Wait for a received message
Requires scope: read. Answers with the newest received message that matches, holding on for up to timeout seconds until one arrives. Made for an agent that has just asked a service for a sign-up code, a magic link, a password reset or an invite-accept link: name the sender with from and what you need with has, then read message.codes[0].value or the first message.links entry. When you gave the service a plus address of the agent's (qa.acme+run-1842@in.mails.ai), pass it as to, and only mail sent to it answers. When mail sent to to arrived past your plan's plus addresses a day, only a record of it was kept, so the call answers 402 plan_limit_exceeded at once instead of waiting. Mail judged forged (auth_failed) and quarantined mail never match. Nothing in time is not an error: message is null and timed_out true.
Request
- Base URL: https://api.mails.ai
- URL: https://api.mails.ai/v1/messages/received/wait
- Auth: HTTP bearer
Query parameters
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.
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. Default: the last 5 minutes. Pass the time you asked the service to send, so an older code never answers.
code: only a message with at least one entry in codes. link: only one with at least one extracted link of any kind — verify, sign_in, reset_password, invite-accept (other), or any other kind. Absent: any message that matches the other filters.
Seconds to wait for a match, 0 to 50 (default 30). 0 looks once and answers at once.
Response
The matching message, or none in time.
Changes
No recorded changes to this operation across all 1 revision of this API.