Skip to Content

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.

openemail.realtime.mailbox(
  mailboxId: string,
  options?: RealtimeMailboxOptions,
): RealtimeConnection

It calls GET /mailboxes/{mailboxId}/events: Subscribe to live mailbox change events over WebSocket in the API reference.

Example

const live = openemail.realtime.mailbox(mailboxId)

live.on('frame', (frame) => {
  // every frame the API sends, the ready frame of each connect first
})

Arguments

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.

Options

The last argument, options, a RealtimeMailboxOptions, takes:

OptionTypeSent asDescription
frames'state'query framesstate: 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.
pim'off'query pimAccepted 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.

Every call also takes signal, timeout, retry and headers, which say how that one call is sent (call options).

Answer

It opens a live channel, a RealtimeConnection, which holds itself open, replaces a socket it loses, and tells each frame to its frame listeners until it is closed.

Errors

StatusWhat it means
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
404Mailbox not found (or not accessible to this principal)
410mailbox_gone — the mailbox is being deleted; stop reconnecting
426upgrade_required — the request was not a WebSocket upgrade
429too_many_subscribers — the per-mailbox subscriber cap is reached
503temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

A live channel rejects nothing: a refused upgrade reaches its WebSocket only as a lost connection, so the channel reconnects (it tells reconnecting), without end unless its retry bounds it. The API's close codes 4403 and 4410 end it: see Live events.