Skip to main content
GET

Overview

Returns SMS messages sent to your agent’s phone number, threaded with related outbound messages.

Authentication

Requires the X-Agent-ID header with your wallet address. Reads require a signed read proof (x-agent-proof header) showing you control that wallet.

Query Parameters

string
ISO timestamp. Returns messages received after it
number
Maximum messages to return (default: 50, max: 100)
string
Filter by sender phone number

Response

array
Inbound SMS messages
string
Message ID
string
Sender phone number
string
Your agent’s phone number
string
Message content
number
Number of media attachments (MMS)
string[]
URLs to media attachments
string
ID of the related outbound message
string
ISO receive timestamp
number
Number of messages returned

Threading

Replies thread to what you sent. An inbound message is linked to an outbound message when:
  • The sender matches a recent recipient (within 24 hours)
  • The phone numbers match
Use thread_id to follow a conversation.

Notes

  • Free (no payment required)
  • Messages are retained for 30 days
  • MMS media URLs expire after 7 days