Is MailWebhook an AI email agent?

MailWebhook is the email intake layer for AI agents. It receives messages from supported mailboxes and delivers signed JSON events to your worker. Your application chooses the agent framework, model, prompt, queue, validation, and review flow.

Can Gmail trigger an AI agent?

Yes. Connect a Gmail or Google Workspace mailbox to MailWebhook, create a route, and deliver matching messages to your agent worker as signed JSON webhook events.

Can Microsoft 365, Office 365, or Outlook email trigger an AI agent?

Yes. MailWebhook supports Microsoft 365, Office 365, and Outlook mailbox sources. The provider page explains the Microsoft-specific email-to-webhook path.

Does the webhook payload include attachment files?

No. Webhook payloads include attachment descriptors such as id, filename, content type, size, inline status, and optional SHA-256 digest. Your backend requests a short-lived download URL only when the workflow needs the file.

Does MailWebhook send raw .eml files to the model?

No. MailWebhook delivers the configured route pipeline output to your endpoint. The default Generic JSON payload is structured JSON, and Custom JSON can shape a smaller route-specific body for the worker.

Can MailWebhook reduce token usage for AI email workflows?

MailWebhook can help by routing messages before model calls, representing attachments as metadata, and letting you use Custom JSON to send only selected fields to the worker. Actual token usage depends on what your worker passes to the model.

Can agents inspect past email events?

Your backend can call the Events API to list recent events, inspect a specific event, review delivery attempts, and queue replay. Treat this as bounded operational context, not a long-term semantic memory system.

How are webhook deliveries verified?

Verify X-MailWebhook-Signature against the raw request body using the route signing secret selected by kid. Use X-Idempotency-Key to dedupe retries and replay.

Can I use a custom JSON shape for my agent?

Yes. Custom JSON can map parsed message fields, headers, attachments, route context, and helper outputs into a route-specific webhook body. Use it when the first agent decision should receive a smaller contract than the default Generic JSON shape.

Does MailWebhook replace Gmail API, Microsoft Graph, or IMAP?

MailWebhook replaces the polling and intake layer for supported email-to-webhook workflows. Use provider APIs directly when your application needs mailbox search, folder management, message mutation, or user-facing inbox features outside the MailWebhook intake flow.

How should I handle prompt injection in email?

Treat email as untrusted input. Use MailWebhook to verify delivery, route deterministically, shape payloads, keep attachments out of the first prompt, and add review before high-risk writes. Keep prompt-injection defenses and tool permissions in your agent system.

Is this the same as email to webhook?

It uses the same MailWebhook delivery foundation, but this page is for AI-agent workflows. The broader email-to-webhook page covers general developer use cases.

Email for AI Agents

Email for AI agents, delivered as signed events

MailWebhook turns Gmail, Microsoft 365, Outlook, IMAP, and hosted mailbox messages into JSON events your agent workers can verify, queue, replay, and enrich only when needed.

Start free View payload docs

Built for AI agent email intake, email-triggered workflows, LLM routing, document intake, support triage, and agent systems that should not poll mailboxes or ingest raw MIME by default.

agent-email-event

Mailbox source
  -> MailWebhook route
  -> signed JSON event
  -> queue or worker
  -> selected model context
  -> review or system write

Connect any supported mailbox source

GmailMicrosoft 365OutlookIMAPHosted mailbox

What is an email API for AI agents?

An email API for AI agents turns incoming mailbox messages into events that agent systems can process. Instead of letting the agent poll Gmail, Microsoft Graph, or IMAP directly, your backend receives a signed JSON webhook when a matching message is processed.

MailWebhook handles the mailbox connection, route match, payload shape, delivery signature, idempotency key, attachment metadata, retry history, and replay path around that event. Your worker decides what the model sees, when to fetch files, and when a human review step is required.

Related developer pages: email webhook API and email to JSON.

Direct mailbox access creates the wrong boundary for production agents

Giving an agent direct mailbox tools can be useful for a prototype. Production email workflows usually need a smaller, more deterministic boundary before the model sees untrusted content.

