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

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.

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

Read message history

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

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, which revokes all prior tokens.
• History vs receive. Use /sms/messages to read; /sms/receive to claim. They serve different jobs.

Common errors

llms.txt OpenAPI MCP server card x402.json mpp.json Agent card Agent skills SKILL.md sitemap.xml Glossary