Skip to Content
GET
/api/v1/mailboxes/{mailboxId}/events

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.

Authorization

bearerAuth
headerAuthorizationBearer <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: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

Query Parameters

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.

Value in"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.

Value in"off"

Response Body

Switching Protocols — the WebSocket is established

Example Request
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/events'
Example Response
Empty