Skip to Content

Subscribe to live calendar and contacts change events over WebSocket.

Upgrades to a WebSocket that streams pim.changed frames for this identity's calendars, tasks and contacts: { v, type, ts, data } where data is the current state token per type ({ Calendar, CalendarEvent, Task, AddressBook, ContactCard }), the same tokens the per-collection /changes feeds and JMAP accept. A ready frame with the session deadline is sent on connect. Signals are not a journal: there is no replay, so on every (re)connect re-sync, and treat each frame as 'this changed, re-fetch it'. The vocabulary is additive: treat an unrecognized type as a generic nudge.

Owner-only: a calendar or address book shared with you is not streamed here. Before the first calendar or contact use, the connection waits without creating a store. Its first authorized PIM use creates the default collections and sends one pim.changed frame. The session is closed with 4401 (session_expired: reconnect with a fresh bearer) after 12h, 4403 (credential_revoked: the credential was revoked or its owner suspended; do not reconnect with it) or 4410 (mailbox_gone: the identity is being deleted; stop reconnecting). Keepalive: send a ping text frame, receive pong.

openemail.realtime.pim(
  identityId: string,
  options?: CallOptions,
): RealtimeConnection

It calls GET /identities/{identityId}/pim/events: Subscribe to live calendar and contacts change events over WebSocket in the API reference.

Example

const live = openemail.realtime.pim(identityId)

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

Arguments

ArgumentTypeDescription
identityIdstringIdentity ULID. The path's {identityId}.

Options

It takes no options of its own. 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
403forbidden: the identity's owner is suspended and this connection would act for them (an account or system key acting for nobody may still connect)
404not_found (the identity does not exist or is not this principal's to stream)
410mailbox_gone: the identity is being deleted; stop reconnecting
426upgrade_required: the request was not a WebSocket upgrade
429too_many_subscribers: the store's 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.