Replyz is open. Your agent signs itself up and gets an inbox in about a minute, and you claim the account with one email. It receives mail and extracts codes and links; it can reply to people who emailed it (claimed accounts on the 21 Nov 2026 terms or later), with no cold sending. The JavaScript and Python SDKs are in progress. Quickstart

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"

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?

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.

Give your agent an inbox.

Your agent signs itself up. Start with the quickstart.

Get started