Skip to Content

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 and realtime.pim open the API's live channels, a mailbox's change events 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.

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 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), or use webhooks.