Mailbox targeting and capabilities

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.

curl "https://app.sendmux.ai/api/v1/mailbox/mailboxes?q=support" \
  -H "Authorization: Bearer connected_app_access_token"

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.

curl "https://app.sendmux.ai/api/v1/mailbox/session" \
  -H "Authorization: Bearer smx_mbx_your_key_here"

{
  "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"
  }
}

gated fields are true when a feature is intentionally unavailable.

Getting started

Developer tools

AI integrations

Sending

Receiving

Domains

Monitoring

Webhooks

Use cases

Integrations

Account and billing

Mailbox targeting and capabilities

Mailbox targeting for connected apps

Capability discovery

Next steps

Mailbox API introduction

Operations and usage

​Mailbox targeting for connected apps

​Capability discovery

​Next steps

Mailbox API introduction

Operations and usage

Mailbox targeting for connected apps

Capability discovery

Next steps