Summary
Send an SMS from the inbox number Requires message_send. POST returns HTTP 409 outbound_not_registered. HTTP 409 phone_number_not_found when the inbox has no active number. A recipient who replied STOP returns HTTP 409 recipient_opted_out until they reply START. The first message to a recipient adds an opt-out footer. HELP and STOP as the whole body return HTTP 400 reserved_keyword. SHAFT content returns HTTP 400 shaft_blocked. A URL shortener returns HTTP 400 short_link. The body, including the footer, must be 320 characters or fewer (HTTP 400 body_too_long). Outbound segments past the monthly allowance return HTTP 402 plan_limit_exceeded with resource sms_segments. Starter allowance is 100 segments per active number. Pro allowance is 1,500 plus 100 for each active number past the 3 included numbers. Purchased segment packs add 500 each when SMS billing is on. A paused inbox is HTTP 403 inbox_paused. The stored message has channel sms. A later Twilio status callback sets status to delivered, undelivered, or failed, and delivery_events carries the numeric error code. client_id and Idempotency-Key follow the send rules. HTTP 404 not_found when SMS is off.
Request
{
"to": "+14155550100",
"text": "Hello",
"client_id": "sms-1"
}Response
HTTP 201. Sample values illustrate the schema.
{
"id": "inb_example",
"inbox_id": "inb_example",
"thread_id": "thr_example",
"direction": "inbound",
"from": "ada@example.com",
"to": [
"string"
],
"subject": "Hello",
"text": "Tuesday works.",
"html": "string",
"extracted_text": "string",
"extracted_html": "string",
"preview": "string",
"status": "queued",
"channel": "sms",
"segments": 1,
"otp_candidates": [
"string"
],
"delivery_events": [
{
"type": "string",
"recipient": "string",
"created_at": "2026-10-18T12:00:00.000Z",
"detail": "string"
}
],
"cc": [
"string"
],
"bcc": [
"string"
],
"reply_to": "string",
"in_reply_to": "string",
"references": [
"string"
],
"labels": [
"string"
],
"auth": {
"spf": "string",
"dkim": "string",
"dmarc": "string"
}
}Errors
- HTTP 409 outbound_not_registered
- HTTP 409 phone_number_not_found
- HTTP 409 recipient_opted_out
- HTTP 400 reserved_keyword
- HTTP 400 shaft_blocked
- HTTP 400 short_link
- HTTP 400 body_too_long
- HTTP 402 plan_limit_exceeded
- HTTP 403 inbox_paused
- HTTP 404 not_found
- HTTP 400 missing_body
- HTTP 400 invalid_e164
- HTTP 402 sms_segments
- HTTP 404 inbox_not_found
Idempotency
Idempotency-Key is 1 to 256 characters of letters, digits, and - . _ ~. The same key and the same request within 24 hours returns the original response with HTTP 200 and Idempotent-Replayed: true. A different request is HTTP 409 idempotency_key_conflict. A second call while the first is running is HTTP 409 idempotency_request_in_progress. An empty or invalid key is HTTP 400 invalid_idempotency_key. client_id is checked first when both are set.