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. Pending sends do not support MMS. Send a single message through your sending list. Omit media for SMS, or include hosted attachments for MMS. The message is queued and assigned an opaque, variable-length identifier for tracking. A 201 response confirms queue acceptance; read the message status to check delivery.

Body Parameters

For real trial SMS, send trial_campaign_id instead of list_number and require an Idempotency-Key header. This path accepts only the group selector, to, final body, optional metadata (JSON object, at most 16,384 encoded bytes), and optional wrap_links: false. Body text must be nonempty and at most 4,096 characters. Templates, link wrapping, MMS, pending approval, provider overrides, raw/bulk and schedules are unavailable. A live key with sends.send is required; sandbox, list-restricted and approval-required keys are refused. Trial success returns 201 with success, message_id, status: "queued", trial: true and trial_campaign_id. Reuse the same idempotency key and payload for identical retries, even after an uncertain response. Unknown submission does not establish non-delivery. See trial errors and lifecycle.
string
Account-owned testing group ID for a trial send. Mutually exclusive with list_number.
string
required
Recipient phone number in E.164 format (e.g. +14155551234).
string
Required for ordinary sends: the sending list phone number in E.164 format, belonging to your account. Omit it when using trial_campaign_id.
string
Required for SMS; optional or empty for MMS. An MMS caption may contain up to 4,096 characters. Use the {{messageId}} placeholder to insert the unique message ID into the body at send time.
array
Non-empty array of hosted MMS attachments. Each object requires url and accepts optional content_type and content_id. Omit this field for SMS. See MMS for URL requirements, formats, and examples.
string
Optional MMS subject, up to 66 characters. Requires media.
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 link1 … link99 (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.
string
Interstitial page for every tracked link in this message, shown before the short link redirects. One of none (redirect straight away, even if the referenced SMS offer has its own interstitial), list_default (the sending list’s default interstitial page; a list without one redirects straight away), or custom (the page described by interstitial). Omit it to keep each referenced SMS offer’s own setting. Requires wrap_links: true and at least one {{linkN}} placeholder backed by linkOverrides; applies to all of them, including every customUrl link, so put an opt-out or unsubscribe page behind a tracked link only if you want it shown there too.
object
Custom interstitial page for this message’s tracked links; supplying it implies interstitialMode: "custom", and it must not be empty. Keys, all optional: title, description, cta (button text), meta_title, meta_description (page metadata), meta_image (absolute HTTP(S) URL used for the Open Graph image and the blurred background), meta_favicon (absolute HTTP(S) URL or inline SVG markup), auto_redirect (boolean; continues automatically after a short pause) and redirect_text (the button text while auto-redirecting). Text values are limited to 2,000 characters, meta_image to 2,048 characters, meta_favicon to 4,096 UTF-8 bytes on this endpoint. Unknown keys are rejected. /v2/send-raw mints no tracked links and refuses both fields with 400 interstitial_requires_links.
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. Trackly fills {{contactId}} and {{listContactId}} itself from the recipient’s subscription to the sending list; they resolve to an empty string when the recipient is not on the list and cannot be set through contact_data.
object
Optional key-value metadata dictionary. Ordinary sends currently accept but do not retain this field. Trial sends retain encrypted metadata and include it in events where outgoing-message correlation is proven.

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.
string
"mms" for an MMS request. Omitted for SMS.

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