Inbound API

Endpoints

Email people send you, parsed into something your application can act on: a webhook the moment it arrives, and this API for the body and the files.

Where to receive

Every project can receive mail immediately, with nothing to configure — any address on its own subdomain works:

anything@<project-slug>.inbound.emailbump.com

It's a catch-all, so support@, replies@, and invoice-4821@ all arrive — filter on received_for, the address that routed it here, to tell them apart. GET /v1/inbound/address returns your project's domain and an example address.

curl https://emailbump.com/api/v1/inbound/address \
  -H "Authorization: Bearer ebk_your_key"

{
  "domain": "acme-newsletter-3f9a2b.inbound.emailbump.com",
  "example": "[email protected]",
  "catch_all": true,
  "custom_domain_record": {
    "type": "MX",
    "value": "inbound-smtp.us-east-1.amazonaws.com",
    "priority": 10
  }
}

Receiving on your own domain

Add that MX record to the domain you want to receive on, and mail to any address there arrives in the same place. The domain has to be one you've verified for sending, which is what proves it's yours.

The email.received webhook

Subscribe to email.received under Developers → Webhooks and we POST as each message arrives. Like every webhook we send, it's signed and retried — and it carries metadata only, so the delivery stays small:

{
  "id": "2c28f706-5f9b-489a-ada6-0bab22460dbe",
  "type": "email.received",
  "created": "2026-08-01T22:34:28Z",
  "data": {
    "email": {
      "id": "3de5e8ff-d56a-4120-b3b7-15d6969b82ba",
      "from": "[email protected]",
      "from_name": "Jamie",
      "to": ["[email protected]"],
      "cc": [],
      "received_for": "[email protected]",
      "subject": "Photo of the damage",
      "message_id": "CAF…@mail.gmail.com",
      "in_reply_to": null,
      "attachment_count": 1,
      "attachments": [
        {
          "id": "877ba06a-…",
          "filename": "photo.png",
          "content_type": "image/png",
          "content_disposition": "inline",
          "content_id": "photo001",
          "size_bytes": 20481,
          "inline": true
        }
      ],
      "size_bytes": 38210,
      "spam": "PASS", "spf": "PASS", "dkim": "PASS", "dmarc": "PASS",
      "received_at": "2026-08-01T22:34:26Z"
    }
  }
}

Fetch the body with the id. The message is stored before the webhook fires, so a handler that was down loses nothing — the mail is here when you come back for it.

Read a message

GET /v1/inbound lists what you've received, newest first, with ?limit=, ?offset=, and ?search= over sender, subject, and recipient. GET /v1/inbound/{id} adds the body and the attachment list.

curl https://emailbump.com/api/v1/inbound/3de5e8ff-d56a-4120-b3b7-15d6969b82ba \
  -H "Authorization: Bearer ebk_your_key"

{
  "id": "3de5e8ff-…",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Re: your invoice",
  "text": "Thanks — see the file attached.",
  "html": "<p>Thanks — see the file attached.</p>",
  "body_truncated": false,
  "attachments": [
    {
      "id": "91ca5a56-…",
      "filename": "people.csv",
      "content_type": "text/csv",
      "size_bytes": 22,
      "inline": false,
      "content_id": null
    }
  ],
  "spam": "PASS", "spf": "PASS", "dkim": "PASS", "dmarc": "PASS",
  "received_at": "2026-08-01T22:34:26Z"
}

A very large body is stored up to a limit and marked body_truncated; the complete message is always kept intact behind the scenes.

Attachments

Download one by id. It comes back as the bytes that were sent, with the original filename and content type:

curl https://emailbump.com/api/v1/inbound/MESSAGE_ID/attachments/ATTACHMENT_ID \
  -H "Authorization: Bearer ebk_your_key" \
  -o people.csv

Every download is served as an attachment with X-Content-Type-Options: nosniff — a file a stranger sent you is never rendered in a browser on our domain. Treat it as untrusted in your own application too.

Images inside the message

An image the sender embedded arrives as an attachment with content_disposition: "inline" and a content_id, and the HTML points at it with <img src="cid:photo001">. To display the message, swap each cid: reference for that attachment's bytes:

let html = message.html
for (const a of message.attachments.filter((a) => a.inline && a.content_id)) {
  const res = await fetch(
    `https://emailbump.com/api/v1/inbound/${message.id}/attachments/${a.id}`,
    { headers: { Authorization: `Bearer ${process.env.EMAILBUMP_API_KEY}` } },
  )
  const b64 = Buffer.from(await res.arrayBuffer()).toString("base64")
  html = html.replaceAll(`cid:${a.content_id}`, `data:${a.content_type};base64,${b64}`)
}

