Subscribe to live mailbox change events over WebSocket
Upgrades to a WebSocket that streams best-effort change signals for this mailbox: message.new (delivery), message.updated / message.expunged / message.restored / message.purged, label.expunged (IMAP EXPUNGE), label.created / label.renamed / label.updated / label.deleted, trash.emptied, thread.merged (an arrival joined two conversations — re-list thread views, since thread ids are convergent rather than stable), shares.changed, forwarding.changed (owner-only: forwarding destinations or forward-everything changed, including via the recipient's disable link), pickup.failed / pickup.completed (owner-only), and state.changed. A subscriber holding a system or account key also receives identity.suspension_changed when the account owner suspends or resumes this mailbox ({ identityId, suspended, generation, revision }; a lower (generation, revision) never overrides a higher one). Each frame is { v, type, ts, data } with identifiers only — never message content. The vocabulary is additive: treat an unrecognized type as a generic 'something changed' nudge rather than an error.
Signals are not a journal: there is no replay or backlog, so on every (re)connect re-sync and treat each event as 'this changed, re-fetch it'. A state.changed frame carries the current state token for each type ({ Email, Mailbox, Thread, EmailDelivery }); its Email value is exactly what GET /mailboxes/{mailboxId}/messages/changes accepts as since, so a client can re-sync incrementally instead of re-listing. A ready frame with the session deadline is sent on connect; the session is closed with code 4401 (session_expired — reconnect with a fresh bearer) after 12h, 4403 (credential_revoked — the app password was revoked; do not reconnect with it) or 4410 (mailbox_gone — stop reconnecting). Keepalive: send a ping text frame, receive pong.
bearerAuthAuthorizationBearer <token>Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.
oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.
oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.
Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].
mailboxId*stringMailbox ULID identifier
frames?"state"state: subscribe to change SIGNALS only — state.changed, label.*, trash.emptied, credential.revoked, ready — and never the per-message message.* frames. For a consumer that treats every frame as the same 'something changed' nudge and re-syncs from GET /messages/changes (the IMAP gateway), this removes one frame per message on every bulk mutation. Omit for the full stream.
"state"pim?"off"Accepted and ignored. This socket no longer carries pim.changed: calendar, task and contact signals come from the PIM store's own channel (GET /identities/{identityId}/pim/events). off once opted out of a relay of them here, and stays valid so existing clients keep connecting.
"off"Switching Protocols — the WebSocket is established
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/events'Get message sync changes GET
Answers `created` / `updated` / `destroyed` message ids for everything that happened since `since`, plus a `newState` to send next time. Ids only: fetch what…
Save structured message to mailbox POST
Constructs and saves an email message from structured JSON (headers, body text/HTML, attachments) into a mailbox without sending.