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 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), andisKnownFrame(frame)to the union of every type the SDK knows (FRAME_TYPES), which aswitch (frame.type)narrows case by case. - Every frame is told, the
readyframe of each connect among them, so that is where to re-sync:messages.getChangeswith the laststate.changedframe'sdata.Emailassince. - 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): astate.changedframe's isMailStates, the state of each type that changed, apim.changedframe'sPimStates. 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
readyframe 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
readyframe within the call'stimeout, and one silent between two keepalive checks (every 30 s an open socket is sentping, which the API answerspong). - Reconnects are without end unless the call's
retrybounds them: a number in a row that may fail (retry: 5,retry: falsefor none), or a policy'sattempts,delayandmaxDelay. The client's ownretryis not theirs. - A refused upgrade is retried too. A bad key's
401or an unknown mailbox's404reaches a WebSocket only as a lost connection, so by default the channel tries again without end and never tellsclose. Bound it withretrywhere a refusal is likely, and watchreconnecting.
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.
Receiving webhooks
OpenEmail's webhooks with the TypeScript SDK, end to end: register a hook, verify and parse what it sends, answer it, recover from failures, test it.
All methods
Every method of the TypeScript SDK, namespace by namespace, in the order the API reference presents them, each with the operation it calls.