---
title: SMS
description: Agent Number SMS — send and receive SMS on the same number as voice. Near-instant OTP delivery via long-poll.
url: https://agentnumber.really.com/docs/sms
doc_version: "1.0.0"
last_updated: "2026-05-15"
---

> ## Documentation index
> Fetch the complete documentation index at: https://agentnumber.really.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS

> Send and receive SMS on the same number that handles voice. Near-instant OTP delivery via long-poll. Three REST endpoints, three matching MCP tools.

## Three endpoints

- **Send** — `POST` `/sms/send`. Outbound from your assigned number. Returns the carrier `message_id` once queued. Long messages segment transparently.
- **Receive** — `GET` `/sms/receive`. Returns currently undelivered inbound messages immediately (atomic claim — marks `delivered_at` so a parallel call doesn't double-deliver). For long-poll behavior, use the MCP `receive_sms` tool, which polls this primitive with progress notifications.
- **History** — `GET` `/sms/messages`. Read-only paginated history across both directions. Does **not** mutate `delivered_at`.

## Send your first SMS

```bash
curl -X POST https://agentnumber.really.com/sms/send \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -d '{"to": "+15551234567", "body": "Hello from my agent."}'
# → {"message_id": "msg_...", "status": "queued"}
```

## Receive an OTP

For OTP / 2FA flows, prefer the MCP `receive_sms` tool over the raw endpoint — it long-polls (up to 120 s) with MCP `notifications/progress` events. The REST endpoint here is the underlying primitive: it returns immediately with whatever's currently undelivered, without long-polling.

```bash
curl https://agentnumber.really.com/sms/receive \
  -H "authorization: Bearer <token>"
# → returns immediately with any undelivered messages
# → {"messages": [{...}], "count": 1}
```

## Read message history

```bash
curl "https://agentnumber.really.com/sms/messages?limit=20" \
  -H "authorization: Bearer <token>"
# → {"messages": [...], "next_cursor": "..."}
```

## MCP equivalents

- `send_sms` — same shape as `POST` `/sms/send`
- `receive_sms` — long-polls with progress notifications; near-instant OTP delivery
- `list_messages` — same as `GET` `/sms/messages`

## Endpoints

| Endpoint | Auth | Purpose |
| --- | --- | --- |
| `POST` `/sms/send` | bearer | Send outbound SMS. Returns `{message_id, status}`. |
| `GET` `/sms/receive` | bearer | Immediate-return claim of undelivered inbound; atomic on `delivered_at`. Use MCP `receive_sms` for long-poll. |
| `GET` `/sms/messages` | bearer | Read-only paginated history (cursor-based). |

## Practical notes

- **Same number for SMS + voice.** One subscription, both channels.
- **Real cellular, not VOIP.** Two-factor codes deliver. Numbers are issued on REALLY's live wireless spectrum.
- **Multiple agents** can share one number by reusing the same bearer token across clients. `/sms/receive` atomically claims messages so no two callers see the same SMS twice. A fresh token rotation goes through [/auth recovery](/docs/auth), which revokes all prior tokens.
- **History vs receive.** Use `/sms/messages` to read; `/sms/receive` to claim. They serve different jobs.

## Common errors

| Status | Error | Meaning |
| --- | --- | --- |
| `400` | `invalid_request` | Body malformed or missing required fields |
| `401` | `unauthorized` | Missing, invalid, revoked, or expired bearer — see [Auth](/docs/auth) |
| `500` | `subscription_missing` | Subscription record not found server-side |
| `500` | `slot_inventory_missing` | Device-slot inventory row missing |
| `502` | `phone_node_error` | Phone node (hardware adapter) returned non-2xx |
| `503` | `subscription_missing_slot` | Subscription has no assigned slot |

## Sitemap

- [Overview](/docs/)
- [Quickstart](/docs/quickstart)
- [Authentication](/docs/auth)
- [SMS](/docs/sms)
- [Voice](/docs/voice)
- [MCP](/docs/mcp)
- [Payment](/docs/payment)

See the full [sitemap.md](/sitemap.md) for the complete index of docs pages.

---

← Previous: [MCP](/docs/mcp) · Next: [Voice](/docs/voice) →