MailWebhookMailWebhook
Email Webhook API

Email webhook API for inbound email events

MailWebhook receives email from Gmail, Microsoft 365, IMAP, or hosted mailboxes, normalizes each message, and sends your application signed JSON webhook POSTs.

Start freeView endpoint docs

Built for inbound email webhooks, receive-email API workflows, email parsing, and email-to-JSON delivery.

POST /mailwebhook HTTP/1.1
Content-Type: application/json
User-Agent: mailwebhook/...
X-Idempotency-Key: 6b8b7f9e...
X-MailWebhook-Signature: t=1782478472, kid=whsec_123, v1=...

An email webhook API for developers who want inbound email events, not another mailbox worker. Use it as an inbound email API or receive-email API without building mailbox polling and MIME parsing yourself.

What is an email webhook API?

An email webhook API turns received email into HTTP events your application can process. Instead of polling a mailbox or wiring mailbox-provider APIs yourself, your app receives a JSON POST when a matching message is processed. This is the core of an inbound email API and a receive-email API workflow.

MailWebhook handles the source mailbox, route matching, payload mapping, delivery headers, signature generation, idempotency key, event history, and attachment URL flow around that incoming email webhook POST.

Read the endpoint contract

From mailbox event to your API endpoint

The full developer workflow in one scan. Each step names a concrete moving part so there is no setup guesswork.

  1. 01

    Connect a source

    Use Gmail, Microsoft 365, IMAP, or a MailWebhook-hosted mailbox as the email source.

  2. 02

    Create an endpoint

    Register the HTTPS URL that should receive webhook POSTs, with optional static headers and a timeout.

  3. 03

    Create a route

    Match messages by route rules and choose a generic or custom JSON pipeline.

  4. 04

    Receive the POST

    MailWebhook sends the pipeline output as the request body with JSON content type.

  5. 05

    Verify and dedupe

    Use the signature header and idempotency key before processing the event.

  6. 06

    Inspect or replay

    Use event history and replay when a delivery needs to be reviewed or sent again.

A webhook request your backend can verify

Each delivery is an HTTP POST. The request body is exactly the selected route pipeline output. For the default generic JSON mapper, that means a deterministic object with message metadata, normalized people arrays, body text or HTML, attachment metadata, and source metadata.

  • POST request with Content-Type: application/json.
  • X-MailWebhook-Signature includes a timestamp, key id, and base64 HMAC-SHA256 signature.
  • X-Idempotency-Key is deterministic for the message and route.
  • Endpoint static headers are included, so receivers can use API keys or authorization headers.
  • Attachment file bytes are not inlined into the webhook body; payloads carry attachment metadata.

Verify against the raw request body bytes, not a parsed and re-serialized JSON object.

POST /mailwebhook HTTP/1.1
Content-Type: application/json
User-Agent: mailwebhook/...
X-Idempotency-Key: 6b8b7f9e...
X-MailWebhook-Signature: t=1782478472, kid=whsec_123, v1=<base64_hmac_sha256>
Authorization: Bearer receiver-token

API operations for routes, endpoints, events, and attachments

MailWebhook exposes a public API scope for the resources developers need around webhook delivery: endpoints, routes, event history, event replay, billing plan readout, attachment URL retrieval, and onboarding route-pair creation.

API areaOperationsVisitor value
EndpointsCreate, list, read, update, deleteManage HTTPS webhook targets.
RoutesCreate, list, read, update, deleteConnect rules and pipelines to endpoints.
EventsList events, read one event, list attemptsInspect what happened after email intake.
ReplayReplay an eventRecover from receiver-side failures or test downstream handling.
AttachmentsGet a signed attachment URLFetch attachment bytes only when your app needs them.
OnboardingCreate or reuse an HTTPS endpoint and route pairProvision the common setup path in one call.
BillingRead current planSurface plan limits in tooling.
View route docsView endpoint docs

Create or reuse an HTTPS endpoint and route pair

For common integrations, MailWebhook can create or reuse an HTTPS endpoint plus route pair from one request. The route defaults to the generic JSON mapper unless you provide a custom pipeline.

Request
{
  "route_name": "Accounts payable intake",
  "endpoint_url": "https://api.example.com/mailwebhook",
  "endpoint_headers": {
    "Authorization": "Bearer receiver-token"
  },
  "timeout_s": 10,
  "rule": {
    "subject_contains": ["Invoice"]
  },
  "pipeline": {
    "steps": [
      { "name": "map.generic_json", "args": {} }
    ]
  },
  "enabled": true
}
Response
{
  "endpoint_id": "0f5a83e4-8220-4f0d-917e-6be20d9dc32d",
  "route_id": "2f3713bf-88cc-46c6-aaa3-ea9d6e9d20f3",
  "endpoint_reused": false,
  "route_reused": false
}
Create your first route

Choose the JSON contract your API should receive

Send a stable normalized email event, or shape an email-to-JSON webhook to match the exact contract your receiver expects.

Generic JSON

Use the default mailwebhook.generic@1 payload when your app wants a stable normalized email event. It includes schema, event, message, body, and meta, with deterministic sorting and normalized message fields.

View generic JSON docs

Custom JSON

Use map.custom_json when your receiver expects a specific API contract. Build the output from message fields, headers, body text, attachments, route context, and extraction helpers such as URLs, reply segments, key/value pairs, tables, and DOM extraction.

View custom JSON docs

