Waiting for emails
GET /v1/mailboxes/{address}/messages/wait holds the request open until a matching email is in and answers with it – no loop over the list of messages, no sleep in your test.
The long poll
There are no webhooks and no streaming on this API; the wait is how you get an email the moment it arrives. It spends nothing of the monthly quota and one request of the per-minute rate limit, however long it waits (Limits).
curl -s -G "https://api.fake-email.pro/v1/mailboxes/anna.smith.42@example.org/messages/wait" \
-H "Authorization: Bearer $FAKE_EMAIL_API_KEY" \
--data-urlencode 'timeout=60' \
--data-urlencode 'from=acme.example'Parameters
timeout– Whole seconds to hold the request open, 1–60; 30 when left out.after– Where to start: the id of a message of this mailbox, or an RFC 3339 time by the server's clock. Only a message strictly after it counts; without it, every message of the mailbox does – one that came before the call included.from– A substring of the sender address, case-insensitive.subject– A substring of the subject, case-insensitive.
Responses
200– The earliest matching message, in the short form the list of messages uses – id, from, subject, bodyState, code and confirmLink. Sent at once if it is already there, the moment it arrives otherwise. Bodies, attachments and every code and link: GET /v1/mailboxes/{address}/messages/{id}.204– No matching message within timeout. No body; ask again.400 bad_request– timeout outside 1–60 or not a number, or an after that is neither a message id nor an RFC 3339 time.404 not_found– No such active mailbox of yours (it may have expired or been deleted while the request waited), or an after id this mailbox does not hold.429 too_many_waits– Too many waits of yours held open at once, with Retry-After: 1. The cap is concurrentWaits in GET /v1/limits; any wait that ends frees its slot.
Reading a mailbox email by email
- Without
afterthe wait answers with the earliest matching email of the mailbox – one that came before the call included, so nothing sent between creating the mailbox and waiting is lost. The first wait on a fresh mailbox goes without it. after=<id>answers with the next email after that one. Pass theidof the email you just got and you walk the mailbox one email at a time, never skipping one – not even one that arrived between two requests or in the same millisecond.after=<time>(RFC 3339, such as2026-10-22T09:00:00Z) answers with an email received strictly after that moment by the server's clock – take it from theDateheader of a response, not from your machine and not from acreatedAtyou were shown. A+in an offset goes into the URL as%2B.
curl -s -G "https://api.fake-email.pro/v1/mailboxes/anna.smith.42@example.org/messages/wait" \
-H "Authorization: Bearer $FAKE_EMAIL_API_KEY" \
--data-urlencode 'timeout=60' \
--data-urlencode "after=$MESSAGE_ID"