Replyz / Guides / Wait for an email in code
How to wait for an email in code.
A sign-up, a password reset or a receipt ends with an email, and your program has to know when it arrives. There are three ways to wait: poll, use a webhook, or hold a request open. This guide compares them for an AI agent or a script, and shows how the Replyz wait call and event feed work. Use it only where a service's terms allow automated sign-ups.
Short answer. Prefer a long poll: one request the server holds open until a matching email arrives or the time runs out. With Replyz that is GET /v1/inboxes/{id}/wait, up to 60 seconds a call, with filters on sender, subject and time.
What are the three ways to wait for an email?
Polling
Ask for new mail on a timer. Simple, works anywhere, but it wastes requests and adds delay up to one interval.
Webhook
The service calls a public URL of yours when mail arrives. Fast, but you need a reachable server and a way to check the call is genuine.
Long poll
One request that the server holds open until something arrives. No public URL needed, and no timer to tune.
An AI agent on a laptop or in a sandbox usually has no public URL, so a webhook is awkward for it. Polling works but burns tool calls and context. A long poll fits an agent best: it makes one call and gets the answer when there is one.
How does the Replyz wait call work?
curl -s "https://api.replyz.io/v1/inboxes/$INBOX_ID/wait?from=*@service.example&timeout=25" \ -H "Authorization: Bearer $REPLYZ_API_KEY"
- It checks at once. If a message matches, it answers immediately, newest first (up to
limit, default 10). It never waits to fill the limit. - Otherwise it holds. Every newly stored message of the account wakes it up, and it answers as soon as something matches or the time passes.
- On timeout it answers
{"status": "timeout", ...}with HTTP 200. That is a normal result, not an error: call again. - Filters, all of which must match:
from(a glob on the sender address),subject(a substring),thread_idandsince. timeoutis 0 to 60 seconds.0checks once and answers at once.
Add extract=otp,link and the same call also returns the verification code and link; see how an agent gets a verification code. In the CLI, replyz wait repeats holds until its own timeout (60 seconds by default). Through MCP, wait_for_email holds up to 45 seconds a call.
What if the email arrived before you started waiting?
By default wait looks back 10 minutes, so a message that came just before the call is returned at once. Within that window the same message comes back on every call, marked returned_before, unless you pass exclude_returned=true or a later since. Trigger the email first, then wait, and do not set since to the exact moment of your call: use the default, or a minute or two earlier.
How do you watch every inbox at once?
The event feed, GET /v1/events, is one ordered list per account across all its inboxes, read with a cursor. Today it has one event for each stored inbound message (message.received). Pass next_after as after on the next call, and add wait (0 to 60 seconds) to make it a long poll.
Does Replyz have webhooks?
No. The wait call and the event feed are the ways to learn about new mail.
What are the limits?
- At most 5 holds at the same time per account, shared by
waitand the event feed. A call that answers at once does not use a slot. - If the account is expired or suspended,
waitdoes not hold: it answers at once with any matching stored mail.
See the CLI for replyz wait, the MCP server for the tools, and Replyz for AI agents to set it up.
Frequently asked questions
How do I wait for an email in code?
Use a long poll if the service offers one: one request that the server holds open until a matching email arrives or the time runs out. With Replyz that is GET /v1/inboxes/{id}/wait, which holds up to 60 seconds and answers as soon as something matches.
What is the difference between polling, webhooks and a long poll?
Polling asks again and again on a timer. A webhook has the service call a public URL of yours when mail arrives. A long poll is one request that the server keeps open until there is something to return. An agent on a laptop usually cannot receive webhooks, because it has no public URL.
Does Replyz have webhooks?
No. Replyz has no webhooks. You learn about new mail with the wait call on one inbox, or with the event feed GET /v1/events, which can also hold open for up to 60 seconds and covers every inbox of the account.
What if the email arrives before I start waiting?
wait looks back 10 minutes by default, so mail that arrived just before the call is returned at once. Use exclude_returned=true to skip messages that were already returned.
How many waits can be open at once?
At most 5 per account, shared between wait and the event feed. A call that answers at once does not use a slot.