Synchronise mailbox data

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.

Sync APIs

Use sync endpoints to poll for changes with state tokens returned by earlier responses, or open an event stream when a client needs live updates.

Event stream

GET /mailbox/events streams mailbox events as Server-Sent Events. Use it for agents, CLIs, MCP servers, and SDKs that need to react when inbound mail arrives. Use webhooks instead when a backend service should receive signed event POSTs without keeping a live connection open.

curl -N "https://app.sendmux.ai/api/v1/mailbox/events?event_types=message.received,message.received.spam" \
  -H "Authorization: Bearer smx_mbx_your_key_here"

id: evt_clxxxxxxxxxxxxxxxxxxxxxxxxx
event: message.received
data: {"event_type":"message.received","mailbox_id":"mbx_clxxxxxxxxxxxxxxxxxxxxxxxxx","message_id":"msg_123","message":{"id":"msg_123","subject":"New reply","preview":"Thanks for the update.","body":{"text":"Thanks for the update.","html":null,"is_truncated":false,"max_bytes":16384}}}

Each received-message event includes subject, participants, preview, attachment metadata, and a capped body snapshot. Use the message and attachment endpoints when you need full content or attachment bytes. To resume after a disconnect, pass the last SSE id as the Last-Event-ID header or the last_event_id query parameter. If the stream sends sync_required, call GET /mailbox/changes before reopening the stream. Optional query parameters:

Parameter	Purpose
`event_types`	Comma-separated list of `message.received` and `message.received.spam`.
`ping`	Heartbeat interval in seconds, from `10` to `300`.
`close_after`	Close the stream after `30` to `3600` seconds. Omit for a long-lived stream.
`last_event_id`	Replay events after a prior SSE event ID.

Message query changes

GET /mailbox/messages/query-changes tracks how a filtered message list has changed since a prior query_state. Omit since_query_state to get the current query state for a filter without a change list.

curl "https://app.sendmux.ai/api/v1/mailbox/messages/query-changes?since_query_state=message_query_state_token&q=invoice&limit=100" \
  -H "Authorization: Bearer smx_mbx_your_key_here"

{
  "ok": true,
  "data": {
    "old_query_state": "message_query_state_token",
    "new_query_state": "message_query_state_token_2",
    "has_more": false,
    "removed": ["msg_old"],
    "added": [{ "id": "msg_new", "index": 0 }],
    "total": null
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Folder changes

GET /mailbox/folders/changes tracks folder object changes. Omit since_state to get the current folder state without a change list.

curl "https://app.sendmux.ai/api/v1/mailbox/folders/changes?since_state=folder_state_token" \
  -H "Authorization: Bearer smx_mbx_your_key_here"

Folder query changes

GET /mailbox/folders/query-changes tracks folder-list ordering changes. Omit since_query_state to get the current folder query state.

curl "https://app.sendmux.ai/api/v1/mailbox/folders/query-changes?since_query_state=folder_query_state_token" \
  -H "Authorization: Bearer smx_mbx_your_key_here"

Typed mailbox changes

GET /mailbox/changes keeps the legacy message-only response when types is omitted. Pass a comma-separated types list to receive a typed state map.

curl "https://app.sendmux.ai/api/v1/mailbox/changes?types=messages,folders,threads,submissions,identities,quotas" \
  -H "Authorization: Bearer smx_mbx_your_key_here"

{
  "ok": true,
  "data": {
    "types": {
      "messages": {
        "old_state": "message_state_token",
        "new_state": "message_state_token_2",
        "has_more": false,
        "created": ["msg_789"],
        "updated": [],
        "destroyed": []
      },
      "folders": {
        "old_state": "folder_state_token",
        "new_state": "folder_state_token_2",
        "has_more": false,
        "created": [],
        "updated": ["inbox"],
        "destroyed": []
      },
      "threads": {
        "old_state": "thread_state_token",
        "new_state": "thread_state_token_2",
        "has_more": false,
        "created": [],
        "updated": ["thr_123"],
        "destroyed": []
      },
      "submissions": {
        "old_state": "submission_state_token",
        "new_state": "submission_state_token_2",
        "has_more": false,
        "created": [],
        "updated": ["sub_123"],
        "destroyed": []
      },
      "identities": {
        "old_state": "identity_state_token",
        "new_state": "identity_state_token_2",
        "has_more": false,
        "created": [],
        "updated": ["id_123"],
        "destroyed": []
      },
      "quotas": {
        "old_state": "quota_state_token",
        "new_state": "quota_state_token_2",
        "has_more": false,
        "created": [],
        "updated": ["quota_123"],
        "destroyed": []
      }
    }
  },
  "meta": {
    "request_id": "req_clxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Supported types values are messages, folders, threads, submissions, identities, and quotas.

Getting started

Developer tools

AI integrations

Sending

Receiving

Domains

Monitoring

Webhooks

Use cases

Integrations

Account and billing

Synchronise mailbox data

Sync APIs

Event stream

Message query changes

Folder changes

Folder query changes

Typed mailbox changes

Next steps

Mailbox API introduction

Mailbox API errors

​Sync APIs

​Event stream

​Message query changes

​Folder changes

​Folder query changes

​Typed mailbox changes

​Next steps

Mailbox API introduction

Mailbox API errors

Sync APIs

Event stream

Message query changes

Folder changes

Folder query changes

Typed mailbox changes

Next steps