Email to Webhook for AI Agents: Receive Mail Without Polling

Most agents check email the slow way. Every few minutes they ask the mailbox "anything new?", usually hear "no", and burn API calls, tokens and time doing it. When a verification code or a customer reply finally lands, the agent might not notice for another five minutes.

An email webhook flips that around. The mailbox calls your agent the moment mail arrives, with the message already packaged as JSON. This guide shows how to turn email into webhook events for an AI agent with Mermail, how to verify every delivery, and how to keep a forwarded email from steering your agent somewhere it shouldn't go.

Polling vs webhooks for agent email

• Polling is simple to start: call the list-messages endpoint on a timer. But most calls return nothing, latency equals your polling interval, and a fleet of agents multiplies the waste.
• Webhooks push each event once it happens. The agent sleeps until there is real work, and a reply or one-time code reaches it in seconds instead of minutes.
• Use both, carefully. Webhooks for speed, plus an occasional catch-up read through the Email API after downtime, because a new subscription doesn't replay mail that arrived before it existed.

If you are still choosing how your agent talks to Mermail at all, start with MCP, CLI or REST API for agent email. Webhooks sit alongside any of them.

Which email events can trigger your agent

Mermail can send five email events to your URL:

• message.received: a new inbound message was saved in a selected mailbox. This is the one most agents need.
• message.sent: Mermail accepted a message for sending. It does not confirm delivery, and drafts or scheduled sends don't emit it.
• message.delivered: the recipient's mail server confirmed delivery.
• message.bounced: a bounce was reported. Pair it with hard vs soft bounce handling.
• message.complained: a recipient marked the mail as spam. Your agent should stop mailing that person.

Set up an email webhook in Mermail

1. Get a public HTTPS URL. Your app, a serverless function or a workflow tool can provide it. Local and private network addresses aren't accepted, and Mermail doesn't follow redirects, so use the final URL.
2. Add the webhook. In the Mermail console, open Settings, then Webhooks, and click Add webhook. Paste the URL, keep Email received selected, and pick specific mailboxes or all workspace inboxes, which also covers mailboxes you create later.
3. Save the signing secret. It is shown once, right after creation. Put it in your receiver's secret store, never in frontend code or logs.
4. Send a test. Click Send test, wait about 30 seconds, then open Delivery history. A test carries test: true and synthetic data, so make sure your handler doesn't act on it.

Prefer code? Create the same endpoint with the REST API using a workspace-scoped API key with admin authority. Create, test and retry calls need an Idempotency-Key header:

curl -X POST "https://console.mermail.app/api/v1/workspaces/$WORKSPACE_ID/webhooks" \
  -H "x-api-key: $MERMAIL_API_KEY" \
  -H "Idempotency-Key: agent-inbox-webhook-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://agent.example.com/email-events",
    "eventTypes": ["message.received", "message.bounced", "message.complained"],
    "allInboxes": false,
    "mailboxIds": ["YOUR_MAILBOX_PUBLIC_ID"]
  }'

Agents can also manage webhooks over Mermail's MCP server with tools such as create_webhook and test_webhook. Those write tools require an explicit confirmation step, and the restricted agent-inbox MCP profile can't touch them at all, which is what you want: an agent shouldn't quietly start forwarding your mail to a new URL. Full reference: webhook payloads and verification.

What your agent receives

Each delivery is a JSON POST. An inbound email looks like this (identifiers are illustrative):

{
  "event_id": "a78af22a-1037-449c-9df9-ddfa0c4f5d64",
  "event_type": "message.received",
  "occurred_at": "2026-09-23T09:00:00.000Z",
  "schema_version": "1",
  "inbox_id": "2c5253b9-b0e8-4a7b-9e7c-15d3ad22d89d",
  "data": {
    "message_id": "message_example",
    "thread_id": "thread_example",
    "from": ["sender@example.com"],
    "to": ["inbox@example.com"],
    "subject": "Hello",
    "text": "Hello from the sender.",
    "scan_status": "clean",
    "attachments": []
  }
}

• Use thread_id to load the conversation history before the agent replies, so it answers in context.
• Attachments arrive as metadata only: filename, type, size and id. Fetch the bytes through the authenticated Email API if the agent actually needs them.
• A missing body isn't an empty body. If data.content_omitted_reason is set (for example content_safety or payload_limit), fetch the message through the API when that's permitted instead of guessing.

Verify every delivery before the agent acts

Anyone can POST JSON to a public URL, so your receiver must prove each event came from Mermail. Every delivery carries webhook-id, webhook-timestamp and webhook-signature headers in the Standard Webhooks format. A compatible library is the easy path. If you write it yourself:

1. Keep the raw request body bytes before parsing JSON.
2. Reject timestamps outside a short tolerance, normally five minutes.
3. Strip the whsec_ prefix from your secret and base64-decode the rest.
4. Compute HMAC-SHA256 over webhook-id.webhook-timestamp.raw_body and base64-encode it.
5. Compare with the v1 signature using a constant-time comparison.
6. Check the workspace and event type, then deduplicate by event_id.

import base64, hmac, hashlib, time

def verify(raw_body: bytes, headers: dict, secret: str) -> bool:
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for part in headers["webhook-signature"].split():
        version, _, sig = part.partition(",")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False

Acknowledge fast, think later

Mermail waits 10 seconds for your response. An LLM call can easily take longer, so don't run the agent inside the request handler.

• Store, then return 2xx. Write the verified event to a queue or table, respond immediately, and let a worker run the agent.
• Expect duplicates and odd ordering. Retries reuse the same event_id and payload. Keep dedup records for at least seven days, the payload retention window, and use occurred_at rather than arrival order.
• Know what retries. Timeouts, connection errors, 408, 429 and 5xx responses retry with backoff for about 24 hours. Other responses, including redirects, fail without an automatic retry.
• Watch the limits. A workspace can have 10 endpoints and receives up to 60 delivery attempts per minute. Payloads are capped at 1 MiB.

Agent patterns that work well with email webhooks

• Verification codes. A signup agent waits for message.received on its own mailbox instead of polling, then reads the code. See handling AI agent signups and verification emails.
• Reply triage. Each inbound reply is labeled and routed: interested, not now, unsubscribe, out of office. See AI email categorization with plain-language rules.
• Approved drafts. A new customer email or prospect reply triggers a drafted answer that a person approves before it goes out, the same pattern as research, draft, approve outreach.
• List hygiene. message.bounced and message.complained events let your handler suppress the address right away, so the agent can't keep mailing someone who bounced or complained.

FAQ

What is an email webhook?

It's an HTTP request a mail service sends to your URL when something happens to email, such as a new message arriving or a bounce. Your code reacts to it instead of repeatedly checking the inbox.

Can an AI agent receive emails without polling?

Yes. Subscribe a webhook to message.received and the agent's backend is notified as each message is saved, with the sender, subject, thread id and available body in the payload.

Do Mermail webhooks cost extra?

No. Webhooks are available to all workspaces, and there's no additional webhook delivery fee.

Do webhooks include attachments?

Only attachment metadata. Download the file through the authenticated Email API when you need its contents.

What happens if my endpoint is down?

Failed deliveries retry with increasing delays for about 24 hours, and you can retry an unexpired failed delivery manually from Delivery history.