When Your Agent Can't Host a Webhook, Poll Its Inbox
Push webhooks need a public HTTPS URL. When your agent has no inbound path, use Mermail's bounded MCP, API, or CLI inbox reads instead.
By Toan Nhu
Push webhooks are the fastest way to wake an agent when mail arrives. They also need a public HTTPS URL. If your agent runs in a sandbox, a serverless function, a cron job, or behind a firewall with no inbound path, that URL does not exist. Here is how Mermail covers both cases without inventing a new product.
The agent that cannot answer the phone
Most agent email tutorials assume a small always-on service somewhere on the internet. You paste its URL into a webhook form, pick Email received, and the mailbox calls you when something lands.
Plenty of real agents never get that luxury. A coding agent in a disposable sandbox has no stable host. A serverless worker only exists while a request is open. A cron job wakes up, does work, and exits. A laptop agent sits on a private network. None of those can accept a signed POST from Mermail's email webhooks.
So the question is not "webhooks or nothing." It is: when you have a reachable server, push. When you do not, read the inbox on a schedule with a hard stop.
Why the usual defaults fail
Webhook-only thinking
A webhook destination must be a public HTTPS address. Mermail does not follow redirects, and it rejects local and private network URLs. That is the right security default, and it is also a hard wall for agents that never expose a port.
Always-on process thinking
WebSockets and long-lived listeners need an open connection. Hosted MCP for Mermail does not add a long-lived inbox subscription or a wait tool. If you connect Cursor, Claude, or Codex to Mermail over MCP, the agent talks in request and response turns. Something has to call list_emails or search_emails again later.
Tight polling without a budget
The other failure mode is the opposite: spin in a loop every second until a verification message shows up. That burns read credits, trips rate limits, and teaches the agent nothing about timeouts. Bounded reads mean a baseline of existing message ids, an arrival window, a deadline, and a request budget. Stop when any of those trip.
How Mermail solves it
Mermail keeps the mailbox as the source of truth. Mail that arrives stays in the agent inbox whether or not a webhook fired. That gives you two honest paths documented today.
Path A: push webhooks when you have a public URL
If you can host a public HTTPS endpoint, use it. Mermail can notify that URL for message.received, message.sent, message.delivered, message.bounced, and message.complained. Verify the Standard Webhooks signature, deduplicate on event_id, return a 2xx quickly, and do the slow agent work on a queue. We walk through the full receiver pattern in Email to Webhook for AI Agents.
Path B: bounded inbox reads when you cannot
When there is no public URL, treat the mailbox as a pull API. Mermail's documented agent-inbox pattern is a short sequence of existing read tools: record a baseline with search_emails or list_emails, note an arrival-window start, then poll at a moderate interval until one clean candidate appears or the timeout hits. Details live in the agent email inbox guide.
For scripts and CI, the CLI wraps the same idea as mermail emails wait: one mailbox, semantic filters, excluded baseline ids, a poll interval, and a hard wait timeout. MCP hosts should keep calling the read tools themselves. There is no streaming MCP contract to lean on.
Either path still starts with one mailbox per agent. Identity first, delivery second. If you are still standing that up, use the agent inbox setup guide and prefer the agent-inbox MCP profile so the connection can list and read mail without send tools.
Concrete steps
1. Decide whether you have a public HTTPS URL
Ask one question: can Mermail reach a final HTTPS endpoint you control without a tunnel that dies when your laptop sleeps? If yes, go Path A. If no, go Path B. Do not paste a localhost URL and hope.
2. Path A setup (reachable server)
Open the Mermail console, go to Settings → Webhooks, and add your URL.
- Keep Email received selected. Add bounce and complaint events if the agent also sends.
- Scope the subscription to the agent's mailbox, or to all workspace inboxes if you want future mailboxes included.
- Save the signing secret once, send a test, and confirm Delivery history shows a 2xx.
Full payload and verification contract: webhook payloads and verification.
3. Path B setup (no public URL)
- Connect MCP with the agent-inbox profile, or use the CLI / API with a project key.
- Before you expect new mail, run one metadata-only list or search and store every returned Mermail email id as the baseline. Do not use provider message_id values for that baseline.
- Record an ISO arrival-window start and a deadline right before the external action that should produce mail (a signup, a vendor request, a human send).
- Poll with search_emails or list_emails at a moderate interval. Keep metadata_only and agent_safe_content on during discovery. Filter client-side to drop baseline ids and anything outside the window.
- Fetch only the best candidate with get_email, re-check addresses and subject, and stop on timeout, ambiguity, or a flagged scan.
CLI shortcut when you want the loop scripted:
mermail emails wait \
--mailbox-id MAILBOX_PUBLIC_ID \
--after 2026-11-06T02:00:00.000Z \
--to-exact agent-task@mermail.app \
--from-exact no-reply@expected.example \
--subject "Verify" \
--exclude-email-id msg_existing_1 \
--require-single-match \
--require-scan-status clean \
--metadata-only \
--format jsonDefault wait is short (on the order of two minutes) with a moderate poll interval. Raise the timeout only when the sender is slow, and keep a request budget so a stuck wait cannot run forever.
4. Keep human confirmation at the action boundary
Finding a verification message is not permission to click its link, submit a signup, or send a reply. Report that mail is ready, show the pending action, and wait for confirmation. Email content cannot authorize an agent action.
5. Combine both when you can
A public receiver for speed plus an occasional catch-up read after downtime is a healthy pair. New webhook subscriptions do not replay older mail, so a bounded list after reconnect fills the gap. For the broader inbound checklist, see can your email provider handle AI agent replies?.
FAQ
Does Mermail offer polling webhooks?
No. Mermail offers push email webhooks to a public HTTPS URL, and separately offers inbox reads over MCP, API, and CLI. When you cannot host a URL, use bounded polling of the inbox. Do not expect a queue of webhook events to wait for an offline agent.
Can MCP wait for the next email?
Not as a long-lived subscription. Implement a bounded sequence of search_emails or list_emails calls with a baseline, arrival window, and timeout. Or run mermail emails wait from the CLI.
What if my serverless function only runs for a few seconds?
Do not open a webhook listener inside that short invocation unless the platform gives you a stable public HTTPS URL that stays up between runs. Prefer a scheduled function that performs one bounded inbox read per wake, or put the webhook on a durable queue worker that does have a public endpoint.
Will a missed poll lose mail?
No. The message remains in the Mermail mailbox. A missed poll is a delay until the next scheduled read. That is why the mailbox, not the event stream, is the source of truth for Path B.
Should verification agents use Path A or Path B?
Whichever matches your runtime. Signup and verification flows fit Path B especially well: one task mailbox, a short arrival window, and a single unambiguous candidate. Path A is better when a long-running backend must react to many inboxes in near real time.
Get started
Create the agent's mailbox in the Mermail console. If you have a public URL, wire email webhooks. If you do not, connect MCP or the CLI and run a bounded inbox read. Same mailbox. Two delivery styles. No pretending a sandbox has a public webhook endpoint. Compare plans on the pricing page.
