---
title: "Email to API | WebhookRelay"
meta:
  "og:description": "Convert inbound email into an API request — Webhook Relay parses each message to JSON and a transform POSTs it to your API in the shape it expects."
  "og:title": "Email to API"
  description: "Convert inbound email into an API request — Webhook Relay parses each message to JSON and a transform POSTs it to your API in the shape it expects."
---

![Stripes](https://webhookrelay.com/docs/tutorials/email/api/images/stripes.svg)

Documentation

**Fundamentals**

# **Email to API**

Convert inbound email into an API request — Webhook Relay parses each message to JSON and a transform POSTs it to your API in the shape it expects.

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](https://webhookrelay.com) can [receive emails as webhooks](https://webhookrelay.com/docs/tutorials/email/api/docs/email/) 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](#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": "jon@example.com",
  "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": "<abc123@mail.example.com>",
  "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](https://webhookrelay.com/docs/tutorials/email/api/docs/email/payload/) for every field.

## [Setup](#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](https://webhookrelay.com/docs/tutorials/email/api/docs/webhooks/functions/) 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](#the-transform)

Webhook Relay [functions](https://webhookrelay.com/docs/tutorials/email/api/docs/webhooks/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](https://webhookrelay.com/docs/tutorials/email/api/docs/email/filtering-and-policy/).

Outputs aren't limited to public URLs. With the relay agent, Webhook Relay can [deliver to a server behind a firewall](https://webhookrelay.com/docs/tutorials/email/api/webhooks/) 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](#get-started)

Turning inbound mail into API requests is one case of a broader pattern: [Email to Webhook](https://webhookrelay.com/docs/tutorials/email/api/email-to-webhook/). Once an email is JSON, you can route it anywhere a webhook can go.

[Create a free Webhook Relay account](https://my.webhookrelay.com/register), add an email input, and start ingesting inbound email as clean API requests in a few minutes.

Did this page help you?