CID replacement is not HTML sanitization. Sanitize the result, restrict displayed attachment types, and use an isolated viewer with scripts and remote loading disabled. Do not put raw inbound HTML into your application's DOM.

Be told the moment mail arrives

Upgrade to a WebSocket and messages are pushed as they land, with no URL to host. The webhook and the socket carry the same news by different routes — a webhook POSTs to a server you run, a socket pushes to an agent already connected and waiting. Both are on at once; use whichever suits what you are building.

// Node.js: install the ws package. Keep API keys out of browsers.
import WebSocket from "ws"

const ws = new WebSocket("wss://emailbump.com/api/v1/inbound/stream", {
  headers: { Authorization: `Bearer ${process.env.EMAILBUMP_API_KEY}` },
})

ws.addEventListener("message", (e) => {
  const event = JSON.parse(e.data)
  if (event.type !== "email.received") return
  console.log(event.email.from, "→", event.email.to, ":", event.email.subject)
})

To watch it without writing any code — useful when you are checking that mail is arriving at all — emailbump inbound:streamprints one JSON object per line, flushed as it arrives, so it pipes into jq.

{
  "type": "email.received",
  "email": {
    "id": "8f1c…",
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Where is my order?",
    "received_at": "2026-08-04T14:22:03Z",
    "attachment_count": 0
  }
}

It is a summary, not the message. id is what GET /v1/inbound/{id} takes, and to lets an agent using an address per task tell at a glance whether the message is one of its own. Fetch the body when the summary says it matters.

A connection that stops reading is disconnected rather than allowed to consume memory, and it is told first — a { "type": "lagged", "missed": 4 } frame, so an agent can list the inbox and recover instead of living with a silent gap.

Reply to a message

Answers whoever wrote to you, inside the thread they already have open. That is the difference from forwarding: a forward sends the message to someone else, a reply continues the conversation.

curl -X POST https://emailbump.com/api/v1/inbound/MESSAGE_ID/reply \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Sorry about that — it ships tomorrow." }'

{ "replied": true, "to": "[email protected]", "message_id": "0100019f…" }

What makes it thread

Three headers, set for you from the message you are answering: In-Reply-To names it, References carries the whole chain so a client that never saw an earlier message still files yours correctly, and the subject gains Re: once — an existing prefix in any language (AW:, SV:) is left alone rather than stacked on.

A reply is a send: it counts against your monthly allowance, obeys the shared-domain daily cap, and appears in your transactional log alongside everything else.

Forward a message

Send a message you received on to a person — a human inbox, a helpdesk, whoever should see it. The original bytes are re-addressed rather than rebuilt, so attachments, embedded images and formatting arrive exactly as they were sent.

curl -X POST https://emailbump.com/api/v1/inbound/MESSAGE_ID/forward \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "[email protected]" }'

The forward goes out from your own address with Reply-To set to whoever wrote it, so a reply reaches them and not you. Sending it as the original author instead would fail SPF and DKIM and land in spam, which is why no provider does it that way.

Forward automatically

A rule forwards mail as it arrives, with no code in the path. Set one under Inbound → Forwarding in the dashboard, or over the API:

curl -X POST https://emailbump.com/api/v1/inbound/rules \
  -H "Authorization: Bearer ebk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "forward_to": "[email protected]", "match_address": "[email protected]" }'

GET /v1/inbound/rules returns the rules plus addresses — the addresses this project has actually received on, taken from recent mail. Because a project receives on a catch-all, there is no other list of "your addresses" to read.

DELETE /v1/inbound/rules/{id} stops it. Up to 20 rules per project: every rule is another copy of every message that arrives, and a handful is a routing setup while fifty is an amplifier. The same loop protections apply as to a manual forward — an address that receives mail here is refused as a destination, automatic mail is never forwarded, and copies stop after three hops.

Spam and authentication

Every message is scanned before you see it, and the verdicts come with it: spam, spf, dkim, and dmarc, each PASS, FAIL, GRAY, or PROCESSING_FAILED.

• Mail carrying a virus never arrives. It's dropped on receipt — no row, no webhook.
• Spam does arrive, flagged. You decide what to do with spam: "FAIL", because one product's junk is another's signal.
• Authentication is advisory. A failed SPF or DMARC often means a forwarded message, not a forged one — weigh it, don't gate on it alone.