# realtime.mailbox

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`.

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

It calls `GET /mailboxes/{mailboxId}/events`: [Subscribe to live mailbox change events over WebSocket](/docs/api/messages/get_MailboxEvents) in the API reference.

## Example

```ts
const live = openemail.realtime.mailbox(mailboxId)

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |

## Options

The last argument, `options`, a `RealtimeMailboxOptions`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `frames` | `'state'` | query `frames` | `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. |
| `pim` | `'off'` | query `pim` | 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. |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

It opens a live channel, a [`RealtimeConnection`](/docs/sdks/typescript/live-events), which holds itself open, replaces a socket it loses, and tells each frame to its `frame` listeners until it is closed.

## Errors

| Status | What it means |
| --- | --- |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Mailbox not found (or not accessible to this principal) |
| `410` | mailbox_gone — the mailbox is being deleted; stop reconnecting |
| `426` | upgrade_required — the request was not a WebSocket upgrade |
| `429` | too_many_subscribers — the per-mailbox subscriber cap is reached |
| `503` | temporary_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](/docs/sdks/typescript/live-events).
