SMS API overview

The SMS API covers the full lifecycle of a message: send → track → analyze. It is the first channel of the 23 Telecom messaging platform — additional channels (Viber and more) will appear here alongside SMS, sharing the same authentication, webhooks and account layer.

Endpoint	Method	Purpose	Permission
/sms/send	POST	Send to 1–100 recipients	sms.send
/sms/status/:message_id	GET	Delivery status of one message	sms.read
/sms/messages	GET	Paginated message history	sms.read
/sms/messages/unified	GET	API + campaign traffic in one view	sms.read
/sms/messages/unified/export	GET	Streaming CSV export	sms.read
/sms/stats	GET	Aggregate statistics	sms.read
/sms/stats/daily	GET	Day-by-day breakdown	sms.read
/sms/stats/by-country	GET	Per-country breakdown	sms.read

How delivery works

your server ──POST /sms/send──▶ 23 Telecom ──▶ carrier ──▶ handset
     ▲                              │
     └──── webhook (DLR) ◀──────────┘

1. You send a message; the API responds immediately with a message_id per recipient and a cost/encoding summary.
2. The carrier returns a delivery report (DLR) — typically within seconds.
3. You receive the final status by webhook (recommended) or by polling message status.

Things worth knowing up front

• E.164 numbers. Always send phone numbers as +<country><number>, e.g. +447911123456.
• Encoding affects cost. One emoji switches the whole message from GSM-7 (160 chars/segment) to UCS-2 (70 chars/segment) — see encoding & segments.
• Sender IDs are regulated. 3–11 alphanumeric characters, must not start with a digit; some countries restrict them — see sender IDs.
• Batch sends are atomic. A multi-recipient request either fully queues or fails as a whole (500 DB_ERROR) — safe to retry, no partial sends.
• Balance is checked before sending. Requests that would exceed your balance return 402 INSUFFICIENT_BALANCE with cost details — see balance.