> ## 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 Inbound Emails

> Poll for inbound emails with minimal, actionable data

## 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 8601 timestamp to filter emails received after this time
</ParamField>

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

<ParamField query="include_body" type="boolean" optional default="false">
  Whether to include email body and attachments
</ParamField>

## Response

<ResponseField name="emails" type="array">
  Array of inbound email objects

  <Expandable title="Email Object">
    <ResponseField name="id" type="string">
      Unique email identifier
    </ResponseField>

    <ResponseField name="from" type="string">
      Sender email address
    </ResponseField>

    <ResponseField name="subject" type="string">
      Email subject
    </ResponseField>

    <ResponseField name="received_at" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="thread_id" type="string">
      Thread identifier for conversation tracking
    </ResponseField>

    <ResponseField name="body" type="string" optional>
      Plain text body (only if `include_body=true`)
    </ResponseField>

    <ResponseField name="body_html" type="string" optional>
      HTML body (only if `include_body=true`)
    </ResponseField>

    <ResponseField name="attachments" type="array" optional>
      Array of attachment objects (only if `include_body=true`)

      <Expandable title="Attachment Object">
        <ResponseField name="filename" type="string">
          Attachment filename
        </ResponseField>

        <ResponseField name="content_type" type="string">
          MIME type (e.g., `image/png`)
        </ResponseField>

        <ResponseField name="size" type="number">
          File size in bytes
        </ResponseField>

        <ResponseField name="content" type="string">
          Base64-encoded file content
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

<ResponseField name="has_more" type="boolean">
  Whether there are more emails available
</ResponseField>

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

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://win.oneshotagent.com/v1/tools/inbox?include_body=true&limit=10",
    {
      headers: {
        "X-Agent-ID": agentUuid,
      },
    },
  );
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "emails": [
      {
        "id": "email_123",
        "from": "sender@example.com",
        "subject": "Re: Your inquiry",
        "body": "Thanks for reaching out!",
        "received_at": "2025-12-28T12:00:00Z",
        "thread_id": "thread_abc",
        "attachments": [
          {
            "filename": "document.pdf",
            "content_type": "application/pdf",
            "size": 102400,
            "content": "JVBERi0xLjQK..."
          }
        ]
      }
    ],
    "count": 1,
    "has_more": false,
    "agent_id": "agent_xyz"
  }
  ```
</ResponseExample>

## Notes

* Only essential fields are returned (no verbose headers or metadata)
* Use `since` parameter for efficient polling
* Attachments are base64-encoded for easy processing
* Thread tracking via `thread_id` for conversation context