Attachment metadata in the webhook, file bytes by signed URL

MailWebhook keeps attachment file bytes out of the webhook body. The generic payload includes attachment metadata such as id, filename, content type, size, inline status, and checksum when available. Your app can request a signed URL for the file when it needs to download the attachment.

Read attachment URL docs
Attachment metadata
{
  "id": "9f5a1ded-538d-4f5f-a7a9-d3eacf9e58a0",
  "filename": "invoice-1042.pdf",
  "content_type": "application/pdf",
  "size": 93259,
  "is_inline": false,
  "sha256": "059a0f5260487bbe663994de1fd641401fec76ac9f6bddfe5b53ae60d4bb2d86"
}
Signed attachment URL
GET /v1/messages/{message_id}/attachments/{attachment_id}/url

Receive email events from the sources your team already uses

MailWebhook is the managed layer that converts supported mailbox messages into webhook events. Gmail, Microsoft 365, and IMAP do not send arbitrary webhooks natively.

Gmail and Google Workspace

Connect Gmail mailboxes, optionally scope by label, and receive normalized events as webhook POSTs.

Microsoft 365, Office 365, and Outlook

Connect Microsoft 365 and Outlook mailbox workflows, including shared mailbox targeting when delegated access allows it.

IMAP

Connect existing IMAP mailboxes without maintaining an IMAP worker in your app.

Hosted mailbox

Use a MailWebhook-hosted address when a dedicated intake inbox is cleaner than connecting an existing mailbox.

Where an email webhook API fits

Commercially relevant developer workflows that start with an inbound email event.

Support intake

Turn mailbox messages into ticket or triage events that your backend can route.

Invoice and order ingestion

Receive finance or order emails as structured events before sending them to ERP, CRM, or approval systems.

AI agent inboxes

Give an agent a clean event stream instead of raw mailbox polling and thread parsing.

Email API for AI agents

Legacy system bridges

Turn email-only notifications into HTTP events for systems that already speak JSON.

Operational alerts

Route monitoring, vendor, or partner emails into incident and workflow APIs.

Where MailWebhook fits in an email integration stack

Build it yourself, wire mailbox APIs, or use a managed email webhook layer. Here is when MailWebhook is the right choice.

Compared with mailbox APIs

Mailbox APIs expose provider primitives. MailWebhook packages mailbox intake, normalization, route matching, JSON mapping, signed delivery, event history, and replay around the email event.

Compared with parser APIs

Parser tools often focus on field extraction. MailWebhook focuses on the full delivery contract from source mailbox to your webhook endpoint.

Compared with no-code automation

No-code tools are useful for simple flows. MailWebhook gives developers a webhook receiver contract, payload control, signatures, idempotency, and API-managed routes.

Compared with MX-only inbound parse

MX-first inbound parse products are useful for dedicated domains. MailWebhook also supports existing mailbox workflows where the inbox is already the source of truth.

Email to webhook

Designed for webhook receivers that need predictable events

Address the developer reliability questions before you ship the integration.

  • Signed webhook delivery so your endpoint can verify the sender.

  • An X-Idempotency-Key header so duplicate processing can be handled safely.

  • Endpoint static headers for API keys, bearer tokens, or receiver-side auth.

  • Public endpoint URL policy that rejects private, loopback, link-local, reserved, or multicast destinations.

  • Event history, attempt details, and replay for debugging delivery workflows.

  • Attachment files fetched by signed URL instead of embedded blindly in every POST.

Read endpoint docs

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.

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

Email webhook API FAQ

What is an email webhook API?
An email webhook API receives email from a mailbox source and sends your application an HTTP event when a message matches your route. MailWebhook delivers those events as signed JSON POSTs.
Is MailWebhook an inbound email API or a webhook API?
Both terms apply depending on how the buyer searches. MailWebhook handles inbound email intake and delivers the result through webhook requests your API can receive.
Can I receive Gmail or Microsoft 365 email through the API?
Yes. MailWebhook supports Gmail, Microsoft 365, Outlook, IMAP, and hosted mailbox workflows as email sources, then delivers matching messages to your webhook endpoint.
What does the webhook request look like?
The request is a JSON POST. The default generic mapper emits top-level schema, event, message, body, and meta objects. Custom JSON routes can emit a receiver-specific shape.
How do I verify a MailWebhook request?
Use the X-MailWebhook-Signature header. It includes a timestamp, key id, and HMAC-SHA256 signature over the timestamp and raw request body.
How should my API handle duplicate events?
Webhook receivers should be idempotent. MailWebhook sends an X-Idempotency-Key header so your API can detect duplicate processing for the same message and route.
Are attachment files included in the webhook body?
No. Attachment metadata can appear in the JSON payload, and your app can fetch file bytes later through the signed attachment URL API.
Can I create endpoints and routes through an API?
Yes. MailWebhook exposes public API operations for endpoints and routes, plus an onboarding route-pair operation that can create or reuse an HTTPS endpoint and route together.
Is this the same as an email sending API?
No. This page is about inbound email triggering webhook events. It does not describe an outbound API for sending email.
Do I need to change MX records?
Not always. MailWebhook supports existing mailbox workflows through Gmail, Microsoft 365, and IMAP, plus hosted mailbox options for dedicated intake addresses.

Receive your next inbound email as a signed webhook

Create an endpoint, connect a route, and let MailWebhook turn mailbox messages into JSON events your API can verify and process.

Start freeView endpoint docs