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

# List inboxes

> List all inboxes for the authenticated organization, across all domains.

<RequestExample>
  ```typescript TypeScript theme={null}
  import { CommuneClient } from 'commune-ai';

  const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });

  const result = await commune.inboxes.list();

  for (const inbox of result.data) {
    console.log(inbox.address);  // support@mycompany.com
  }
  ```

  ```python Python theme={null}
  from commune import CommuneClient

  client = CommuneClient()

  result = client.inboxes.list()

  for inbox in result.data:
      print(inbox.address)
  ```

  ```bash MCP theme={null}
  list_inboxes()
  ```

  ```bash cURL theme={null}
  curl "https://api.commune.email/v1/inboxes" \
    -H "Authorization: Bearer comm_..."
  ```

  ```bash CLI theme={null}
  commune inboxes list
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "data": [
      {
        "id": "3d4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8",
        "localPart": "support",
        "address": "support@mycompany.com",
        "displayName": "Support Agent",
        "agent": {
          "name": "Support Agent"
        },
        "status": "active",
        "createdAt": "2026-02-25T10:00:00.000Z",
        "domain_id": "domain_xyz789",
        "domain_name": "mycompany.com"
      },
      {
        "id": "7e8f9a0b-1c2d-3e4f-b5c6-d7e8f9a0b1c2",
        "localPart": "sales",
        "address": "sales@mycompany.com",
        "displayName": "Sales Agent",
        "agent": {
          "name": "Sales Agent"
        },
        "status": "active",
        "createdAt": "2026-02-24T09:00:00.000Z",
        "domain_id": "domain_xyz789",
        "domain_name": "mycompany.com"
      }
    ]
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "unauthorized",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseExample>

## Response

<ResponseField name="data" type="object[]">
  Array of inbox objects for your organization. Includes inboxes from all custom domains and the shared Commune domain.

  <Expandable title="Inbox object properties" defaultOpen>
    <ResponseField name="id" type="string">
      Unique inbox identifier (UUID).
    </ResponseField>

    <ResponseField name="localPart" type="string">
      The local part of the inbox address (before `@`).
    </ResponseField>

    <ResponseField name="address" type="string">
      Full email address of the inbox.
    </ResponseField>

    <ResponseField name="displayName" type="string">
      Display name shown in outbound `From` headers.
    </ResponseField>

    <ResponseField name="agent" type="object">
      <Expandable title="properties">
        <ResponseField name="name" type="string">Agent name.</ResponseField>
        <ResponseField name="id" type="string">Agent ID, if linked to an agent identity.</ResponseField>
        <ResponseField name="metadata" type="object">Arbitrary metadata attached to the agent.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="webhook" type="object">
      <Expandable title="properties">
        <ResponseField name="endpoint" type="string">Webhook endpoint URL.</ResponseField>
        <ResponseField name="events" type="string[]">Subscribed event types.</ResponseField>
        <ResponseField name="secret" type="string">HMAC signing secret for webhook payload verification.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="extractionSchema" type="object">
      Structured extraction configuration, if set. See [Set extraction schema](/api-reference/inboxes/update) for details.

      <Note>Structured extraction requires the **Business** plan or higher.</Note>
    </ResponseField>

    <ResponseField name="limits" type="object">
      <Expandable title="properties">
        <ResponseField name="emailsPerDay" type="number">Per-inbox daily outbound email limit override.</ResponseField>
        <ResponseField name="emailsPerHour" type="number">Per-inbox hourly outbound email limit override.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">
      Inbox status. Typically `"active"`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="domain_id" type="string">
      ID of the domain this inbox belongs to.
    </ResponseField>

    <ResponseField name="domain_name" type="string">
      Domain name (e.g. `mycompany.com`).
    </ResponseField>
  </Expandable>
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.