# 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](https://voozin.com/docs/domains)).
2. A route matches the recipient address.
3. Voozin checks SPF, DKIM and DMARC, stores the message, and sends an `inbound.received` [webhook](https://voozin.com/docs/webhooks) to the route's endpoint.
4. Your app handles the event and can [reply](https://voozin.com/docs/inbound/replying) 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:

```bash
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-…" }'
```

```ts
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

```json
{
  "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:

```ts
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

- [Reply to inbound mail](https://voozin.com/docs/inbound/replying) so the conversation threads.
- [Contact form to inbox](https://voozin.com/docs/guides/contact-form) for a complete example.
- The [WordPress plugin](https://voozin.com/docs/wordpress) shows inbound mail in wp-admin without code.
