Skip to main content
POST
Send an SMS

Authorizations

Authorization
string
header
required

Dashboard JWT token from Clerk

Body

application/json
to
string
required

Phone number. Accepts E.164 (preferred) or display formats and PBX-extension suffixes (x1234, ;ext=1234, ,ext=1234); normalized server-side to E.164 before send.

Required string length: 1 - 64
body
string
required

SMS body text

Required string length: 1 - 1600
webhook_url
string<uri>

DLR callback URL

metadata
object

Custom key-value metadata

test
boolean

When true, marks this send as a throwaway test. The provider call still happens and billing still runs, but the recipient is NOT auto-upserted into the contacts table. Use this for dashboard 'Send Test SMS' flows to avoid polluting the operator's contacts list with verification numbers. TEST-USER P1 / DECISION — TEST_SMS_NO_CONTACT_CREATE_2026_05_28.

validity_period
string

Twilio ValidityPeriod parity. Carrier-level expiry hint after which the SMSC drops the attempt. Suffixed grammar: s (seconds, default), m (minutes), h (hours), d (days). Examples: '30m', '1h', '24h', '2d'. Consumed by Telnyx (valid_until), Jasmin (validity-period), and SMPP (validity_period hours). GAP2_CPaaS_33.

Pattern: ^[1-9][0-9]*[smhd]?$
max_price
number

Twilio MaxPrice parity. Hard per-message USD ceiling. The send is rejected 422 MAX_PRICE_EXCEEDED if the resolved per-unit cost exceeds this cap — useful as an anti-fraud guard on international SMS to premium-rate destinations. Capped at 100 USD per message to defend against units mistakes. GAP2_CPaaS_33.

Required range: 0 < x <= 100
fallback_from
string

Twilio FallbackFrom parity. An optional secondary sender identity recorded on the message as metadata.fallback_from for audit and record-keeping. Same allowed shape as from (E.164 / alphanumeric sender ID / __shared_generic__). Audit-only: the value is stored on the message record and is not currently auto-swapped in on a rejected attempt, so treat it as a record of intent rather than an active carrier-failover retry.

Required string length: 1 - 64

Response

SMS accepted for delivery

SMS accepted for delivery

data
object
meta
object