Polling loops

Mailbox polling adds delay, cursor state, duplicate handling, rate-limit behavior, and provider-specific failure modes to the agent runtime.

Model context waste

Full threads, quoted replies, HTML, signatures, tracking markup, and raw MIME can reach the model before the workflow knows what matters.

Attachment timing

Fetching PDFs, images, spreadsheets, or base64 blobs too early increases transport cost and model context without proving the file is needed.

Credential blast radius

Direct mailbox credentials inside the agent runtime increase the cost of a prompt mistake, tool bug, or compromised worker.

Operational recovery

Agent systems still need idempotency, retries, event history, replay, and clear review boundaries around business writes.

Put MailWebhook before the agent

MailWebhook is the intake layer. Your agent framework, queue, model, validation code, and business system remain under your control.

Connect the source mailbox
Use Gmail, Microsoft 365, Office 365, Outlook, IMAP, hosted mailboxes, or a loopback test mailbox for setup.
Route the messages that matter
Use route rules to match the mailbox address and workflow conditions before delivery.
Choose the payload
Start with Generic JSON for a stable normalized email shape, then use Custom JSON or transform steps when the agent workflow needs a smaller route-specific contract.
Deliver a signed event
MailWebhook sends the route pipeline output to your endpoint with signature and idempotency headers.
Let the worker decide model context
Your queue or worker stores the event, reduces the fields, fetches attachments only when needed, calls the model, and routes outputs through validation or review.
Inspect and replay
Use event history, delivery attempts, retries, and replay for debugging and recovery.

Give the agent a payload contract, not a mailbox

A useful AI email workflow starts with a deterministic event. The default Generic JSON payload is complete and stable. For token-sensitive agent paths, use Custom JSON to emit only the fields your worker needs for the first decision.

Payload element	Current MailWebhook source	Why it matters for agents
event.id	Generic JSON event.id or Custom JSON ctx.event_id	Lets the worker correlate logs, event history, attempts, and replay.
event.route_id	Generic JSON event.route_id or Custom JSON ctx.route_id	Lets the agent workflow apply route-specific policy.
message.message_id	Generic JSON message.message_id or Custom JSON message.message_id	Needed for idempotency correlation and attachment URL requests.
Sender and recipients	message.from, message.to, message.reply_to, message.cc, message.bcc	Helps classify workflow ownership without giving the model a whole inbox.
Subject and dates	message.subject, message.date, meta.received_at	Useful for triage, deadlines, and ordering.
Text and HTML	body.text, body.html, or Custom JSON from message.text and message.html	Lets the worker choose a text-only, trimmed, or transformed input before the model call.
Headers	Generic JSON message.headers or Custom JSON message.headers	Available when workflows need provider, sender, or threading signals.
Attachments	body.attachments or Custom JSON message.attachments	Descriptors let the workflow decide whether to fetch files.
Source	Generic JSON meta.source or Custom JSON ctx.source_type	Helps distinguish Gmail, Microsoft 365, IMAP, hosted, API, or CLI source paths.

Custom JSON: compact agent payload

{
  "version": "v1",
  "vars": [
    {
      "name": "plain_text",
      "expr": {
        "call.transform.html_to_text": {
          "html": { "var": "message.html" },
          "text": { "var": "message.text" }
        }
      }
    }
  ],
  "output": {
    "event_id": { "var": "ctx.event_id" },
    "route_id": { "var": "ctx.route_id" },
    "source": { "var": "ctx.source_type" },
    "message_id": { "var": "message.message_id" },
    "subject": { "var": "message.subject" },
    "from": { "var": "message.from[0].email" },
    "text_preview": { "substr": [{ "var": "vars.plain_text" }, 0, 4000] },
    "attachments": { "var": "message.attachments" }
  }
}

This Custom JSON mapper shape uses the current MailWebhook mapper roots and helpers. It emits a smaller webhook body for the first agent decision while preserving message_id and attachment descriptors for later download.

