When building AI agents that need to receive email, you have three options: polling, webhooks, and long-polling. Each has trade-offs. Here is how to choose.

Option 1: Polling

// Check for new email every 5 seconds
while (true) {
  const emails = await listEmails(inboxId);
  if (emails.length > 0) break;
  await sleep(5000);
}

Pros: Simple to implement, no public URL required.

Cons: Burns API quota. 5-second delay on average. Keeps a process alive indefinitely. Hard to scale to many agents.

Option 2: Webhooks

AgentMailr can POST to your server the moment an email arrives.

POST https://youragent.com/email-webhook
{
  "event": "email.received",
  "data": { "inbox_id": "...", "otp_codes": ["123456"] }
}

Pros: Instant delivery, no wasted requests, scales well.

Cons: Requires a public HTTPS endpoint. More complex to set up for local development. Hard to use in simple scripts.

Option 3: Long-Polling (Recommended for AI Agents)

// Block until email arrives, then return immediately
GET /v1/inboxes/{id}/otp?timeout=60

Pros: No public endpoint needed. Returns the moment the email arrives (not every 5 seconds). Simple one-line call. Works in any environment including local scripts and CI.

Cons: Keeps an HTTP connection open for up to the timeout duration.

When to Use Each

ScenarioBest Option
Simple agent scriptLong-poll
Playwright / Cypress testLong-poll
Production server with persistent agentsWebhook
n8n / Make.com workflowLong-poll
Real-time dashboard updatesWebhook

Long-Poll is the Default Choice

For most AI agent use cases, long-polling is the right default. It is simple, it blocks until the email arrives, and it requires no infrastructure beyond the API call itself.