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
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)
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 reads from history
without touching delivered_at. Use this for replay
/ audit, not for live OTP claim.
Where to go next
- Receive reference — full schema
- Messages reference — paginated history
- MCP — long-poll, all tools at once