Events
The record of everything that happened.
Every meaningful action appends an event. It is the same stream that drives webhooks, and it is queryable after the fact.
| Event | Fires when |
|---|---|
message.received |
Inbound mail stored |
message.received.spam |
…and it was classified spam |
message.received.blocked |
…and the sender is on a receive list |
message.received.unauthenticated |
…and it failed authentication |
message.sent |
Accepted for delivery |
message.delivered |
Confirmed delivered |
message.bounced |
Rejected by the recipient's server |
message.complained |
Marked as spam by the recipient |
message.rejected |
Refused before sending |
domain.verified |
A custom domain finished verifying |
Events are written before any delivery is attempted, so an event exists whether or not its webhook ever arrived.
Reading them back
Three endpoints, and they answer different questions.
GET /v0/events lists the events themselves, newest first. This is how you find
out what you missed while an endpoint was down.
curl "https://api.carlyemail.com/v0/events?event_types=message.received&limit=50" \
-H "Authorization: Bearer $CARLYEMAIL_API_KEY"
Narrow it with inbox_id, event_types (repeatable), and a start/end
window. The window defaults to the last 7 days — pass start explicitly to
go further back. Page with next_page_token, unmodified, exactly as everywhere
else.
An unknown event_types value is a 400, not an empty page: a typo and "there
were none" should not look the same.
GET /v0/metrics/events aggregates the same stream into counts over time, per
organization, per pod and per inbox. This is what tells you how many, and
when — use it for a graph, not for a catch-up.
GET /v0/inboxes/{inbox_id}/events is a different stream entirely: the
label.added and label.removed history for one inbox, which answers "who
touched this message, and when". It does not contain the message events in the
table above.
Note
To find out whether a specific delivery reached your endpoint — as opposed to
what happened at all — use the webhook delivery log, GET /v0/webhooks/attempts.
It records every attempt with its status code, duration and failure body. See
webhooks.
Note
Metrics buckets are per minute. A period shorter than 60 seconds is refused
rather than silently rounded.