The event log
GET /v1/events
Required scope: webhooks:read. Available on Starter, Pro and Scale.
The same events, in exactly the same envelopes the webhook sends, kept for 7 days and readable on demand. It exists for three jobs a subscription cannot do.
Catching up after an outage. A delivery is abandoned after 12 attempts, about 14 and a half hours. The log keeps 7 days, deliberately longer, so an endpoint that was down past the retry window has somewhere to recover from. This is its most important use and the reason the two windows differ.
Showing a sample. An automation platform needs real events to display while somebody is still building, before any endpoint exists to receive them.
Polling instead of listening, for an integration that cannot expose a public URL at all.
Filters
| Query | |
|---|---|
type |
One event name, such as message.received. An unknown name is a 400 listing the valid ones |
mailbox |
One mailbox address |
since |
RFC 3339; only events after that instant |
limit |
1 to 100, default 25 |
Newest first.
Catching up safely
Because the envelopes are identical to the webhook’s, you can mix the two
sources and deduplicate on id:
last = store.last_seen_at() # an RFC 3339 instant you persisted
r = client.get("/v1/events", params={"since": last, "limit": 100})
for event in reversed(r.json()["data"]): # oldest first
if not store.seen(event["id"]):
process(event)
store.record(event["id"], event["created"])
Two details worth keeping. Iterate oldest first when replaying, since the
endpoint returns newest first. And advance your since from the events you
actually processed, not from the clock, so a crash mid-page cannot skip the
remainder.
It is written whether or not you subscribe
Events are logged even with no webhook configured, so you can start polling before building an endpoint, and the log is populated from the moment your account raises its first event.
Which events you see
The same ones a subscription would deliver, subject to the same rules: a key’s mailbox grants apply to events about a single mailbox, while account-level events such as a domain verification are visible to any caller with the scope.