Messaging
This guide covers message submission, status tracking, cost preview, segment encoding, and operational guardrails.
Submitting a message
Via account
POST /v1/accounts/{accountId}/messages Authorization:
Bearer eyJ... (or X-Api-Key) Content-Type: application/json
{
"subaccountId": "00000000-0000-0000-0000-000000000001",
"to": "+15551234567",
"body": "Your code is 123456.",
"from": "+18005550100"
}
Via subaccount
POST /v1/subaccounts/{subaccountId}/messages Authorization:
Bearer eyJ... (or X-Api-Key)
Response (201 Created):
{
"messageId": "...",
"status": "queued",
"segmentCount": 1,
"encoding": "gsm7",
"estimatedCost": 0.008
}
Message status lifecycle
| Status | Meaning |
|---|---|
queued |
Accepted, awaiting dispatch |
dispatched |
Submitted to carrier |
delivered |
Confirmed delivery receipt from carrier |
undelivered |
Carrier confirmed non-delivery |
failed |
Internal error during dispatch |
GET /v1/accounts/{accountId}/messages/{messageId}
GET /v1/accounts/{accountId}/messages/{messageId}/transition
Segment preview
POST /v1/messages/segments/preview
Content-Type: application/json
{
"body": "Your order# 123456 is ready for pickup at 123 Main St."
}
Response:
{
"segmentCount": 1,
"encoding": "gsm7",
"characterCount": 51,
"charactersPerSegment": 160
}
Messages with non-GSM characters switch to UCS-2, reducing per-segment capacity from 160 to 70 characters.
Message cost
GET /v1/billing/message-costs
GET /v1/billing/message-costs/channels
GET /v1/billing/message-costs/detail
Quota enforcement
Returns
429 Too Many Requests
when quota is exhausted.
GET /v1/quota/subaccounts/{subaccountId}
Templates
POST /v1/accounts/{accountId}/templates/{templateId} # create
POST /v1/accounts/{accountId}/templates/{templateId}/render # preview substitution
Routing policy
GET /v1/subaccounts/{subaccountId}/routing-policy
POST /v1/subaccounts/{subaccountId}/routing-policy/preview
Opt-out management
POST /v1/user/subaccounts/{subaccountId}/opt-out
GET /v1/user/subaccounts/{subaccountId}/opt-outs
Messages to opted-out recipients are blocked at dispatch.