Shape email into JSON for your workflow Read Custom JSON docs Read Generic JSON docs

Keep attachments out of the model path until they matter

MailWebhook webhook payloads include attachment metadata, not file bytes. Your worker can inspect filename, content type, size, inline status, and digest before deciding whether the workflow needs the attachment.

When the file is needed, your backend requests a short-lived download URL with the project API key. The project API key stays server-side. Returned URLs are temporary credentials and should not be logged or sent to browsers.

Read attachment download docs

Attachment descriptor in payload

{
  "id": "att-1",
  "filename": "invoice-1042.pdf",
  "content_type": "application/pdf",
  "size": 93259,
  "is_inline": false,
  "sha256": "059a0f5260487bbe663994de1fd641401fec76ac9f6bddfe5b53ae60d4bb2d86"
}

Fetch bytes only when needed

curl "https://app.mailwebhook.com/v1/messages/{encoded_message_id}/attachments/{attachment_id}/url" \
  -H "X-API-Key: <project_api_key>"

Verify the event before your agent acts

Every MailWebhook delivery includes a signature header and an idempotency key. Verify the signature against the raw request body before trusting the payload, then store the idempotency key before side effects.

Delivery headers

X-MailWebhook-Signature: t=<unix>, kid=<kid>, v1=<base64_hmac_sha256>
X-Idempotency-Key: <sha256(message_id|route_id)>

Read raw body bytes.
Verify X-MailWebhook-Signature with the route signing secret selected by kid.
Parse JSON only after signature verification.
Store X-Idempotency-Key with the work item.
Enqueue durable work.
Return 204 after acceptance.

Node receiver excerpt

app.post(
  "/agent-email-events",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.get("X-MailWebhook-Signature") || "";
    const idempotencyKey = req.get("X-Idempotency-Key") || "";

    if (!verifyMailWebhookSignature(signature, req.body, secretsByKid)) {
      res.sendStatus(401);
      return;
    }

    const payload = JSON.parse(req.body.toString("utf8"));

    await enqueueEmailAgentEvent({
      idempotencyKey,
      eventId: payload.event.id,
      routeId: payload.event.route_id,
      messageId: payload.message.message_id,
      subject: payload.message.subject,
      from: payload.message.from,
      text: payload.body.text ?? "",
      attachments: payload.body.attachments
    });

    res.sendStatus(204);
  }
);

Use the signed delivery docs for the full verifier. The signature must be checked against raw request body bytes, not parsed or reserialized JSON.

Read signed delivery docs See email webhook API

Give agents operational context without giving them the whole inbox

MailWebhook records delivery events and attempts so your system can inspect what arrived, whether the receiver accepted it, and what happened during delivery. That history can support agent workflows that need bounded operational context, audit trails, or recovery after downstream failures.

Events API surface

curl "https://app.mailwebhook.com/v1/events?limit=10" \
  -H "X-API-Key: <project_api_key>"

curl "https://app.mailwebhook.com/v1/events/{event_id}" \
  -H "X-API-Key: <project_api_key>"

curl "https://app.mailwebhook.com/v1/events/{event_id}/attempts" \
  -H "X-API-Key: <project_api_key>"

curl -X POST "https://app.mailwebhook.com/v1/events/{event_id}/replay" \
  -H "X-API-Key: <project_api_key>"

Check whether a route recently received a similar message.
Confirm whether a downstream worker accepted, rejected, or timed out.
Inspect HTTP status, latency, and captured request or response previews when available.
Replay an event after fixing a receiver, endpoint credential, or route pipeline issue.

Event history is bounded operational context. It is not a vector database, semantic memory, or long-term knowledge store. Teams that need long-term memory should export selected summaries into their own storage.

Read retries and replay docs Read API key docs

Use the mailbox source that fits the agent workflow

Gmail

Trigger agent workers from Gmail or Google Workspace messages through MailWebhook routes.

Gmail for AI agents

Microsoft 365, Office 365, and Outlook

Convert Microsoft and Outlook mailbox messages into webhook events for agent workflows.

Microsoft 365 email for AI agents

