Events and inboundView as Markdown

Inbound email

Inbound routes let your application receive email. Mail sent to an address on your domain, such as support@acme.com or reply+ticket-123@acme.com, is parsed and posted to your webhook as JSON: sender, recipients, subject, text and HTML bodies, attachments and authentication results.

Typical uses are support inboxes, reply-by-email for comments or tickets, receiving invoices, and turning email into tasks.

Inbound routes are a paid add-on, and one route is included in the free trial.

How it works

  1. Your domain's MX record points to Voozin (see Domains and DNS).
  2. A route matches the recipient address.
  3. Voozin checks SPF, DKIM and DMARC, stores the message, and sends an inbound.received webhook to the route's endpoint.
  4. Your app handles the event and can reply through the sending API.

Addresses that are real mailboxes never match a route, so one domain can hold both your team's mailboxes and app addresses.

Create a route

In the dashboard open Developers → Inbound, or use the API with a key that has the inbound scope:

curl https://api.voozin.com/v1/inbound-routes \
  -H "Authorization: Bearer $VOOZIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain_id": "d3c1…", "pattern": "support", "endpoint_id": "5d0b8e3a-…" }'
await voozin.inbound.routes.create({ domain_id: domain.id, pattern: "support", endpoint_id: endpoint.id });
  • pattern is an exact local part (support), a prefix ending in * (reply+*), or * for every other address. Exact patterns win over prefixes (the longest first), and prefixes win over *.
  • endpoint_id is a webhook endpoint subscribed to inbound.received (or to all events).
  • mailbox_id additionally delivers a copy to a mailbox, so your team sees the mail in the webmail too.

The inbound.received event

{
  "type": "inbound.received",
  "timestamp": "2026-10-26T10:15:03.120Z",
  "data": {
    "id": "8a4f2c1e-…",
    "route_id": "1c9e7b52-…",
    "received_at": "2026-10-26T10:15:02+00:00",
    "mail_from": "ada@example.com",
    "recipients": ["support@acme.com"],
    "size": 18234,
    "auth": { "spf": "pass", "dkimPass": true, "aligned": true, "dmarc": { "dkim": "pass", "spf": "pass", "policy": "Reject", "failed": false } },
    "content_available": true,
    "from": { "name": "Ada Lovelace", "address": "ada@example.com" },
    "to": [{ "name": null, "address": "support@acme.com" }],
    "cc": [],
    "reply_to": [],
    "subject": "Order #1042 hasn't arrived",
    "message_id": "CAF7x…@mail.gmail.com",
    "in_reply_to": null,
    "references": null,
    "date": "2026-10-26T10:14:58+00:00",
    "text": "Hi, my order hasn't arrived yet…",
    "html": "<div>Hi, my order hasn't arrived yet…</div>",
    "truncated": false,
    "headers": [{ "name": "X-Mailer", "value": "…" }],
    "attachments": [
      { "index": 0, "filename": "photo.jpg", "content_type": "image/jpeg", "content_id": null, "size": 120334, "url": "https://api.voozin.com/v1/inbound/8a4f2c1e-…/attachments/0?expires=…&signature=…" }
    ],
    "raw_url": "https://api.voozin.com/v1/inbound/8a4f2c1e-…/raw?expires=…&signature=…"
  }
}
  • text and html are limited to 512 KB each; truncated is true when either was cut. The full message is always available from raw_url.
  • auth holds the SPF, DKIM and DMARC verdicts. Treat mail that is not aligned with care before acting on it.
  • Attachment url and raw_url are signed links that work without an API key for 24 hours.

Download attachments and the raw message

After 24 hours, or from your backend at any time, use a key with the inbound scope:

const raw = await voozin.inbound.raw(event.data.id); // ArrayBuffer, message/rfc822
const file = await voozin.inbound.attachment(event.data.id, 0); // { content, contentType, filename }

The REST paths are GET /v1/inbound/:id/raw and GET /v1/inbound/:id/attachments/:index.

History and replays

  • GET /v1/inbound lists received messages with their delivery status (filter by route_id and status).
  • GET /v1/inbound/:id returns the payload and the webhook attempts.
  • POST /v1/inbound/:id/replay sends the event again with fresh links, optionally to another endpoint_id. This is useful while developing your handler.

Retention and encryption

Inbound message content is stored encrypted for 7 days, then deleted; only the envelope remains. Routed mail is decrypted by Voozin to post it to your webhook, so it is not end-to-end encrypted. Use a mailbox for mail that must stay end-to-end encrypted.

Next