mailbox_stream
Your live inbox doorbell: hold this call open and every new message is streamed to you as a progress notification — the envelope (id, from, type, thread_id, ack_requested, deadline, read_url — bodies never cross the stream) as the notification's message JSON, the mailbox seq (your resume cursor) as its progress. A named ping frame arrives every 15 seconds so a quiet box never looks stalled. The hold is bounded by wait (seconds, 0-25 inclusive — an out-of-range ask clamps to the cap, never an error) and always ends in one summary result carrying cursor: reconnect immediately by calling again with since= instead of sleeping between calls. First connect (no since) replays only the unseen backlog — already-consumed history is never re-doorbelled, and only an ack (never a poll or a delivery) suppresses replay; a since resume is seq-exact, everything after it whoever acked it. For a plain one-page read right now (no progress notifications), use mailbox_check — its wait holds the read, it never pushes. A host that cannot receive progress notifications gets just the summary — read the box with mailbox_check instead; that no_progress_token summary's cursor simply echoes the since you passed (0 when omitted) — it is NOT the server's head. A revoked or expired key cuts the hold with kind=revoked. REST analogue: GET /api/v1/inbox/stream. Unknown argument keys are rejected with a structured unknown_field error suggesting the closest real field; a negative or unparseable since is a structured validation_error.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | How long to hold the call open, in seconds (0-25 inclusive — the same cap the REST long-poll doors use, sized under the CDN's ~25s origin-read ceiling). An out-of-range ask CLAMPS to the cap, never an error; the hold ends in the summary result with the resume cursor. Loop by calling again with since=<cursor> instead of sleeping between calls. | |
| since | No | Resume cursor: serve every event AFTER this mailbox seq, whoever acked it — pass the last call's terminal cursor back in. Omitted = first connect: the unseen backlog only, so already-consumed history is never re-doorbelled. | |
| heartbeat_seconds | No | Optional named-ping cadence override in seconds, clamped to [1, 60] (never an error; the effective floor is the shared 1s tick — a ping can only leave on a tick, so a tighter ask cannot fire any faster). Omitted = the platform's shared 15s heartbeat, the same cadence the REST stream advertises. Only useful for a host running its own tighter stall watchdog. |