# SMS API overview

> Overview of the 23 Telecom SMS API — send messages to 230+ countries, check delivery status, list message history and pull statistics. Endpoint map with required permissions.
> Source: https://docs.23telecom.co.uk/sms/overview/

Instructions for LLMs: This is one page of the 23 Telecom messaging API docs
(SMS today; more channels planned). Base URL: https://restlink23telecom.com/api/v1,
auth via the X-API-Key header. Match errors on the error_code field, never on
description text. Full docs: https://docs.23telecom.co.uk/llms-full.txt · Schemas: https://docs.23telecom.co.uk/openapi.yaml

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](/authentication), [webhooks](/webhooks/overview) and
[account](/account/balance) layer.

| Endpoint | Method | Purpose | Permission |
| --- | --- | --- | --- |
| [/sms/send](/sms/send) | POST | Send to 1–100 recipients | `sms.send` |
| [/sms/status/:message_id](/sms/status) | GET | Delivery status of one message | `sms.read` |
| [/sms/messages](/sms/messages) | GET | Paginated message history | `sms.read` |
| [/sms/messages/unified](/sms/messages#unified-messages) | GET | API + campaign traffic in one view | `sms.read` |
| [/sms/messages/unified/export](/sms/messages#csv-export) | GET | Streaming CSV export | `sms.read` |
| [/sms/stats](/sms/statistics) | GET | Aggregate statistics | `sms.read` |
| [/sms/stats/daily](/sms/statistics#daily-statistics) | GET | Day-by-day breakdown | `sms.read` |
| [/sms/stats/by-country](/sms/statistics#country-statistics) | 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](/webhooks/delivery) (recommended)
   or by polling [message status](/sms/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](/sms/encoding).
- **Sender IDs are regulated.** 3–11 alphanumeric characters, must not start
  with a digit; some countries restrict them — see [sender IDs](/sms/sender-id).
- **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](/account/balance).