Inbound Email API

What is an inbound email API?

Most email APIs send email. An inbound email API does the opposite. It receives incoming email for your application and converts each message into structured data.

With Inbox Bridge, the API is push-based. You do not call our servers to get new messages. When an email arrives, we call your server. Each email becomes one HTTPS POST request with a JSON body. Your application handles it like any other API request.

The flow has four steps:

1. You create a bridge and get a unique email address
2. Someone sends an email to that address
3. Inbox Bridge parses the message into JSON
4. Inbox Bridge sends the JSON to your webhook URL

Get an inbound email address

Each bridge has one unique address. The address looks like this:

abc123@webhook.inboxbridge.io

Give this address to a person, a device, a vendor system, or a form. All email sent to the address goes to your endpoint. You can create more bridges to route different senders to different endpoints.

The JSON payload

Each delivery is an HTTPS POST request with Content-Type: application/json. The body contains the parsed email:

{
  "id": "9b2c1f7a4e",
  "receivedAt": "2026-07-20T15:04:22.000Z",
  "from": { "email": "customer@example.com", "name": "Jordan Lee" },
  "to": [{ "email": "abc123@webhook.inboxbridge.io", "name": "" }],
  "cc": [],
  "bcc": [],
  "replyTo": null,
  "subject": "Question about my order",
  "date": "2026-07-20T15:04:00.000Z",
  "textBody": "Hey, can someone check order #1234?",
  "htmlBody": "<p>Hey, can someone check order #1234?</p>",
  "attachments": [
    {
      "name": "invoice.pdf",
      "contentType": "application/pdf",
      "contentLength": 482931,
      "contentId": null,
      "downloadUrl": "https://inboxbridge.io/attachments/clx1a2b3?token=…"
    }
  ]
}

The important fields are:

• id: a stable identifier for the message. Use it to prevent duplicate processing.
• from, to, cc, bcc: contact objects with an email and a name.
• textBody and htmlBody: the message body in both forms.
• attachments: one entry for each file, with its name, content type, and size. On paid plans, each entry also has a signed downloadUrl.

Delivery headers

Each request includes two headers. Use them to make sure the request came from Inbox Bridge:

• X-InboxBridge-Signature: an HMAC-SHA256 of the raw request body, in the form sha256=…. The key is the signing secret for your bridge.
• X-InboxBridge-Timestamp: the delivery time as unix seconds. Use it to reject old requests.

Verify and parse with typed code

Our open-source package, inbound-email-webhook, does the verification and the parsing for you. It checks the signature with a constant-time compare. It validates the payload against a schema. It returns a fully typed email object. It is the same code Inbox Bridge uses in production.

npm install inbound-email-webhook

In Next.js, one function call handles the full request:

// app/api/inbound-email/route.ts

import { verifyRequest } from "inbound-email-webhook/next";

export const runtime = "nodejs";

export async function POST(request: Request) {
  const result = await verifyRequest(request, {
    secret: process.env.INBOXBRIDGE_SIGNING_SECRET!,
  });

  if (!result.ok) return result.response;

  const email = result.email; // typed InboundEmail
  console.log(email.from.email, email.subject);

  return Response.json({ ok: true });
}

The package also has an Express middleware at inbound-email-webhook/express and a plain verify function for other frameworks. If you prefer no dependency, you can compute the HMAC yourself. The Next.js guide shows the manual version.

Responses and retries

Return a 2xx status to accept a delivery. Keep the handler fast. Store the payload first. Do slow work in the background.

If your endpoint returns an error, or does not respond, Inbox Bridge retries the delivery. Retries use exponential backoff. The number of attempts follows your plan limit. Each attempt is recorded with its response code and duration, so you can see what happened.

You can also replay any delivery from the dashboard. Replay sends the same payload again. This helps when you debug your handler.

Because retries exist, the same message can arrive more than one time. Use the payload id as an idempotency key. Store it with a unique constraint, and skip messages you already processed.

Do I need an email inbox API instead?

Some teams look for an email inbox API. That model connects to a mailbox over IMAP or a provider API, and your application polls for new messages. It works, but it adds moving parts: credentials, polling jobs, folder state, and processed message tracking.

If the goal is to react to incoming email inside your application, a push-based incoming email API is simpler. The email arrives. Your endpoint gets one JSON request. There is no polling and no mailbox state.

Use an inbox API when you must read an existing mailbox you do not control. Use an inbound email API when you can give out a new address and want each message to become an event in your app.

Quick start

1. Create a free account and add a bridge
2. Paste your webhook URL
3. Copy the generated email address
4. Send a test email to the address
5. Watch the JSON request arrive at your endpoint

The free plan includes a working bridge, so you can test the full flow before you pay for anything.