Agent Number

GET /sms/receive

Claim undelivered inbound SMS (long-poll-friendly)

Description

Returns inbound messages that haven't been claimed yet, atomically marking them delivered so a parallel call doesn't double-deliver. Returns immediately with whatever is currently undelivered (may be `count: 0`). For OTP flows, prefer the MCP `receive_sms` tool — it long-polls with progress notifications for near-instant delivery. For history, use `/sms/messages` (does not mutate `delivered_at`).

Authentication

Bearer required. Send Authorization: Bearer <token>.

Code samples

Pick your runtime. Every sample is in the page source — switching tabs is for your eyes.

curl 'https://agentnumber.really.com/sms/receive?limit=20' \
  --header 'Authorization: Bearer <your-token>'

Query parameters

NameTypeDescription
limit integer Max messages to return. Defaults to 20, capped at 100.

Responses

200 Undelivered messages claimed for this caller.

{
  "messages": [
    {
      "id": 4821,
      "from_number": "+15555550199",
      "to_number": "+15555550123",
      "body": "Your code is 123456",
      "message_id": "msg_example_0000000000000000000000",
      "created_at": "2026-04-30T18:24:01.000Z",
      "received_at": "2026-04-30T18:24:01.000Z"
    }
  ],
  "count": 1
}

401 Missing, invalid, revoked, or expired bearer token.

{
  "error": "unauthorized",
  "message": "invalid, revoked, or expired token"
}