Email to API

You have an API — or an app behind one — and a steady stream of inbound email you'd like to ingest as structured requests: support tickets, order confirmations, server alerts, form notifications, customer replies. The usual options are unappealing: run and secure an SMTP server, or poll an IMAP mailbox on a timer and parse raw MIME yourself. Both are infrastructure you don't want to own.

Webhook Relay can receive emails as webhooks instead. You get a unique address, every message sent to it is parsed into JSON, and a small transform reshapes that JSON into exactly the request your API expects — body, headers and auth — before it's POSTed to your endpoint.

How it works

The whole path is a single hop with a transform in the middle:

inbound email  ──▶  Webhook Relay (parse + transform)  ──▶  POST to your API (public or behind a firewall)

When an email hits your Webhook Relay address it's parsed into a structured JSON document and POSTed to the bucket's outputs. Your API expects its own request shape — not Webhook Relay's parsed-email shape — so the transform converts one into the other in flight, and can attach the headers and bearer token your endpoint requires.

The parsed email looks like this:

{
  "from": "[email protected]",
  "from_name": "Jon Snow",
  "recipient": "<uuid>@in.webhookrelay-mail.com",
  "to": ["<uuid>@in.webhookrelay-mail.com"],
  "cc": [],
  "subject": "Order #4821 confirmed",
  "date": "Fri, 26 Jun 2026 11:27:41 +0400",
  "message_id": "<[email protected]>",
  "text": "plain body",
  "html": "<p>html body</p>",
  "headers": {},
  "spf": "pass",
  "dkim": "pass",
  "dmarc": "pass",
  "attachments": [
    { "name": "invoice.pdf", "content_type": "application/pdf", "size": 48213, "content": "<base64>", "truncated": false }
  ]
}

See the full payload reference for every field.

Setup

1. Create a bucket. This is the container that ties an input to its outputs.

2. Add an email input. Webhook Relay gives you back a unique address of the form <uuid>@in.webhookrelay-mail.com. Anything sent there is parsed and forwarded to the bucket's outputs.

3. Add your API as the output. Point the bucket's output at your endpoint's URL. Static headers and auth can be set on the output itself, or in the transform below — whichever you prefer.

4. Attach a transform. Add the transform function below so the parsed email is reshaped into your API's schema before delivery.

5. Send a test email. Email your <uuid>@in.webhookrelay-mail.com address from any client. Within a second or two the request reaches your API. If it doesn't, open the request log in your dashboard to see exactly what was received and delivered.

The transform

Webhook Relay functions hand you the incoming request body as a string in r.body. Parse it, build your API's request, and write it back with r.setBody() and r.setHeader():

const e = JSON.parse(r.body);
r.setBody(JSON.stringify({ sender: e.from, title: e.subject, body: e.text, received_at: e.date }));
r.setHeader("Authorization", "Bearer YOUR_API_TOKEN");
r.setHeader("Content-Type", "application/json");

That's the complete bridge: the email is mapped field-for-field onto your API's schema and authenticated with your token.

The same function is the place to drop messages you don't want. Inspect any parsed field and short-circuit with r.setResponseStatus() plus an early return so the request never reaches your endpoint:

const e = JSON.parse(r.body);
if (e.dmarc !== "pass") {
  r.setResponseStatus(202);
  return; // discard spoofed mail — never hits your API
}

Only the messages you actually want make the trip. For coarser control, pair this with the From-address allowlist in filtering and policy.

Outputs aren't limited to public URLs. With the relay agent, Webhook Relay can deliver to a server behind a firewall or on localhost with no public IP — useful for internal services and local development. Failed deliveries are retried, so a brief outage on your side doesn't drop email.

Get started

Turning inbound mail into API requests is one case of a broader pattern: Email to Webhook. Once an email is JSON, you can route it anywhere a webhook can go.

Create a free Webhook Relay account, add an email input, and start ingesting inbound email as clean API requests in a few minutes.