> ## 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. # Synchronise mailbox data > Synchronise mailbox resources with state tokens, change endpoints, and realtime events. 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](/docs/webhooks/setup) instead when a backend service should receive signed event POSTs without keeping a live connection open. ```bash theme={null} 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" ``` ```text theme={null} 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. ```bash theme={null} 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" ``` ```json theme={null} { "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. ```bash theme={null} 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. ```bash theme={null} 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. ```bash theme={null} curl "https://app.sendmux.ai/api/v1/mailbox/changes?types=messages,folders,threads,submissions,identities,quotas" \ -H "Authorization: Bearer smx_mbx_your_key_here" ``` ```json theme={null} { "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`. ## Next steps