> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS

> Send and receive SMS messages globally via the Orbit API

# SMS

Send SMS messages worldwide through Orbit's SMPP gateway infrastructure. Orbit connects to tier-1 carriers and aggregators across 190+ countries, handling concatenation, encoding, and delivery tracking automatically.

## Send an SMS

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Hello from Orbit!"
  }'
```

### Response

The endpoint responds with **HTTP 202 Accepted** — the message is persisted and queued for delivery (it has not yet been handed to the carrier). The `id` is a platform message id of the form `msg_` followed by 32 lowercase hex characters (no channel infix); track its lifecycle via [delivery webhooks](/webhooks/overview).

```json theme={null}
{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "sms",
    "segments": 1
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}
```

## Features

* **A2P and P2P messaging** — application-to-person and person-to-person support
* **Global reach** — 190+ countries via Devotel's aggregator network
* **Delivery reports** — real-time status webhooks for every message
* **Concatenated messages** — multi-part SMS handled transparently (up to 10 segments)
* **E.164 validation** — automatic phone number format validation
* **Unicode support** — full GSM-7 and UCS-2 encoding with automatic detection
* **Sender ID** — alphanumeric sender IDs where supported by local regulations

## Message Status Flow

`queued` → `sending` → `sent` → `delivered` (or `failed` / `undelivered`)

Subscribe to status updates via [webhooks](/webhooks/overview) using the `message.sent`, `message.delivered`, and `message.failed` events — one webhook event fires per status transition, each carrying the message `id` and the new `status` value.

## Rate Limits

SMS sends are rate-limited to **100 requests/minute per tenant** by default on the `/messages/sms` endpoint. The limit is keyed per tenant (per organization), not per IP or per plan, so concurrent callers within the same tenant share one pool while separate tenants never affect each other.

Need a higher ceiling? The per-tenant cap is override-able via your organization's messaging settings (`channel_rate_overrides.sms`) — contact support or set it from the dashboard. Exceeding the limit returns `429 Too Many Requests` with the `RATE_LIMITED` error code; see the [Rate Limits guide](/guides/rate-limits) for headers and retry handling.

The same per-channel, per-minute, per-tenant model applies across messaging channels (each independently override-able):

| Channel                            | Default limit (requests/minute) |
| ---------------------------------- | ------------------------------- |
| SMS                                | 100                             |
| WhatsApp                           | 80                              |
| Messenger                          | 80                              |
| LINE                               | 80                              |
| Telegram                           | 80                              |
| Email                              | 200                             |
| MMS                                | 60                              |
| Group MMS (`POST /messages/group`) | 60 (shares the MMS cap)         |
| RCS                                | 50                              |
| Viber                              | 50                              |
| Fax                                | 20                              |

## Pricing

SMS pricing is per-segment and varies by destination country. Check the [pricing page](https://orbit.devotel.io/pricing) or query the `GET /api/v1/pricing/messaging?country=<ISO>` endpoint for real-time rates (the returned `channels` array includes `sms`).