IMAP

Move IMAP polling, UID tracking, parsing, and delivery retries out of the agent runtime.

Replace IMAP polling for AI agents

Hosted mailbox

Use a MailWebhook-hosted address when the workflow needs a dedicated intake inbox.

Hosted mailbox intake

Loopback testing

Use the onboarding loopback mailbox and test destination for a quick first pass before connecting production sources.

Loopback testing docs

Mailbox setup guides

Gmail setup Microsoft 365 setup IMAP configuration Hosted mailbox setup

Agent workflows that start with email events

Each pattern delivers structured email events for AI agents to your worker, so the model only sees what the workflow selects.

Support triage

Receive the incoming support email, classify intent from selected fields, fetch attachments only when needed, and create a draft ticket for review.

Document intake

Inspect attachment descriptors first, fetch PDF or spreadsheet bytes in a worker, then run document processing with explicit size and type policy.

CRM lead routing

Turn inbound lead emails into normalized events, enrich only the relevant fields, and keep system writes behind deterministic validation.

Finance inbox automation

Route vendor messages, preserve invoice attachment metadata, and put approval or exception handling before ERP writes.

Internal operations assistants

Let internal agents react to shared mailbox events without owning the mailbox connection or parsing raw MIME.

Want this workflow built and operated for you? Explore managed email data entry automation.

Choose the right email boundary for the agent

Approach	Best for	Tradeoff
Direct Gmail, Microsoft Graph, or IMAP access	Personal assistants, search-heavy workflows, prototypes, and inbox-native tasks.	The agent runtime owns mailbox credentials, polling/cursor behavior, parsing, attachment timing, and duplicate handling.
MailWebhook event gateway	Production AI workflows that need mailbox events, signed delivery, idempotency, payload shaping, attachment references, retries, replay, and inspection.	The model call and agent orchestration remain in your own worker or framework.
Parser-first tools	Workflows centered on extracting fields from a known document or email format.	Parser output may still need event delivery, idempotency, attachment policy, replay, and review boundaries around an agent.
Workflow automation tools	Business-user orchestration, simple automations, and low-code integrations.	Agent systems still need a reliable, compact mailbox intake contract before model context and downstream writes.

Compare email webhook API options Replace IMAP polling

Treat every email as untrusted input

Emails can contain prompt text, quoted history, hidden HTML, tracking markup, spoofed-looking headers, and attachments from unknown senders. MailWebhook gives your application a deterministic intake point before model reasoning starts.

Step 1
Verify the webhook signature.
Step 2
Store the idempotency key and event id.
Step 3
Reduce the payload to the fields required for the first decision.
Step 4
Keep attachment bytes out of the prompt until the workflow explicitly needs them.
Step 5
Run deterministic validation before system writes.
Step 6
Use human review for high-risk outputs such as account changes, payments, legal messages, customer replies, or destructive actions.

This reduces the amount of untrusted content sent to the model. It does not replace agent prompt-injection defenses, tool permissioning, output validation, approval workflows, or audit logging.

Build the first AI email trigger

Create a MailWebhook account.
Choose a loopback test mailbox or connect Gmail, Microsoft 365, Outlook, IMAP, or a hosted mailbox.
Save a public HTTPS endpoint for your worker.
Create a route with map.generic_json or a Custom JSON payload.
Send a test email and inspect the delivery.
Verify signatures, store idempotency keys, enqueue the event, and return 204.
Fetch attachment bytes later through the attachment download API only when the worker needs them.

Start free First webhook quickstart Test email and payload inspection

Start free, scale when you need to

The Free plan includes 300 emails/month at no cost. Paid plans start at $29/per month with a 30-day free trial.

Start free

See full pricing

HMAC-signed webhook delivery
Automatic retries with backoff
Event inspector and replay
Idempotency keys for safe dedupe

Frequently asked questions

Give your agent email events, not mailbox plumbing

Connect a mailbox, route matching messages, and deliver signed JSON events to the worker that decides what the model should see.

Start free View email webhook API