events

Replayable event log and live streams.

Every command also takes the global flags.

events get

Get event.

One event of the log. An event the credential may not read (see GET /v0/events) is a 404, like one outside its scope.

Requires the metrics_read permission.

machinemail events get <event-id> [flags]

Arguments

Flags

Examples

machinemail events get evt_01m4g0d4n60000v8b2c6k3y7zd
machinemail events get evt_01m4g0d4n60000v8b2c6k3y7zd --inbox agent@machinemail.dev

API

• GET /v0/events/{event_id}
• GET /v0/inboxes/{inbox_id}/events/{event_id} with --inbox
• GET /v0/pods/{pod_id}/events/{event_id} with --pod

events list

List events.

Also: machinemail events ls.

The replayable event log, newest first. Pass —after (an event ID or a time) to read forward from a point, oldest first. Events are kept without a retention limit. Only the events the credential may read are listed, as on the live streams: message.* needs message_read, inbox.* inbox_read, domain.* domain_read, draft.* draft_read, webhook.test webhook_read, and the audit events (agent registrations, members) metrics_read. —event-types cannot add others.

Requires the metrics_read permission.

machinemail events list [flags]

Flags

Examples

machinemail events list
machinemail events list --inbox agent@machinemail.dev
machinemail events list --all --json | jq '.events | length'

API

• GET /v0/events
• GET /v0/inboxes/{inbox_id}/events with --inbox
• GET /v0/pods/{pod_id}/events with --pod

events stream

Stream events as they happen (server-sent events).

Server-Sent Events of everything in the credential scope that its permissions allow, narrowed by the query filters.

Each event is sent only when the credential holds the read permission of what it describes: message.* needs message_read, domain.* needs domain_read, inbox.* needs inbox_read, draft.* needs draft_read, webhook.* needs webhook_read. Other events are skipped, without an error, and —event-types cannot add them. The credential is re-checked every 30 seconds: when it is revoked or expired, or its permissions or pod/inbox scope change, the stream ends with an error (reconnect to get the events the credential allows now).

Frames are id: <event_id>, event: <event_type>, data: <JSON>, where the JSON is the webhook event envelope (type: “event”, event_id, event_type, timestamp, data, and the data keys repeated at the top level), not the Event object of GET /v0/events. The first frame is event: ready with data: {“type”:“subscribed”}. A : ping comment is sent after 15 seconds without events.

With a Last-Event-ID: evt_… header, up to 500 missed events are replayed first. The replay applies —event-types, the credential scope and the per-event permissions, not the —inbox or —pod filters. When the API runs on several servers, the replay also repeats events from the few seconds before Last-Event-ID (an event from another server can reach a stream after a later one): dedupe by event id.

An event: resync frame (data: {“type”:“resync”}) means this server may have missed events from other servers (its notification connection to the database was interrupted); the stream then ends. Its id: is a cursor from before the interruption, which an EventSource takes as its last event ID: reconnect with it as Last-Event-ID to replay what was missed, some events again (dedupe by event id).

A stream opened with a dashboard session cookie also receives that person’s session events (session.agent.claimed, session.cli.device, session.oauth.request): live notices that a hand-off they started (an agent claim, a CLI sign-in, an OAuth consent) was completed, so their other tabs can finish too. Their frames have no id: line and their data is {“type”:“session”,“event_type”,“timestamp”,“data”}; they are never stored, replayed or sent to API keys, OAuth tokens, webhooks or the WebSocket. They need no permission: they go only to the session of the person they are about.

Requires the metrics_read permission.

machinemail events stream [flags]

Flags

Examples

machinemail events stream --json | jq -c 'select(.type == "message.received")'

API

• GET /v0/events/stream