Read the durable event ledger
Read the durable event ledger (catch-up)
Returns your account's durable, ordered event ledger — outbound message lifecycle (email.sent, email.delivered), delivery outcomes (email.bounced, email.complained), and inbound message.received — as a data array of ledger rows, each carrying a monotonic per-partition seq and a partitionKey join key. Events are returned oldest-first (forward catch-up order), so you replay history in the order it happened; order=newest returns the newest first instead. Page forward by passing the previous response's pagination.nextCursor as since (cursor is accepted too): on every non-empty page it names the last event returned, so you can keep polling from it after the last page, and pagination.hasMore says whether more events already exist. limit accepts 1–100 and defaults to 50. wait (0–12 seconds) holds an empty request open until an event arrives, and tail=true returns no events, only the current head cursor to start reading strictly after the newest event. Narrow the stream with inboxId (one partition), type (one event type, e.g. email.bounced), or idempotencyKey (every event threaded from one idempotent send). Each page also reports gaps[] — per-partition seq numbers expected but absent within the returned window (detection is window-local, not whole-history); a non-empty entry means events were lost and can be recovered with a replay. Any other query parameter returns 400. This call is read-only and never re-delivers to webhooks. Requires the events:read scope.
Scope: events:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
since | string | no | Opaque keyset cursor (from a prior pagination.nextCursor) to read forward from. |
limit | integer | no | Maximum number of items in the page. (minimum 1, maximum 100, default 25) |
inboxId | string | no | Filter to one inbox partition. |
type | string | no | Filter to one event type, e.g. email.bounced. |
idempotencyKey | string | no | Return every event carrying this loop-wide idempotency key. |
wait | integer | no | Long-poll: when no event is available yet, hold the request up to this many seconds (0..=12, larger values are capped) until one arrives. (minimum 0, maximum 12, default 0) |
tail | boolean | no | Return no events, only the current head cursor of the (filtered) stream in pagination.nextCursor, to start reading strictly after the newest existing event. (default false) |
order | "oldest", "newest" | no | oldest (default, forward catch-up order) or newest (newest first). (default "oldest") |
Response
200 Success. Body: application/json, EventLedgerPage.
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" | yes | Always "list" — the unified list envelope discriminator. |
data | array of LedgerEvent | yes | The ledger events for this page, each with seq/partitionKey join keys. (This is the array named data, not events.) |
pagination | Pagination | yes | |
gaps | array of LedgerGap | yes | Per-partition seq gaps detected within this page's window. An empty array means no gap was detected in the returned window — detection is window-local (only the seq range present on this page), not whole-history. |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
422 | The request is well-formed but a field failed validation (validation_failed). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
Recheck a domain's DNS records
Re-checks the DNS records for a pending domain and updates both the domain's status and each record's status to match what is currently published.
Replay events from the ledger to webhooks
Re-reads a slice of the event ledger and re-delivers it to your webhook subscriptions, reconstructing each event body byte-identically — same eventId, type, and data — and signing it with a fresh X-Dairo-Timestamp like any delivery attempt, so it passes the consumer's verification and timestamp window while consumer-side dedupe on the event ID stays exact.