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

# Mailbox targeting and capabilities

> Select a granted mailbox and discover supported Mailbox API capabilities and limits.

The Sendmux Mailbox API is for mailbox-scoped access. Use it when a client should act as a mailbox, or as one mailbox from a connected-app mailbox set, without managing team-wide resources.

## Mailbox targeting for connected apps

Manual mailbox credentials always target their single mailbox. Omit `mailbox_id` when you use a manual `smx_mbx_` credential.

Connected-app tokens can grant a set of mailboxes. Use `GET /mailbox/mailboxes` to list or search the granted set, then pass the selected mailbox's `id` as `mailbox_id` on Mailbox API requests.

Self-registered agent tokens target their assigned mailbox. Omit `mailbox_id` when you use a pre-claim `smx_agent_` token. Pre-claim tokens can read and receive mail, but they cannot send. After owner approval, an app-resource `smx_agent_` token with `email.send` can send from the assigned mailbox.

```bash theme={null}
curl "https://app.sendmux.ai/api/v1/mailbox/mailboxes?q=support" \
  -H "Authorization: Bearer connected_app_access_token"
```

```bash theme={null}
curl "https://app.sendmux.ai/api/v1/mailbox/messages?mailbox_id=mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx&limit=10" \
  -H "Authorization: Bearer connected_app_access_token"
```

If a connected app has exactly one granted mailbox, Mailbox API requests use that mailbox by default. If several mailboxes are granted and you omit `mailbox_id`, Sendmux returns `400 missing_parameter`. If you pass a mailbox outside the grant, Sendmux returns `403 insufficient_permissions`.

## Capability discovery

Use `GET /mailbox/session` before planning a mailbox workflow. It returns the
selected mailbox, supported Mailbox API features, current state
tokens, request limits, and gated features. A gated feature is intentionally
unavailable through the Mailbox API.

```bash theme={null}
curl "https://app.sendmux.ai/api/v1/mailbox/session" \
  -H "Authorization: Bearer smx_mbx_your_key_here"
```

```json theme={null}
{
  "ok": true,
  "data": {
    "mailbox": {
      "id": "mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx",
      "email": "agent@example.com",
      "display_name": "Agent"
    },
    "states": {
      "messages": "email_state_token",
      "folders": "folder_state_token",
      "threads": "thread_state_token",
      "submissions": "submission_state_token",
      "identities": "identity_state_token",
      "quotas": "quota_state_token"
    },
    "capabilities": {
      "messages": {
        "list": true,
        "query_changes": true,
        "batch_update": true,
        "keywords": true,
        "update_fields": ["seen", "flagged", "keywords"]
      },
      "identities": {
        "list": true,
        "update": true
      },
      "attachments": {
        "upload": true,
        "download": true,
        "parsing": false
      }
    },
    "limits": {
      "list_limit_max": 100,
      "changes_limit_max": 500,
      "batch_ids_max": 100,
      "body_chars_max": 1000000,
      "inline_attachment_bytes_max": 5000000,
      "attachment_upload_bytes_max": 7500000,
      "outbound_raw_message_bytes_max": 26214400,
      "keywords_per_update_max": 50
    },
    "gated": {
      "identity_mutation": false,
      "quota_mutation": true,
      "filter_script_writes": true,
      "events": false,
      "raw_protocol": true,
      "attachment_parsing": true
    }
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

<Note>
  `gated` fields are `true` when a feature is intentionally unavailable.
</Note>

## Next steps

<Columns cols={2}>
  <Card title="Mailbox API introduction" icon="book-open" href="/docs/mailbox-api/introduction" />

  <Card title="Operations and usage" icon="gauge" href="/docs/developer-tools/mailbox-api/operations-and-usage" />
</Columns>