Menu Waiting for emails

Guides

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
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 after the 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 the id of 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 as 2026-10-22T09:00:00Z) answers with an email received strictly after that moment by the server's clock – take it from the Date header of a response, not from your machine and not from a createdAt you were shown. A + in an offset goes into the URL as %2B.
cURL
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"
Something missing, confusing or wrong on this page? Tell us