The event stream

Webhooks push events to you; the event stream lets you pull them. Every event on your account is written to a durable, ordered stream you can page through, tail live, or re-send to your webhooks — so downtime never loses an event.

Read the stream

GET /v1/events pages the stream oldest-first, so you read events in the order they happened. Each page is the standard list envelope — a data array and a pagination cursor — plus a gaps array unique to this stream. Reading uses the events:read scope.

curl "https://api.dairo.app/v1/events?limit=50" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const page = await dairo.events.list({ limit: 50 });
for (const e of page.data) console.log(e.seq, e.type, e.createdAt);
if (page.gaps.length) console.warn("missing sequences:", page.gaps);

page = dairo.events.list(limit=50)
for e in page.data:
    print(e.seq, e.type, e.created_at)

Tool: list_events  (scope events:read)
{ "action": "list", "limit": 50 }
{ "action": "list", "type": "message.received", "inboxId": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }
{ "action": "list", "order": "newest", "limit": 10 }

A page looks like this:

{
  "object": "list",
  "data": [
    {
      "object": "event",
      "eventId": "evt_9f8c2a1b4e7d4c1a8b2d3e4f5a6b7c8d",
      "type": "message.received",
      "seq": 412,
      "partitionKey": "inbox:7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "inboxId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "threadId": "b2c3d4e5-6f70-4a81-92b3-c4d5e6f708a9",
      "idempotencyKey": null,
      "outboundMessageId": null,
      "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "providerMessageId": null,
      "occurredAt": "2026-06-12T10:00:00Z",
      "createdAt": "2026-06-12T10:00:01Z",
      "data": {
        "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "from": "customer@example.com",
        "subject": "Re: Your receipt"
      }
    }
  ],
  "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOi…", "hasMore": true },
  "gaps": []
}

Each entry carries the same eventId, type, and data as the webhook delivery for that event, and adds the stream’s join keys: the per-partition sequence number seq and the loop-wide idempotencyKey threaded from the originating send. Page forward with the cursor until pagination.nextCursor comes back null.

Parameter	Description
`limit`	Events per page, 1–100. Defaults to 50.
`since`	Opaque cursor from a prior page’s `pagination.nextCursor`. `cursor` is accepted as an alias.
`inboxId`	Only events for one inbox.
`type`	Only one event type, for example `message.bounced`.
`idempotencyKey`	Every event carrying this idempotency key — the full story of one send.
`order`	`oldest` (default) reads forward for catch-up; `newest` returns a recency view with the most recent event on page 1.
`wait`	Long-poll hold in seconds, 0–12. See the tail loop below.
`tail`	When `true`, returns `data: []` plus the current head cursor.

Detect gaps

Every event carries a seq — a contiguous, 1-based sequence number within its partition. The partitionKey names the resource the events belong to, such as inbox:<id> or letter:<id>. If a page’s window is missing a sequence number it should contain, the page reports it under gaps as { "partitionKey": …, "missingSeq": [...] } — a lost event is something you can see and act on, never a silent hole. Detection is window-local: it checks the sequence range present on the returned page, not the whole history. On a filtered read (type or inboxId), events excluded by the filter surface as gaps too — expected, not lost. Audit gaps on unfiltered pages.

Tail a live feed

To follow events in near-real time, seed at the current head with tail: true, then long-poll forward with wait. A request with wait set holds until a matching event arrives or the seconds elapse (capped at 12), so a steady listener never hammers the API; if nothing arrives in time you get an empty page and poll again. When events are already waiting, they return immediately.

// Seed at the head, then long-poll forward.
const head = await dairo.events.list({ tail: true });
let cursor = head.pagination.nextCursor;
for (;;) {
  const page = await dairo.events.list({ cursor, wait: 12 });
  for (const e of page.data) handle(e);
  cursor = page.pagination.nextCursor ?? cursor;
}

# tail/wait are query parameters on GET /v1/events — call the endpoint directly.
import os, requests

url = "https://api.dairo.app/v1/events"
headers = {"Authorization": f"Bearer {os.environ['DAIRO_API_KEY']}"}

head = requests.get(url, headers=headers, params={"tail": "true"}).json()
cursor = head["pagination"]["nextCursor"]
while True:
    page = requests.get(url, headers=headers, params={"cursor": cursor, "wait": 12}).json()
    for event in page["data"]:
        handle(event)
    cursor = page["pagination"]["nextCursor"] or cursor

# The CLI wraps tail + long-poll into one streaming command.
dairo listen

tail: true returns data: [] plus the current head cursor (or null on an empty stream), so your next poll streams only events from that point on. It honors the same inboxId and type filters as a normal read. wait: 0 — the default — returns immediately.

Replay to your webhooks

POST /v1/events/replay re-sends a slice of history through your webhooks — to recover after your receiver was down, or to backfill a newly added endpoint. Replay uses the events:write scope. Give exactly one lower bound:

Lower bound	Use
`since`	A cursor from a prior page.
`sinceSeq` + `inboxId`	Replay one inbox partition from a sequence number (inclusive).
`sinceTimestamp`	An RFC 3339 timestamp.

curl -X POST https://api.dairo.app/v1/events/replay \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sinceTimestamp": "2026-06-10T00:00:00Z", "maxEvents": 500 }'

const result = await dairo.events.replay({
  sinceTimestamp: "2026-06-10T00:00:00Z",
  maxEvents: 500,
});
console.log(result.replayed, result.skipped);

result = dairo.events.replay(since_timestamp="2026-06-10T00:00:00Z", max_events=500)
print(result.replayed, result.skipped)

Tool: replay_event  (scope events:write, confirm required)
{ "action": "replay", "sinceTimestamp": "2026-06-10T00:00:00Z", "maxEvents": 500, "confirm": true }

The response counts what happened and names the first and last event of the slice:

{
  "replayed": 212,
  "skipped": 3,
  "from": {
    "eventId": "evt_2c1a8b2d3e4f5a6b7c8d9f8c2a1b4e7d",
    "seq": 201,
    "partitionKey": "inbox:7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2026-06-10T00:02:11Z"
  },
  "to": {
    "eventId": "evt_9f8c2a1b4e7d4c1a8b2d3e4f5a6b7c8d",
    "seq": 412,
    "partitionKey": "inbox:7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2026-06-12T10:00:01Z"
  }
}

Replay goes to your active webhooks, re-matched per event on their subscribed types; skipped counts events no active subscription matched. Narrow a slice with until (an upper timestamp), types (an event-type list), or inboxId. Pass webhookId to replay to one endpoint only — useful for backfilling a new receiver without re-firing the others; a paused or unknown webhookId returns a 404. Events are re-sent in (partitionKey, seq) order, and every replayed delivery is recorded in that webhook’s delivery log. maxEvents caps the slice at 1–5,000 events (default 1,000). A slice that exceeds the cap is refused with a 400 rather than silently truncated — narrow the range or page through it with until.

Replayed events travel the normal signing and delivery path with the same event ID, so your receiver verifies and deduplicates them exactly like live ones. Keep your handler idempotent — a replay can re-send events you already processed.

Next steps

Webhooks — push delivery, signature verification, and the full event catalog.
Track delivery — delivery, bounce, and complaint events per message.
CLI — dairo listen, the live tail built on this stream.
API reference — GET /v1/events and POST /v1/events/replay.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Read the stream

Detect gaps

Tail a live feed

Replay to your webhooks

Next steps

​Read the stream

​Detect gaps

​Tail a live feed

​Replay to your webhooks

​Next steps

Read the stream

Detect gaps

Tail a live feed

Replay to your webhooks

Next steps