Skip to main content
POST
Keys requiring send approval receive 403 confirmation_required for direct sends. Use pending sends for approved single or bulk SMS; raw sends have no approval workflow. Send a single SMS message through your sending list. The message is queued for delivery and assigned an opaque, variable-length message identifier for tracking.

Body Parameters

string
required
Recipient phone number in E.164 format (e.g. +14155551234).
string
required
Sending list phone number in E.164 format. Must belong to your account.
string
required
Message body text. Use the {{messageId}} placeholder to insert the unique message ID into the body at send time.
Enables link processing for this message. Send the JSON value true or false. A non-empty linkOverrides object requires literal true; other types return invalid_wrap_links. Raw URLs typed into body are still not auto-shortened — only {{linkN}} placeholders resolved through linkOverrides are. For a click-tracked link without placeholders, create it via the Shorten Link endpoint and put the returned short URL in your body.
Per-placeholder link targets, keyed link1link99 (max 10 entries). Each entry sets exactly one of offerId (an active account-owned SMS offer), partnershipOfferId (an active, account-owned offer with offer management enabled; requires the Partnerships product), or customUrl (an absolute HTTPS URL of at most 2,048 characters on a public hostname, not an IP literal). A customUrl authority must not contain macros. Each referenced {{linkN}} is replaced with a freshly minted short URL; body placeholders without a matching override remain unchanged, and unreferenced entries create no affiliate or offer-access state. Requires wrap_links: true. productId is not supported.
object
Optional per-contact data for macro substitution. Supports first_name (string), last_name (string), custom_fields (object), and timezone (string). These values are used to populate template variables like {{first_name}} in the message body.
object
Optional key-value metadata dictionary. Currently accepted but not stored or returned — the endpoint reads this field and then discards it, so it cannot yet be used to correlate messages with your own systems.

Response Fields

boolean
Whether the message was successfully queued.
string
An opaque, variable-length message identifier for tracking delivery and clicks.
string
Current message status. Will be "queued" on successful submission.

Examples

Error Codes

Authenticated requests can also fail with 401 invalid_credentials, 403 account_suspended, or 429 rate_limited — see Error Codes.

Next Steps

Campaign Execution

How messages flow from queue to delivery

Create Contact

Add contacts before sending