> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List SMS Inbox

> List inbound SMS messages received by your agent

## Overview

Retrieve SMS messages that have been sent to your agent's phone number. Messages are automatically threaded with related outbound messages.

## Authentication

Requires `X-Agent-ID` header with your wallet address.

Reads return private, per-agent data, so they are protected by a signed **read proof** (`x-agent-proof` header) proving you control that wallet. The OneShot SDK signs and sends this automatically (TypeScript ≥ 0.25.0, Python ≥ 0.17.0). This is rolling out in log-only mode — requests without the proof still succeed today and will be rejected once enforcement is enabled; raw HTTP callers should start sending it. See [Read Proof Authentication](/sdk/overview#read-authentication).

## Query Parameters

<ParamField query="since" type="string" optional>
  ISO timestamp to filter messages received after this time
</ParamField>

<ParamField query="limit" type="number" optional>
  Maximum messages to return (default: 50, max: 100)
</ParamField>

<ParamField query="from" type="string" optional>
  Filter by sender phone number
</ParamField>

## Response

<ResponseField name="messages" type="array">
  Array of inbound SMS messages
</ResponseField>

<ResponseField name="messages[].id" type="string">
  Unique message ID
</ResponseField>

<ResponseField name="messages[].from" type="string">
  Sender phone number
</ResponseField>

<ResponseField name="messages[].to" type="string">
  Your agent's phone number
</ResponseField>

<ResponseField name="messages[].body" type="string">
  Message content
</ResponseField>

<ResponseField name="messages[].num_media" type="number">
  Number of media attachments (MMS)
</ResponseField>

<ResponseField name="messages[].media_urls" type="string[]">
  URLs to media attachments
</ResponseField>

<ResponseField name="messages[].thread_id" type="string">
  ID linking to related outbound message
</ResponseField>

<ResponseField name="messages[].received_at" type="string">
  ISO timestamp when received
</ResponseField>

<ResponseField name="count" type="number">
  Number of messages returned
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://win.oneshotagent.com/v1/tools/sms/inbox?limit=10" \
    -H "X-Agent-ID: 0xYourWalletAddress"
  ```

  ```typescript SDK theme={null}
  import { OneShot } from "@oneshot-agent/sdk";

  const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

  // List recent messages
  const inbox = await agent.smsInboxList({ limit: 10 });

  for (const msg of inbox.messages) {
    console.log(`From ${msg.from}: ${msg.body}`);
  }

  // Filter by sender
  const fromCustomer = await agent.smsInboxList({
    from: "+14155551234",
    limit: 20,
  });

  // Get messages since a timestamp
  const recent = await agent.smsInboxList({
    since: "2024-01-01T00:00:00Z",
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "messages": [
      {
        "id": "msg_abc123",
        "from": "+14155551234",
        "to": "+14151234567",
        "body": "Yes, I'd like to confirm my appointment",
        "num_media": 0,
        "media_urls": null,
        "thread_id": "msg_outbound_xyz",
        "related_outbound_id": "msg_outbound_xyz",
        "received_at": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-15T10:30:00Z"
      },
      {
        "id": "msg_def456",
        "from": "+14155559876",
        "to": "+14151234567",
        "body": "Thanks for the update!",
        "num_media": 1,
        "media_urls": ["https://media.oneshotagent.com/..."],
        "thread_id": null,
        "related_outbound_id": null,
        "received_at": "2024-01-15T09:15:00Z",
        "created_at": "2024-01-15T09:15:00Z"
      }
    ],
    "count": 2
  }
  ```
</ResponseExample>

## Threading

Inbound messages are automatically linked to outbound messages when:

* The sender matches a recent recipient (within 24 hours)
* The phone numbers match

Use `thread_id` to track conversation flows.

## Notes

* This endpoint is free (no payment required)
* Messages are retained for 30 days
* MMS media URLs expire after 7 days