Send message
send_messageDestructive
Send one SMS from one of your numbers. Set category "marketing" for promotions (the opt-in check applies) and scheduled_at to send later. Quiet hours apply to every message: outside 8am-9pm (8pm in Florida, Maryland and Oklahoma) in the recipient's local time a marketing message is refused and anything else is held until 8am, except one-time codes and replies within 4 hours of their text. In sandbox (test keys), delivery is simulated: +15005550006 delivers, +15005550002 fails, +15005550007 is filtered as spam, +15005550013 delivers after a delay, +15005550016 has no opt-in (see /docs/sandbox).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | ||
| body | Yes | ||
| from | No | One of your numbers, or a sender pool id (pool_...): TextKit picks a pool member, the same one for each recipient every time. Optional when the account has exactly one number for the key's mode. | |
| tags | No | Optional. Your own labels, up to 10 (letters, digits, space _ . : -; up to 32 characters each; lowercased), for example a campaign or a flow. Stored on the message, sent on its webhook events, and reported by GET /v1/deliverability?group_by=tag. Filter with GET /v1/messages?tag=. | |
| media | No | Reserved for MMS; currently returns 400 mms_not_enabled. | |
| consent | No | Optional. How the recipient agreed to your messages. A recurring non-marketing message from a number linked to a registration needs an opt-in on file for that registration; when none is, this records it and the message is sent. Never counts for marketing (use POST /v1/consent with proof). Not with scheduled_at. | |
| category | No | Optional. It can make a message stricter (`marketing`), never looser: what a message is comes from the sending number's registration and its wording ([which messages are marketing](/docs/compliance-checks#which-messages-are-marketing)). A message outside its registration's use case is refused with 403 campaign_mismatch. | |
| customer_id | No | Optional. Attribute to one of your customers. Defaults to the customer the from-number is assigned to; a number assigned to another customer is rejected (400). | |
| quiet_hours | No | Optional. What to do with a message in the recipient's quiet hours: `block` refuses it (403 quiet_hours), `defer` holds it until their next 8:00am. Omitted: the account default (a single marketing send is refused; every other message is held). One-time codes are never held. | |
| scheduled_at | No | Optional. Future ISO timestamp (or epoch ms), up to 30 days out. The message is queued and the response is a scheduled_message object instead of a message. A marketing message scheduled into the recipient's quiet hours is refused now (403 quiet_hours) or, with quiet_hours defer, moved to their next 8:00am; any other message is moved. | |
| shorten_links | No | Optional. Rewrite every http(s) link in `body` to a short link on your active link domain (POST /link-domains), with clicks tracked (`links` on the message, `message.link_clicked` events). The links are checked as you wrote them; segments are counted on the shortened text. Without an active link domain the request is refused with 400 link_domain_required: short links are never put on a shared domain. Works with scheduled_at. | |
| idempotency_key | No | Optional. Retries are already safe: the same call with the same inputs within 10 minutes is done once and answers with the first result. Pass your own key to dedupe across a longer gap, or a new one to repeat an identical call on purpose. | |
| status_callback | No | Optional. Also send this message's status events (message.sent, message.delivered, message.failed, message.blocked) to this https URL, signed with your callback secret (POST /v1/webhooks/callback_secret; 400 callback_secret_required until it exists). Logged and retried like a webhook endpoint, under endpoint `status_callback`. Immediate sends only. |