client.live_events
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
Follow the mailbox as it changes, without polling: one event each time a message arrives or is sent and each time a conversation changes or is deleted, resumed where it left off after a dropped connection.
live_events.stream
Follow the mailbox as it changes
stream(types: nil, address: nil, last_event_id: nil, api_key: nil, &block) -> Enumerator<Hash>Opens the live event stream, GET /live-events read as server-sent events, and yields one event to the block each time something happens, for as long as the block keeps reading: 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 delivery of an email sent from an address moves on, with its status: delivered, delivery_delayed, bounced, complained, failed, suppressed or cancelled. Each event is a Hash with id, type, occurredAt and data, where data[:addresses] names the addresses it concerns and threadId and messageId the conversation and the message, where there is one. No content travels in an event, so read the conversation with threads.get or the message with threads.get_message when you need it.
The stream never ends by itself. The server closes it after 30 minutes, when the credential stops being valid, or when the connection drops, and the method opens it again and resumes where it left off through Last-Event-ID: at once after the server closes it, and with backoff after a failure. When the server can no longer replay from that point, which happens once the event is more than 10 minutes or 1,000 events back, it yields a reset, a Hash with type set to reset, before the next events: anything may have changed in between, so list again what you keep in sync. Leave the block with break, or raise out of it, to close the connection.
Without a block it returns an Enumerator that opens the stream only once you start reading it, so first(10) waits for ten events and then closes it.
A key or an app limited to particular addresses gets only the events of the addresses it reaches, enforced on the server for every event.
Parameters
typesString or Array<String>Only these kinds of event, the values of
Nextmail::LIVE_EVENT_TYPES:message.received,message.sent,thread.changed,thread.deletedandmessage.status_changed. An Array is sent comma separated. Left out, all of them. A reset is always delivered.addressStringOnly the events of this address. One the key does not reach delivers nothing rather than failing.
last_event_idStringResume after this event id, the
idof an event an earlier stream yielded. Left out, the stream starts with what happens from now on.api_keyStringOverrides the client's API key for this stream only.
Returns
Yields each event to the block and runs until the block breaks or raises, or without a block returns an Enumerator of the same Hashes. An event has id, type, occurredAt and data, a Hash with addresses, threadId and messageId and, by type, labelIds (received), emailId (sent), addedLabelIds and removedLabelIds (changed), or emailId, status and recipients (status changed, where threadId may be nil). A reset has id, type set to reset, occurredAt and data with reason: expired or unknown.
Example
last_seen = nil client.live_events.stream(types: ["message.received"]) do |event| last_seen = event[:id] if event[:type] == "reset" puts "Resync: the stream could not resume" next end thread = client.threads.get(event[:data][:threadId]) puts "#{event[:data][:addresses].join(", ")} #{thread[:id]}" breakend puts "Pass last_event_id: #{last_seen.inspect} to carry on from here"Notes
One key, app or session holds at most 5 open streams, and a workspace at most 50. Past that the stream is refused with 429
too_many_streams.The server sends a keepalive every 25 seconds and a
retryhint of 3 seconds. Events are kept for resuming for 10 minutes and at most 1,000 per workspace.A network failure, a 408, a 429 and a 5xx answer are retried for as long as you read, waiting about a second at first and doubling up to 30 seconds, or longer when
Retry-Afterasks, up to 5 minutes.max_retries:does not apply. When no byte arrives for 60 seconds, the method drops the connection and opens it again.A 400, 401, 403, 404 or 422 raises the
Nextmail::ApiErrorsubclass for its type instead of retrying, so an expired or revoked credential ends the stream on the next attempt to open it. A 200 that is not an event stream raisesNextmail::ApiErrorwith the codeunrecognised_response.The client's
timeout:bounds only the wait for the stream to open. Each stream holds a connection of its own, outside the client's pool, until it closes.A block, or
each,firstandtakeon the Enumerator, close the connection when they stop.nextkeeps it open between calls, so read the stream with a block when you can.
Google Workspace