v2

latestOpenAPI 3.1.02026-08-075421692.0 MB

SMS

Send an SMS/MMS

Sends an SMS (or MMS when mediaUrls is set) from one of your SMS-enabled numbers. At least one of text / mediaUrls is required. Both numbers are normalized to E.164, so from matches regardless of formatting and replies thread into the same inbox conversation.

US numbers must have an approved carrier registration (/v1/sms/registrations) before messages deliver.

Idempotency: send an Idempotency-Key header to make retries safe: same key + same body replays the original response instead of sending a second message; same key + different body returns 422; a key still in flight returns 409.

post/v1/sms/messages

Headers

Idempotency-Keystring

Optional client-generated unique key (e.g. a UUID) that makes retries safe. Same key + same body replays the original response; same key + different body → 422; key still processing → 409.

Request body

fromstring required

One of your SMS-enabled numbers (E.164; formatting is normalized).

tostring required

Recipient number (E.164).

textstring

Message body. Required unless mediaUrls is set. Max 10 SMS segments (1530 GSM-7 or 670 unicode characters).

mediaUrlsstring[]

Public media URLs to attach (sends as MMS). Max 10.

sendAtstring date-time

Optional. Schedule the send for a future time (ISO 8601 with offset, e.g. 2026-08-01T12:00:00Z). Must be in the future. The message is queued and the message.delivered webhook fires when it actually sends.

Response

Message accepted for delivery.

idstring

Message ID

conversationIdstring

Inbox conversation the message was threaded into.

status'sent'