List received messages

Page size (1–100).

Opaque cursor from a previous page's next_cursor.

Filter by agent id or name. A key tied to one agent always reads that agent's mail, and naming another agent is a 403.

Filter by thread id.

Case-insensitive substring of the subject, body or sender address. For word search across all mail, use GET /v1/search.

Only mail from this sender: an address (noreply@github.com, in any case) or a domain (github.com, which takes its subdomains such as mail.github.com and never github.com.evil.example). It is the From header's address, proven only when the message's dmarc is pass. Anything else answers 400 invalid_param_value.

Only mail sent to this address, in any case: the message's delivered_to. Give each test run or sign-up its own plus address (qa.acme+run-1842@in.mails.ai) and pass it here, so runs that overlap never read each other's mail. In a query string, write its + as %2B: one left as it is arrives as a space, which is read back as +. Mail received before 2026-10-16 has no delivered_to and never matches. Anything that is not an address answers 400 invalid_param_value.

Only mail received at or after this time: an ISO 8601 time such as 2026-10-05T07:00:00Z, or a date (midnight UTC). Any other value answers 400 invalid_param_value.