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

# Get Agent Inbox

> List the conversations that reached an agent by email or WhatsApp

Agents can be reached on inbound channels: email (when an email trigger is configured) and WhatsApp (on a user's personal Omni). This endpoint lists those conversations - the agent's inbox - newest first, with filters for channel, date range and title text.

It is agent-wide: every sender's conversation with this agent, not just the caller's. For an agent's full task history across all sources, use [Get Agent Tasks](/api-reference/v1/agents/get-agent-tasks) instead.

## Path Parameters

<ParamField path="agent_id" type="string" required>
  Unique identifier of the agent (UUID format)
</ParamField>

## Query Parameters

<ParamField query="source" type="string">
  Comma-separated channels to include: `email`, `whatsapp`. Defaults to every channel enabled on the agent. Asking for a channel the agent does not have returns `400`.
</ParamField>

<ParamField query="from_date" type="string">
  Only conversations created at or after this ISO date/datetime. A bare date (`2026-08-01`) covers that whole UTC day.
</ParamField>

<ParamField query="to_date" type="string">
  Only conversations created at or before this ISO date/datetime. A bare date covers the whole day.
</ParamField>

<ParamField query="q" type="string">
  Case-insensitive text matched against conversation titles.
</ParamField>

<ParamField query="limit" type="integer" default={20}>
  Maximum conversations to return (1-50).
</ParamField>

## Response

<ResponseField name="items" type="array">
  Inbound conversations, newest first

  <Expandable title="Conversation Object">
    <ResponseField name="id" type="string">
      Conversation (task) id - pass it to [Get Task Thread](/api-reference/v1/tasks/get-thread) to read the messages
    </ResponseField>

    <ResponseField name="source" type="string">
      Inbound channel: `email` or `whatsapp`
    </ResponseField>

    <ResponseField name="title" type="string">
      Conversation title
    </ResponseField>

    <ResponseField name="status" type="string">
      Execution status: `pending`, `executing`, `paused`, `error`, `failed`, `completed`, or `stopped`
    </ResponseField>

    <ResponseField name="user_id" type="string">
      Profile id or address of whoever started the conversation (nullable)
    </ResponseField>

    <ResponseField name="sender" type="string">
      Sender email address, resolved from the profile when the row carries an id (nullable)
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO timestamp of the first message
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO timestamp of the last update
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sources_enabled" type="array">
  Inbound channels enabled on this agent. An empty array means the agent has no inbox at all - clients should hide the surface rather than show an empty list.
</ResponseField>

<ResponseField name="total" type="integer">
  Number of matching conversations before `limit` was applied
</ResponseField>

## Example Requests

### Everything in the inbox

```bash theme={"dark"}
curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/agents/<agent-id>/inbox"
```

### Search one channel

```bash theme={"dark"}
curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/agents/<agent-id>/inbox?source=email&q=invoice&limit=10"
```

### A date range

```bash theme={"dark"}
curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/agents/<agent-id>/inbox?from_date=2026-08-01&to_date=2026-08-03"
```

## Example Response

```json theme={"dark"}
{
  "items": [
    {
      "id": "df716857-0c93-4ec9-9b91-bbe1b9879b59",
      "source": "email",
      "title": "Invoice question",
      "status": "completed",
      "user_id": "92310d0c-feda-4e8d-82df-a5320247b10b",
      "sender": "dan@acme.com",
      "created_at": "2026-08-03T07:41:12.426253Z",
      "updated_at": "2026-08-03T07:41:44.108221Z"
    }
  ],
  "sources_enabled": ["email"],
  "total": 1
}
```

## Use Cases

* **Inbox view**: render everything people sent an agent, across channels
* **Lookup**: find the conversation a specific person or subject started
* **Triage**: filter by date range to review what arrived while nobody was watching

## Notes

* Only top-level conversations are listed; sub-tasks spawned inside a conversation are excluded
* Each channel is queried separately and the results merged, so a channel that is temporarily unavailable degrades the list rather than failing it - the request only errors when every requested channel fails
* `sender` is null when the conversation came from an identity with no email on file
* The agent itself can list the same conversations in chat, so "what emails did you get?" is answered from real data rather than guessed

## See Also

* [Get Agent Tasks](/api-reference/v1/agents/get-agent-tasks) - all tasks for an agent, any source
* [Get Task Thread](/api-reference/v1/tasks/get-thread) - the messages inside one conversation
* [List Tasks](/api-reference/v1/tasks/list-tasks) - tasks across all agents


## OpenAPI

````yaml GET /v1/agents/{agent_id}/inbox
openapi: 3.1.0
info:
  title: xpander.ai API Service
  description: |2-

        The xpander.ai API Service provides a unified REST API for managing AI agents,
        executing tasks, managing knowledge bases, and integrating with external systems.
        
        Features:
        - Agent Management: Create, update, deploy, and delete AI agents
        - Task Execution: Invoke agents with support for sync, async, and streaming modes
        - Knowledge Bases: Manage knowledge bases and documents for RAG workflows
        - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
        - MCP Integration: Model Context Protocol support for standardized AI interactions
        
        Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/agents/{agent_id}/inbox:
    get:
      tags:
        - API v1
        - Agents
        - Agents CRUD
      summary: Get Agent Inbox
      description: >-
        List conversations that reached this agent by email or WhatsApp, newest
        first.
      operationId: Get_Agent_Inbox_v1_agents__agent_id__inbox_get
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
        - name: source
          in: query
          required: false
          schema:
            type: string
            description: >-
              Comma-separated channels to include (email, whatsapp). Defaults to
              every channel enabled on the agent.
            default: ''
            title: Source
          description: >-
            Comma-separated channels to include (email, whatsapp). Defaults to
            every channel enabled on the agent.
        - name: from_date
          in: query
          required: false
          schema:
            type: string
            description: >-
              ISO date/datetime - only conversations created at or after it (a
              bare date covers the whole UTC day).
            default: ''
            title: From Date
          description: >-
            ISO date/datetime - only conversations created at or after it (a
            bare date covers the whole UTC day).
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            description: ISO date/datetime - only conversations created at or before it.
            default: ''
            title: To Date
          description: ISO date/datetime - only conversations created at or before it.
        - name: q
          in: query
          required: false
          schema:
            type: string
            description: Case-insensitive text matched against conversation titles.
            default: ''
            title: Q
          description: Case-insensitive text matched against conversation titles.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: Max conversations to return.
            default: 20
            title: Limit
          description: Max conversations to return.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxConversationsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    InboxConversationsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/InboxConversation'
          type: array
          title: Items
        sources_enabled:
          items:
            type: string
          type: array
          title: Sources Enabled
          description: Inbox channels enabled on this agent; empty means no inbox at all.
        total:
          type: integer
          title: Total
          default: 0
          description: Matches before the limit cap was applied.
      type: object
      title: InboxConversationsResponse
      description: The agent's inbound inbox, filtered.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InboxConversation:
      properties:
        id:
          type: string
          title: Id
          description: Conversation (execution) id.
        source:
          type: string
          title: Source
          description: 'Inbound channel: email or whatsapp.'
        title:
          type: string
          title: Title
          default: ''
          description: Conversation title.
        status:
          type: string
          title: Status
          default: ''
          description: Execution status.
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: Profile id or address of whoever started the conversation.
        sender:
          anyOf:
            - type: string
            - type: 'null'
          title: Sender
          description: >-
            Sender email address; resolved from the profile when the row carries
            an id.
        created_at:
          type: string
          title: Created At
          default: ''
          description: Creation timestamp (ISO).
        updated_at:
          type: string
          title: Updated At
          default: ''
          description: Last update timestamp (ISO).
      type: object
      required:
        - id
        - source
      title: InboxConversation
      description: One inbound email/WhatsApp conversation of an agent.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````