List emails
GET /emails
Newest first.
| Parameter | Default | Notes |
|---|---|---|
limit | 50 | Clamped to 1–200. |
after | — | The keyset cursor: the last id from the previous page. |
query | — | Matches the recipient or the subject, case-insensitively, as a substring — the two things you have when you come looking for a message somebody is asking about. |
status | — | Exact match. queued, sent, delivered, bounced, complained, failed, refused, cancelled. Omit for any. |
{
"data": [
{ "id": "1042", "from": "hello@yourdomain.com", "to": ["someone@example.com"],
"subject": "Your receipt", "status": "delivered", "created_at": 1735689600 }
],
"next": "1042"
}
Pass next back as after to continue, and stop when data comes back
empty: a non-empty next is not a promise that more exist, and a full page
followed by nothing is an ordinary end.
Keyset rather than an offset, because rows arriving while you page would shift an
offset under you — you would see one message twice and miss another — and this is
the largest table we own, where OFFSET gets slower the deeper you go.
Bodies are not included. html and text come back only from
retrieving one message: a listing that carried fifty bodies
would be a slow endpoint for a field almost nobody reads in a list.
Reading requires a full-access key
A sending_access key answers 403 key_not_permitted here and on every other
read. The point of the narrow key is that it is the credential you can put on the
machine you trust least, and one that could read every message the account ever
sent would not be that.
Reads have their own rate ceiling, separate from sending, so polling the log can
never eat the send rate you are paying for. Over it you get 429 with
Retry-After, exactly as on a send.