---
title: Receive inbound SMS — Guide
description: Atomic claim, near-instant end-to-end, parallel-safe.
url: https://agentnumber.really.com/docs/guides/receive-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.

# Receive inbound SMS

> Atomic claim, near-instant end-to-end, parallel-safe. For OTP flows, prefer the MCP `receive_sms` tool — it long-polls with progress notifications.

## Plain REST

```bash
curl https://agentnumber.really.com/sms/receive \
  -H "authorization: Bearer <token>"
# → 200
# {"messages":[{"id":4821,"from_number":"+15555550199","to_number":"+15555550123","body":"Your code is 123456","created_at":"..."}],"count":1}
```

Returns immediately with whatever's currently undelivered. Each returned row is atomically marked delivered, so a parallel call won't duplicate.

## Long-poll (MCP)

```bash
curl -X POST https://agentnumber.really.com/mcp \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"receive_sms","arguments":{"wait_seconds":30}}}'
```

The MCP tool holds the request open up to `wait_seconds` (default 30, max 120) and emits MCP `notifications/progress` every 20 seconds to keep the client alive. Returns immediately when a message arrives. Near-instant OTP delivery end-to-end.

## History (no mutation)

[`/sms/messages`](/docs/reference/messages) reads from history without touching `delivered_at`. Use this for replay / audit, not for live OTP claim.

## Where to go next

- [Receive reference](/docs/reference/receive) — full schema
- [Messages reference](/docs/reference/messages) — paginated history
- [MCP](/docs/mcp) — long-poll, all tools at once

## 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: [Quickstart](/docs/quickstart) · Next: [Place a call](/docs/guides/place-call) →