Willitsend

willitsend

Your AI agent sends texts. Carriers silently drop the non-compliant ones, and the API never tells you. willitsend is the missing check between the model and the carrier: a deterministic preflight for outbound SMS/iMessage that catches silent filtering, segment blowups, and dropped iMessage features before you spend the send.

[Try it in the browser](https://abryfs.github.io/willitsend/): runs client-side, nothing leaves the page.

npx -y -p github:abryfs/willitsend willitsend-cli "Hey! Your appointment is tomorrow at 2pm." --first-message

Verdict: BLOCK

Segments: 1 (gsm7, 41 septets) Channel: unknown [BLOCK] first-message.opt-out: First message doesn't include opt-out instructions (e.g. "Reply STOP to unsubscribe"). Carriers may silently filter first messages that lack one, with no API error. Fix: Append "Reply STOP to unsubscribe." to the message body. Source: https://docs.agentphone.ai/documentation/reference/messaging-rate-limits#first-message-requirements [WARN] first-message.opt-in: No opt-in acknowledgment language found … [INFO] first-message.brand: No brand_name was provided …

The problem

Messaging APIs report "sent" when a message reaches the downstream carrier, not when it reaches a phone. AgentPhone's rate-limit docs spell out the consequence: first messages that skip brand identification, opt-in acknowledgment, or opt-out instructions "may be silently filtered by carriers. The API will not return an error."

AI agents now send texts autonomously, and nothing sits between the model and the carrier. An agent that drops the opt-out line gets no error and no delivery. An agent that adds one emoji turns a 160-character message into three billable segments and never notices.

willitsend is the missing check: a deterministic, stateless lint for a draft message. Text and context in, verdict and evidence out. It sends nothing and stores nothing.

sequenceDiagram

participant A as AI agent participant W as willitsend participant API as Messaging API participant C as Carrier participant P as Phone

rect rgba(255,69,58,0.08) note over A,P: without preflight A->>API: send_message (no opt-out language) API-->>A: "sent" ✓ C--xP: silently filtered. no error, no delivery end

rect rgba(52,199,89,0.08) note over A,P: with preflight A->>W: preflight_message(draft, context) W-->>A: BLOCK · missing opt-out · fix + citation A->>W: preflight_message(fixed draft) W-->>A: PASS A->>API: send_message API-->>A: "sent" ✓ C->>P: delivered end

Why not just prompt the rules into your agent?

A fair question: AgentPhone's docs are agent-readable, so you could feed them into every generation call and ask the model to comply. Two things break, and one gets expensive:

1. Generation is probabilistic; verification is deterministic. A model with the rules in context complies *usually*. This checker returns the same verdict every time, and its failure mode is a visible finding rather than a silently filtered message. Compose-time guidance and pre-send verification are complements — this repo ships both (the agent skill is the compose-time half).
2. Models can't do segment math. Septet counting, GSM-7 extension characters, encoding flips from one smart quote, placement-aware packing — token-based models are structurally bad at exactly this arithmetic. No amount of prompting fixes it; a 300-line deterministic function does.
3. The token math, measured (char-count/4 heuristic on the actual pages, July 2026):

Roughly 30× fewer tokens per message in default mode — several hundred× in concise mode — and the checker's own compute rounds to zero (~4µs locally, no API). If you compress the rules into your system prompt instead — our skill file does, at ~950 tokens — you keep the compose-time benefit but still have no verifier and no segment math. Bulk senders feel this most: the tool exists precisely for AI agents sending texts at volume.

Quickstart

As an MCP tool (Claude Code):

claude mcp add willitsend -- npx -y -p github:abryfs/willitsend willitsend-mcp

or in any MCP client config:

{

"mcpServers": { "willitsend": { "command": "npx", "args": ["-y", "-p", "github:abryfs/willitsend", "willitsend-mcp"] } } }

For AI agents — paste this block into your agent (or point it at this README):

Install the willitsend MCP server (pre-send SMS/iMessage lint, no API key needed):

• Claude Code: run claude mcp add willitsend -- npx -y -p github:abryfs/willitsend willitsend-mcp
• Any other MCP client: add {"command": "npx", "args": ["-y", "-p", "github:abryfs/willitsend", "willitsend-mcp"]} to its MCP server config.

Then, before every send_message (or equivalent) call, call preflight_message with the draft body, is_first_message_to_contact (true/false when known), and brand_name. Treat verdict "block" as do-not-send: apply the returned fix strings and re-run until pass. Treat "needs_context" as a signal to determine whether this is a first message (check conversation history), never as permission to send. For high-volume loops pass response_format: "concise" (~4 tokens on pass).

No API key required. Set AGENTPHONE_API_KEY if you want a live iMessage/SMS capabilities lookup for phone-number destinations; without it the tool runs offline. The config above installs straight from this repo (a prepare script builds on install) — nothing to sign up for. willitsend also publishes to npm and the MCP Registry under the server name io.github.abryfs/willitsend; once a release is cut, registry-aware clients can add it by name and npx -y willitsend starts the server directly. See docs/publishing.md for the release runbook.

As a library (npm install github:abryfs/willitsend):

import { preflight } from "willitsend";

const report = preflight({ body: "Acme: thanks for signing up. Your order shipped. Reply STOP to unsubscribe.", is_first_message_to_contact: true, brand_name: "Acme", });

report.verdict; // "pass" | "warn" | "block" | "needs_context" report.findings; // each with severity, fix, and a citation URL report.trace.segments; // { encoding, units, segments, perSegment, ... }

As a CLI: npx -y -p github:abryfs/willitsend willitsend-cli --help (or npx -y -p willitsend willitsend-cli once installed from npm). Exit codes: 0 pass/warn, 1 block, 2 needs context, 3 usage error. It drops into CI or a shell pipeline as-is.

What it checks

Rules come in two labeled tiers. Rules sourced from AgentPhone's own documentation can block. Industry-sourced rules warn at most, because a keyword heuristic has no business vetoing your send.

The verdict model

A finding that depends on context you didn't supply doesn't pretend to be certain. If you never say whether this is the first message to a contact, the opt-out rule reports conditionally and the verdict is needs_context. You get no fake pass and no fake block.

flowchart LR

F[findings] --> B{any block finding with known context?} B -- yes --> BLOCK B -- no --> C{any block finding waiting on context?} C -- yes --> NC[NEEDS_CONTEXT] C -- no --> W{any warning?} W -- yes --> WARN W -- no --> PASS

Every report also carries a send trace: destination classification, assumed channel (iMessage/SMS/MMS), full segment math (encoding, septet and code-unit counts, placement-aware per-segment packing), and, given a 10DLC campaign tier, what this message costs against published daily segment caps.

Benchmarks

Reproduce every number here from the repo; none of them require an account.

• Segment-math parity: agrees with Twilio's reference segment calculator on encoding and segment count across a frozen 126-vector corpus: GSM-7/UCS-2 boundaries, extension characters, emoji, ZWJ sequences, and a deterministic fuzz sweep. The corpus and suite live in test/parity.test.ts; run npm test.
• Latency: median ~4µs per message, ~100,000 messages/second on one thread (Node 22, Apple Silicon laptop; single-pass code-point tables, zero per-character allocation). Run npm run bench on yours. Preflighting ev