# Live events

A mailbox's live changes with the TypeScript SDK: a channel that holds itself open, typed frames, reconnects with backoff, and when it ends for good.

[`realtime.mailbox`](/docs/sdks/typescript/realtime/mailbox) and
[`realtime.pim`](/docs/sdks/typescript/realtime/pim) open the API's live
channels, [a mailbox's change events](/docs/api/messages/get_MailboxEvents)
and an identity's calendar and contacts changes, and hold them open: a socket
lost is replaced, and the channel ends only when the API or its caller says so.

```ts
import { isFrame } from '@openemail/sdk'

const live = openemail.realtime.mailbox(mailboxId, { frames: 'state' })

live.on('frame', (frame) => {                       // { v, type, ts, data }: identifiers, never content
  if (isFrame(frame, 'ready')) resync()             // every (re)connect: the API keeps no backlog
  else if (isFrame(frame, 'state.changed') && frame.data.Email) syncSince(frame.data.Email)  // the types that changed
})
live.on('reconnecting', ({ attempt, delay, code }) => {})  // a socket lost, the next in delay ms
live.on('close', ({ code, reason }) => {})                 // for good

live.close()
```

## Frames

- **Frames are typed by their type.** `isFrame(frame, 'state.changed')`
  narrows a frame to that type's data (`frame.data.Email`), and
  `isKnownFrame(frame)` to the union of every type the SDK knows
  (`FRAME_TYPES`), which a `switch (frame.type)` narrows case by case.
- **Every frame is told**, the `ready` frame of each connect among them, so
  that is where to re-sync: [`messages.getChanges`](/docs/sdks/typescript/messages/get-changes)
  with the last `state.changed` frame's `data.Email` as `since`.
- **The vocabulary grows.** A type the API added since is no known frame,
  and still a nudge that something changed: read again what it names.
- Frames carry identifiers, never content. Each type's data is
  `FrameData[type]` (`FrameOf<type>` the whole frame): a `state.changed`
  frame's is `MailStates`, the state of each type that changed, a
  `pim.changed` frame's `PimStates`. The sets their values come from are
  constants too: `MAIL_STATE_TYPES`, `PIM_STATE_TYPES`, `MESSAGE_FLAGS`,
  `EMAIL_FAILURE_REASONS`, `PICKUP_FAILURE_STATUSES`.

## Reconnects

- **A lost socket is replaced**: a session that expired (every 12 hours), a
  deploy of the API (which drops every socket at once), the network. The wait
  is random below a ceiling that starts at 1 s and doubles to 30 s while no
  socket gets up (a `ready` frame starts it over), so a fleet of clients does
  not come back on one beat.
- **A socket that seems alive but is not is replaced too**: one that sends no
  `ready` frame within the call's `timeout`, and one silent between two
  keepalive checks (every 30 s an open socket is sent `ping`, which the API
  answers `pong`).
- **Reconnects are without end** unless the call's `retry` bounds them: a
  number in a row that may fail (`retry: 5`, `retry: false` for none), or a
  policy's `attempts`, `delay` and `maxDelay`. The client's own `retry` is
  not theirs.
- **A refused upgrade is retried too.** A bad key's `401` or an unknown
  mailbox's `404` reaches a WebSocket only as a lost connection, so by default
  the channel tries again without end and never tells `close`. Bound it with
  `retry` where a refusal is likely, and watch `reconnecting`.

## The channel

`realtime.mailbox` and `realtime.pim` answer a `RealtimeConnection` at once,
no promise: a bad argument, a missing credential or a runtime with no
WebSocket throws there. Its `on(event, listener)` answers a function that
removes that listener; `live.state` is `connecting`, `open`, `reconnecting`
or `closed`, and `live.socket` the socket held now (none between two). A
listener that throws is logged, and the others are told all the same.

## When it ends

The channel ends, telling `close` once: at its `close()` or its call's
`signal`, at the API's final word (`4403` credential revoked: do not reconnect
with that credential; `4410` the mailbox is gone), or when its reconnects in a
row run out. A socket closed under it is a socket lost, and replaced: close the
channel itself.

## The credential

It goes in each upgrade's `Authorization` header, as every other call sends
it, with the call's own `headers` and nothing else (not the client's
`headers`, not its User-Agent). That needs a WebSocket that takes headers:
Node 22.12 and later and Bun have one; a browser's and a Cloudflare Worker's
cannot send it. Elsewhere, give the client one that does with `{ WebSocket }`
([The client](/docs/sdks/typescript/client)), or use
[webhooks](/docs/sdks/typescript/webhooks).
