Preflight a message before sending
preflight_messageValidate outbound SMS/iMessage drafts before sending to catch carrier-filtering risks, segment blowups, and dropped iMessage effects. Returns a verdict with actionable fixes.
Instructions
Analyzes (lints) a draft SMS/iMessage BEFORE you send it — it sends nothing itself, makes no delivery attempt, and has no side effects. Call this first, before send_message or any other messaging tool, on every outbound draft. Returns: a verdict (pass, warn, block, or needs_context — block-severity issues that depend on context you didn't provide, like whether this is the first message to this contact); a list of findings, each with a severity, a stable rule id, a plain-language explanation, an optional concrete fix, and a citation URL (AgentPhone docs, CTIA, or Twilio guidelines) backing the rule; and a send trace with the destination classification, the assumed delivery channel (imessage/sms/mms/unknown), SMS segment math (encoding, segment count), and — given a 10DLC campaign_type — a daily-quota illustration. Use it to catch carrier-filtering risks (missing opt-out language, missing brand identification, missing opt-in wording on first messages), invalid iMessage send_style values, oversized media carousels, and GSM-7/UCS-2 segment blowups from stray unicode before spending a real send. Every finding's fix field is directly actionable: apply it to the draft verbatim (e.g. append the exact quoted sentence), then call preflight_message again — loop until the verdict is pass. Never treat needs_context as permission to send; supply the missing context and re-check.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The exact message text to preflight. Pass an empty string for a media-only send. This text is used only for local analysis — the tool never stores or forwards it anywhere. | |
| to_number | No | Single destination: E.164 phone number (e.g. +15551234567), email (iMessage only), a 5-6 digit short code, or a grp_ group id. Omit when using `recipients` for a multi-recipient group. | |
| brand_name | No | Sender brand or company name that should be identifiable in a first message. Without it the brand-identification check degrades to advisory only. | |
| media_urls | No | Media attachment URLs. 2-20 entries triggers an iMessage carousel; check the returned findings for carousel-size warnings on other channels. | |
| recipients | No | 2+ destinations to create a new iMessage group (iMessage only, never delivers as SMS). Do not combine with to_number. | |
| send_style | No | iMessage-only visual send effect (e.g. "confetti", "slam"). Silently dropped outside iMessage — flagged unless the channel is confirmed iMessage. | |
| campaign_type | No | 10DLC campaign tier, if known, to attach a static daily-send-cap illustration to the trace. | |
| response_format | No | Output size. "detailed" (default): full messages, fixes, and citation URLs. "concise": one line per finding (severity, rule, fix), ~10x fewer tokens — same engine, same verdict, everything needed to act; use it for high-volume loops. | |
| reply_to_message_id | No | iMessage-only threaded reply target message id. | |
| destination_line_type | No | Destination phone line type, if known from an external lookup. Never guess this from the number itself — VoIP lines often have unreliable iMessage/SMS delivery. | |
| destination_capabilities | No | Known delivery capabilities for the destination, if you already looked them up. Passing this explicitly always takes precedence over — and skips — this server's own optional lookup. | |
| is_first_message_to_contact | No | Whether this is the first outbound message ever sent to this contact. Set true or false when you know it — first messages carry stricter compliance rules (opt-out language, brand identification, opt-in wording). Leave unset only if genuinely unknown; the tool then reports affected findings as conditional instead of asserting them (verdict needs_context). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| trace | Yes | ||
| verdict | Yes | ||
| findings | Yes |