SMS
Send SMS messages and track delivery status through the SMS channel.
The SMS endpoints let you send outbound text messages through a configured SMS use case and track their delivery lifecycle.
Send SMS
POST /v1/sms/
Sends a single SMS message through the messaging service associated with the specified SMS use case.
Before sending, the platform validates that:
The SMS use case exists and is active
At least one phone number is assigned to the use case's sender pool
For US long-code numbers, a verified A2P 10DLC campaign is associated with the use case
The sender number is selected automatically from the use case's sender pool based on configured routing policies (sticky sender, area code geomatch). The chosen sender is not known at send time - it is resolved asynchronously and reported via the status callback.
Request Body
use_case_id
string (UUID)
Yes
ID of the SMS use case to send through
to_phone_number
string
Yes
Destination phone number in E.164 format
message
string
Yes
Message body, 1-1600 characters
Response (201)
id
string (UUID)
Unique identifier for the outbound SMS message
use_case_id
string (UUID)
SMS use case this message was sent through
message_sid
string
External message identifier used for delivery tracking
from_number
string or null
Sender phone number, null until resolved by the messaging service
to_number
string
Destination phone number
body
string
Message body that was sent
num_segments
integer or null
Number of message segments, null until carrier handoff
status
string
Current delivery status: pending, sent, delivered, failed, or undelivered
handed_off_at
string (datetime) or null
When the message was handed off to the carrier
delivered_at
string (datetime) or null
When the carrier confirmed delivery
errored_at
string (datetime) or null
When a delivery error occurred
error_code
integer or null
Error code on failed or undelivered messages
created_at
string (datetime)
When the message record was created
updated_at
string (datetime)
When the message record was last updated
Error Responses
404
SMS use case not found or has been deleted
422
No phone number assigned to the use case
422
No verified A2P campaign for a US long-code sender pool
422
Invalid destination phone number (not a real number or is a landline)
422
Destination phone number has opted out of receiving messages
422
Destination region not permitted for the messaging service
422
The brand registration behind the use case is suspended
Delivery Status Lifecycle
After a message is sent, its status is updated automatically as delivery progresses:
The from_number field is populated once the messaging service selects a sender from the pool, which happens asynchronously after the send request returns.
On carriers without delivery receipt support (some international routes), the lifecycle stops at sent - delivered_at stays null, and handed_off_at is the only post-send signal.
Status Callback Webhook
POST /v1/webhook/twilio/sms-status
This webhook receives delivery status updates from the messaging provider. It is configured automatically on each outbound message.
The webhook validates the request signature using the subaccount credentials before processing. Invalid signatures receive a 403 response. Unknown message identifiers are silently acknowledged with 204.
Status updates are idempotent - duplicate callbacks for the same status transition are safely ignored. Late-arriving status updates that would regress a terminal state (for example, a sent callback arriving after delivered) are also dropped.
204
Status processed successfully, or silently ignored
403
Request signature validation failed
Last updated
Was this helpful?