Live events

Holds the response open as text/event-stream and sends one event each time the mailbox changes, so a program stays in sync without polling. Every event is an SSE message whose event is its type, whose id is its id and whose data is the event as JSON (LiveEvent): message.received when a message is filed for an address, message.sent when a message sent from an address is filed in its Sent folder, thread.changed when a conversation gains or loses labels (read, starred, archived, moved, snoozed or labelled), thread.deleted when one is deleted for good, and message.status_changed when the receiving servers report on a sent email: delivered, delayed, bounced, complained of, failed, suppressed or cancelled. Events name the addresses, the conversation and the message they concern and carry no content: read it with GET /threads/{id} or GET /threads/{id}/messages/{messageId}.

The stream starts with retry: 3000, then a ready event whose data is { cursor, resumed }. Pass the id of the last event you handled as the Last-Event-ID header (or the lastEventId query parameter) and the events after it are replayed first, for as long as it is at most 10 minutes and 1000 events back. When it is older, or unknown, a reset event comes first, with { reason, cursor } (expired or unknown): list again what you keep in sync, then carry on from the stream. A comment line keeps the connection open every 25 seconds, and carries an id when events you filtered out moved the cursor on. The server ends every stream after 30 minutes, and when the credential stops being valid, with an end event whose reason is lifetime, credential or unavailable: open it again with Last-Event-ID, as the SDKs do by themselves.

A key, an app or a session holds at most 5 open streams and a workspace at most 50. A key or an app limited to particular addresses gets only the events of the addresses it reaches, checked on the server for every event, and an address it does not reach delivers nothing rather than failing. The credential is checked again at most once a minute while events flow, so a revoked key stops receiving within a minute.

Requires the threads:read scope.