# Outbox — complete documentation

> Open source email API and dashboard. A self-hostable Resend.
> Generated from https://wess.io/outbox



---

# Outbox

> Open source email API and dashboard. A self-hostable Resend, built on Bun, Atlas, and PostgreSQL.


<div class="hero">

# Outbox

<p class="tagline">Open source email API and dashboard. A self-hostable Resend.</p>

</div>

Outbox implements the Resend API surface — the same paths, request bodies, response
shapes, and error envelope — plus the dashboard that goes with it. Point any Resend
SDK at your Outbox host and it works unchanged.

```ts
import { Resend } from "resend"

// The only change is the base URL.
const resend = new Resend("ob_yourapikey", { baseUrl: "https://outbox.example.com" })

await resend.emails.send({
  from: "Acme <onboarding@yourdomain.com>",
  to: ["someone@example.com"],
  subject: "Hello World",
  html: "<strong>It works!</strong>",
})
```

<div class="cards">
  <a class="card" href="/quickstart">
    <h3>Quickstart →</h3>
    <p>Running locally and sending your first email in about five minutes.</p>
  </a>
  <a class="card" href="/api/introduction">
    <h3>API reference →</h3>
    <p>Every endpoint, with request and response shapes.</p>
  </a>
  <a class="card" href="/tutorials/migrate-from-resend">
    <h3>Migrate from Resend →</h3>
    <p>What changes, what doesn't, and how to cut over.</p>
  </a>
  <a class="card" href="/self-hosting">
    <h3>Self-hosting →</h3>
    <p>Transports, DNS, deployment, and the operational realities of email.</p>
  </a>
</div>

## What's in it

**Sending** — transactional email, batch send (100 per call), scheduling with natural
language (`in 1 hour`) or ISO 8601, attachments, inline images, custom headers, tags,
idempotency keys, and cancel/reschedule of queued sends.

**Domains** — per-domain DKIM keypairs, generated SPF/DKIM/DMARC/MX/tracking records,
live DNS verification, open and click tracking, custom return path, opportunistic or
enforced TLS.

**Audience** — contacts with typed custom properties, segments, topics with per-contact
opt-in and opt-out, and a suppression list that bounces feed automatically.

**Broadcasts** — fan out to a segment with per-contact personalisation, scheduling, and
per-broadcast metrics including clicked links.

**Templates** — versioned, with typed variables and fallbacks, a draft/publish workflow,
duplication, and addressing by id or alias.

**Automations** — event-triggered workflows as a step graph: conditions with branching,
delays, waiting on an event, sending email, and mutating contacts.

**Webhooks** — 19 event types, Svix-compatible signatures, delivery attempt history, and
exponential-backoff retries.

**Receiving** — an inbound SMTP server that parses MIME, stores attachments, and fires
`email.received`.

**Accounts** — the first account created on an instance owns it; later signups get their
own team. Sessions are cookie-based and revocable.

## Why it exists

Resend is a good product with an API worth copying. Outbox exists for the cases where
sending someone else's servers your customers' email is the wrong answer: air-gapped
deployments, data-residency requirements, high volume where per-email pricing stops
making sense, or simply wanting the thing you depend on to be inspectable.

The compatibility is the point. You should be able to develop against Resend and deploy
against Outbox, or the reverse, without a rewrite.

## How it differs

Outbox is not a proxy in front of SES — it delivers mail itself, so a few things
necessarily differ:

| | Resend | Outbox |
|---|---|---|
| API key prefix | `re_` | `ob_` |
| DNS record values | Point at SES | Point at your host |
| Billing | Metered | None — it's your server |
| Regions | Routed | Stored and returned, single region |

The record *set* is the same shape, the API is the same, and errors use the same
envelope. See [Migrate from Resend](/tutorials/migrate-from-resend) for the full list.

## For agents

The docs are available as plain text: [llms.txt](/llms.txt) for an index, and
[llms-full.txt](/llms-full.txt) for everything in one file. Any page also serves its
raw markdown by appending `.md` to the URL.



---

# Quickstart

> Get Outbox running locally and send your first email in about five minutes.


# Quickstart

Outbox needs [Bun](https://bun.sh) 1.3 or newer and PostgreSQL 14 or newer. Docker is
the easiest way to get Postgres, and the repo ships a compose file for it.

## Install

```sh
git clone https://github.com/wess/outbox.git
cd outbox
bun install
```

## Configure

```sh
cp .env.example .env
```

Open `.env` and set `JWT_SECRET` to a long random string. It signs dashboard sessions
and the tokens embedded in tracking and unsubscribe links, so it must not stay at its
default:

```sh
openssl rand -hex 32
```

Everything else has a working default for local development. In particular
`OUTBOX_TRANSPORT=console`, which prints messages to the worker log instead of
delivering them — you can exercise the whole product before you own a domain.

## Start the database and migrate

```sh
bun run db:up      # Postgres on :55432, via Docker
bun run migrate    # creates the schema
bun run seed       # creates a team, a login, and an API key
```

`seed` prints credentials. Save the API key — it is hashed on write and never shown
again:

```
  team      Acme (0f8a...)
  owner     yes — this is the instance owner
  user      admin@outbox.local
  password  outbox-dev-password
  api key   ob_EXAMPLEKEYdonotusethisvalue123
```

> The first account created on an instance owns it. That is whoever `seed` creates, or
> the first person to sign up if you skip seeding.

## Run it

```sh
bun run dev
```

This starts the API and the background worker in one process:

```
[outbox] api        http://localhost:3000
[outbox] dashboard  http://localhost:3000/app
[outbox] worker worker-332b92ae started (concurrency 8, transport console)
```

Open <http://localhost:3000/app> and sign in.

## Send an email

```sh
curl -X POST http://localhost:3000/emails \
  -H "Authorization: Bearer ob_yourapikey" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@example.com>",
    "to": ["someone@example.com"],
    "subject": "Hello World",
    "html": "<strong>It works!</strong>"
  }'
```

```json
{ "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }
```

The `User-Agent` header is required — Outbox rejects requests without one, exactly as
Resend does. Every official SDK sets it for you.

Watch the worker log and you'll see the rendered message, then check the Emails page in
the dashboard: the email moves from `queued` to `sent` to `delivered`.

## Use an SDK

Any Resend SDK works. In JavaScript:

```ts
import { Resend } from "resend"

const resend = new Resend(process.env.OUTBOX_API_KEY, {
  baseUrl: "http://localhost:3000",
})

const { data, error } = await resend.emails.send({
  from: "Acme <onboarding@example.com>",
  to: ["someone@example.com"],
  subject: "Hello World",
  html: "<strong>It works!</strong>",
})

if (error) console.error(error)
else console.log(data.id)
```

Outbox also ships its own zero-dependency client — see [SDK](/sdk).

## What's next

- [Send your first email](/tutorials/send-your-first-email) — the same flow with more explanation.
- [Verify a domain](/tutorials/verify-a-domain) — required before Outbox will deliver real mail.
- [Self-hosting](/self-hosting) — transports, deployment, and what running an MTA actually involves.
- [API reference](/api/introduction) — every endpoint.

## Commands

| Command | What it does |
|---|---|
| `bun run dev` | API + worker (+ inbound when enabled) |
| `bun run api` | API and dashboard only |
| `bun run worker` | Background worker only |
| `bun run inbound` | Inbound SMTP server only |
| `bun run migrate` | Apply pending migrations |
| `bun run migrate:status` | Show migration state |
| `bun run migrate:down` | Roll back the most recent migration |
| `bun run seed` | Create a starter team, user, and API key |
| `bun test` | Unit tests |
| `bun run test:smoke` | API contract, against a running server |
| `bun run test:e2e` | Full pipeline, including a webhook receiver |
| `bun run test:compat` | The official `resend` package, against Outbox |



---

# Concepts

> How teams, domains, contacts, topics, and the job queue fit together.


# Concepts

A short tour of the objects Outbox works with and how they relate.

## Teams and accounts

Everything is scoped to a **team**. API keys, domains, contacts, emails, and templates
all belong to exactly one team, and no query crosses that boundary.

A **user** signs in to the dashboard and belongs to one or more teams through a
**membership** carrying a role (`owner`, `admin`, `member`).

The first account created on an instance is the **instance owner** (`is_owner`). That is
a property of the installation, distinct from being the owner of a team. It is enforced
by a partial unique index, so two simultaneous signups on a fresh instance cannot both
claim it.

## API keys

Keys are shown once, at creation, and stored only as a SHA-256 hash. They carry a
permission:

- `full_access` — every endpoint.
- `sending_access` — only the send endpoints. Suitable for a key that ships somewhere
  less trusted.

A key can additionally be restricted to a single domain, in which case it may only send
from that domain.

The dashboard authenticates with a session cookie against the *same* endpoints, so there
is no second API to keep in sync.

## Domains

You must add and verify a domain before Outbox will deliver mail from it. Adding one
generates a DKIM keypair and the DNS records to publish:

| Record | Type | Purpose |
|---|---|---|
| `@` and `send` | TXT | SPF authorising this host |
| `send` | MX | Return path for bounces |
| `outbox._domainkey` | TXT | DKIM public key |
| `_dmarc` | TXT | DMARC policy, starting at `p=none` |
| `links` | CNAME | Click and open tracking, when tracking is enabled |
| `@` | MX | Inbound mail, when receiving is enabled |

Verification resolves each record and compares it. A domain becomes `verified` once SPF
and DKIM check out; tracking and receiving records are advisory. From that point
outbound mail is DKIM-signed.

See [Verify a domain](/tutorials/verify-a-domain).

## Emails

An email is created synchronously — validated, persisted, and queued — and the API
returns its id immediately. Delivery happens in the worker.

Its state lives in `last_event`, which mirrors the webhook event names without the
`email.` prefix:

```
queued → scheduled → sent → delivered → opened → clicked
                        ↘ bounced / complained / failed / suppressed / canceled
```

Terminal states never regress. An open arriving after a bounce does not overwrite the
bounce.

Every state change writes a row to `email_events`, which is what the metrics endpoint
aggregates over.

## Contacts, segments, and topics

A **contact** is a person, unique by email within a team, with optional first and last
names, an `unsubscribed` flag, and typed **contact properties** you define.

A **segment** is a named group of contacts. Broadcasts target a segment.

A **topic** is a subscription category — "Weekly newsletter", "Product updates" —
letting recipients opt out of one kind of mail without opting out of everything. Each
topic has a `default_subscription` of `opt_in` or `opt_out` that applies to anyone who
has not expressed a preference.

Sending with a `topic_id` gates each recipient:

| Recipient | Outcome |
|---|---|
| Contact who opted in | Sent |
| Contact who opted out | Skipped, `email.failed` |
| Not a contact | Follows the topic's `default_subscription` |

## Suppressions

The suppression list is the team's do-not-send list. Addresses land on it three ways:

- `bounce` — a hard bounce, added automatically.
- `complaint` — a spam report.
- `manual` — added through the API or dashboard.

Every send checks it per recipient. A suppressed address produces `email.suppressed` and
is not delivered, which protects your sending reputation from repeatedly hitting a dead
address.

## Templates

A template holds content out of your codebase. Each edit creates a new **version**;
publishing promotes a version to `current_version_id`. Sends always use the published
version, so editing a template cannot break production mid-flight.

Variables use triple mustaches with an optional inline fallback:

```html
<p>Hi {{{first_name|there}}}, your order of {{{PRODUCT}}} shipped.</p>
```

Declared variables can carry a typed fallback used when a value is missing. Double
braces (`{{name}}`) HTML-escape; triple braces do not.

## Broadcasts

A broadcast is one message sent to every contact in a segment. Fan-out happens in the
worker: each eligible contact gets a real email row, personalised with their own values,
so per-recipient tracking and metrics work exactly as they do for transactional mail.

Contacts are skipped, with a recorded reason, when they are unsubscribed, suppressed, or
opted out of the broadcast's topic.

## Automations

An automation is a graph. **Steps** do things and **edges** connect them:

| Step | Behaviour |
|---|---|
| `trigger` | Entry point, matched on a custom event name |
| `condition` | Branches on `condition_met` / `condition_not_met` edges |
| `delay` | Suspends the run and resumes later |
| `wait_for_event` | Suspends until a named event arrives |
| `send_email` | Sends, inline or from a template |
| `add_to_segment` | Adds the contact to a segment |
| `contact_update` | Updates contact fields |
| `contact_delete` | Deletes the contact |

You start a run by posting to `/events/send`. Delays and waits suspend the run rather
than holding a worker, so a 30-day drip campaign costs nothing while it waits.

See [Build a welcome automation](/tutorials/welcome-automation).

## Webhooks

Webhooks deliver events to your endpoint, signed with the Svix scheme so the standard
Svix libraries verify them unchanged. Failures retry with exponential backoff across
roughly a day, and every attempt is recorded with its status code and response body.

See [Handle webhooks](/tutorials/handle-webhooks) and [Webhooks API](/api/webhooks).

## The job queue

Anything that must not happen inside a request — delivery, broadcast fan-out, webhook
posts, automation steps, DNS verification — goes through a Postgres-backed queue.

Workers claim jobs with `SELECT … FOR UPDATE SKIP LOCKED`, so you can run as many as you
like without coordination. Failed jobs retry with exponential backoff up to
`max_attempts`, and jobs whose worker died mid-flight are reclaimed after five minutes.

That is why `bun run dev` starts a worker alongside the API: without one, mail is
accepted and queued but never sent.



---

# Self-hosting

> Transports, configuration, deployment, and the operational realities of running your own mail.


# Self-hosting

Outbox delivers mail itself rather than fronting a provider. That is the point of it,
and it is also the part that takes real work. This page is about that work.

## Choosing a transport

`OUTBOX_TRANSPORT` decides how mail leaves the building.

| Value | Behaviour | Use it when |
|---|---|---|
| `console` | Prints the message, delivers nothing | Local development, CI |
| `relay` | Hands every message to one upstream SMTP server | You want real delivery without running an MTA |
| `smtp` | Connects to each recipient domain's MX hosts directly | You want no third party in the path |

### console

The default. Messages are rendered fully — MIME built, tracking applied, unsubscribe
links injected — then printed instead of sent. Events still fire, so webhooks and
metrics behave as they would in production.

### relay

Hands off to an SMTP server you already trust: SES, Postmark, a corporate smarthost, or
your own Postfix.

```sh
OUTBOX_TRANSPORT=relay
SMTP_RELAY_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_RELAY_PORT=587
SMTP_RELAY_USER=...
SMTP_RELAY_PASS=...
SMTP_RELAY_SECURE=starttls   # none | starttls | tls
```

This is the pragmatic choice for most self-hosters. You keep your data and the API, and
you let someone else own IP reputation.

### smtp

Resolves MX records for each recipient domain and delivers directly, upgrading to TLS
when the receiver offers STARTTLS.

```sh
OUTBOX_TRANSPORT=smtp
OUTBOX_HOSTNAME=mail.example.com
```

Before choosing this, be honest about the requirements:

- **Outbound port 25.** Most cloud providers block it by default and some will not
  unblock it at all. Check before you build a plan around it.
- **A static IP with matching forward and reverse DNS.** `mail.example.com` must resolve
  to your IP and that IP's PTR record must resolve back. Receivers reject mail from
  hosts that fail this.
- **Reputation.** A new IP has none. Volume ramps over weeks, not hours.
- **Someone to watch it.** Blocklists, feedback loops, and bounce handling are ongoing
  work, not setup steps.

If that list is unwelcome, use `relay`. It is not a lesser option; it is the correct
trade for most deployments.

## Configuration

| Variable | Default | Notes |
|---|---|---|
| `DATABASE_URL` | `postgres://outbox:outbox@localhost:55432/outbox` | |
| `JWT_SECRET` | — | **Set this.** Signs sessions and tracking tokens. |
| `PORT` | `3000` | |
| `PUBLIC_URL` | `http://localhost:3000` | Builds tracking and unsubscribe links. Must be the externally reachable URL. |
| `OUTBOX_TRANSPORT` | `console` | `console`, `relay`, `smtp` |
| `OUTBOX_HOSTNAME` | `localhost` | EHLO name, and the host DNS records point at |
| `SMTP_RELAY_HOST` | — | Relay transport |
| `SMTP_RELAY_PORT` | `587` | |
| `SMTP_RELAY_USER` | — | |
| `SMTP_RELAY_PASS` | — | |
| `SMTP_RELAY_SECURE` | `starttls` | `none`, `starttls`, `tls` |
| `INBOUND_ENABLED` | `false` | |
| `INBOUND_PORT` | `2525` | Forward :25 to it rather than running as root |
| `WORKER_CONCURRENCY` | `8` | Jobs in flight per worker |
| `WORKER_POLL_MS` | `1000` | Queue poll interval |
| `RATE_LIMIT_PER_SECOND` | `10` | Per team, matching Resend's default |
| `MAX_ATTACHMENT_BYTES` | `41943040` | 40MB |
| `TRUSTED_PROXIES` | — | Set behind a load balancer so client IPs are real |
| `STORAGE_BUCKET` | — | Set to move attachments out of Postgres. See below |
| `STORAGE_REGION` | `us-east-1` | |
| `STORAGE_ENDPOINT` | — | Leave empty for AWS; set it for Spaces, R2, MinIO |
| `STORAGE_ACCESS_KEY_ID` | — | |
| `STORAGE_SECRET_ACCESS_KEY` | — | |
| `STORAGE_PREFIX` | `outbox` | Key prefix, so one bucket can hold other things |
| `AUTH_FROM` | — | Address password-reset mail comes from. See below |

`TRUSTED_PROXIES` matters more than it looks. Outbox only honours `X-Forwarded-For` when
the request genuinely arrived from a listed proxy; otherwise the header is
attacker-controlled and would let anyone forge their IP past the rate limiter.

## Running the pieces

`bun run dev` runs everything in one process, which is fine for a single box. To scale,
run them separately:

```sh
bun run api        # stateless, run as many as you like behind a load balancer
bun run worker     # run as many as you like; they coordinate through Postgres
bun run inbound    # one per host that MX records point at
```

Workers claim jobs with `SELECT … FOR UPDATE SKIP LOCKED`, so adding workers needs no
configuration and no leader election.

## Behind a reverse proxy

Terminate TLS in front and forward to the API. Nginx:

```nginx
server {
  listen 443 ssl http2;
  server_name outbox.example.com;

  ssl_certificate     /etc/letsencrypt/live/outbox.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/outbox.example.com/privkey.pem;

  client_max_body_size 50m;   # attachments

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
```

Then set:

```sh
PUBLIC_URL=https://outbox.example.com
TRUSTED_PROXIES=127.0.0.1
```

## Receiving mail

Set `INBOUND_ENABLED=true` and enable receiving on the domain.

> The inbound server is also what processes **bounces**, and that does not need
> receiving enabled on the domain — see [Handle
> bounces](/tutorials/handle-bounces). On the `smtp` transport, running without
> it means asynchronous bounces are never seen and dead addresses are never
> suppressed. Outbox listens on
`INBOUND_PORT` (2525 by default) so it need not run as root; forward port 25 to it:

```sh
iptables -t nat -A PREROUTING -p tcp --dport 25 -j REDIRECT --to-port 2525
```

Publish an MX record for the domain pointing at `inbound.<OUTBOX_HOSTNAME>`. Mail for
addresses on that domain is parsed, stored with its attachments, and raises
`email.received`.

See [Receive inbound email](/tutorials/receive-inbound-email).

## Password reset

The dashboard has a "Forgot your password?" flow. It sends the reset link
**through this instance** — Outbox is an email service, so it delivers its own
transactional mail rather than asking you to configure a second one.

That has one consequence worth knowing before you need it:

> **A brand new instance cannot send reset mail.** Until a domain is verified,
> there is no address to send from, so the request is accepted, logged, and
> nothing arrives. This is not a bug you can configure away — the first account
> exists before any domain does.

So: verify a domain early, and keep the owner password somewhere you can find it
until you have. The log line to look for is

```
[outbox] password reset not sent — no verified sending domain and AUTH_FROM is unset
```

By default reset mail comes from `no-reply@<first verified domain>`. Set
`AUTH_FROM` to override that.

Two things the flow deliberately does:

- **It answers identically whether or not the address has an account.** An
  endpoint that needs no credentials and confirms which addresses are registered
  is an account-enumeration oracle; the detail goes to the log instead.
- **A successful reset signs out every existing session.** If the reset happened
  because somebody else knew the password, leaving their session alive would
  defeat the point.

Tokens are single-use, expire in an hour, and only their hash is stored — a
database backup cannot be turned into working reset links.

Reset mail goes through the ordinary send pipeline, which means **a suppressed
address will not receive it**. Correct in general, maddening if it is yours:
check `/suppressions` if a reset never arrives.

## Object storage

By default everything lives in Postgres, attachments included. That is the right
default — one thing to run, one thing to back up — but attachments are unlike
everything else Outbox stores. A single 40MB attachment is larger than most teams'
entire `emails` table, and base64 in a `text` column costs a third again on top.
Send enough of them and the blobs dominate the database, every `pg_dump` carries
them, and the disk fills long before the row count gets interesting.

Point Outbox at a bucket and they go there instead, with Postgres keeping a key:

```sh
STORAGE_BUCKET=my-bucket
STORAGE_REGION=nyc3
STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com   # empty for AWS S3
STORAGE_ACCESS_KEY_ID=...
STORAGE_SECRET_ACCESS_KEY=...
```

Any S3-compatible endpoint works — AWS, DigitalOcean Spaces, Cloudflare R2, MinIO,
Backblaze B2. Give the key **read and write on that one bucket**, not full access.

What moves: attachments on sent mail, attachments on received mail, and the raw
MIME of received messages. Keys are namespaced `<prefix>/<kind>/<team id>/<uuid>/
<filename>`, so one bucket serves every team and a team's objects can be found
without consulting the database.

Three things worth knowing:

- **It is not a cutover.** Rows written before you configured a bucket keep their
  inline content and stay readable. Nothing backfills them and nothing needs to —
  the read path takes whichever column is populated.
- **Turning it off strands anything already uploaded.** The objects survive, but an
  attachment with a key and no bucket configured is an error rather than an empty
  file, because silently sending a zero-byte attachment is worse than failing.
- **The bucket becomes part of your backup.** `pg_dump` alone is no longer a
  complete backup once blobs live elsewhere.

## Backups

Everything lives in Postgres — message bodies, DKIM private keys, and attachments
too unless you configured object storage above. A standard `pg_dump` is a complete
backup of the database.

Two things deserve attention:

- **DKIM private keys** are in `domains.dkim_private_key`. Losing them means republishing
  DNS for every domain. Treat the dump as a secret.
- **Attachments make the database large** when they are stored inline. If you send many
  or large attachments, either configure a bucket or plan retention accordingly.

## Housekeeping

Some tables grow without bound and nothing prunes them automatically, deliberately —
retention is your policy, not ours:

| Table | Grows with | Suggested |
|---|---|---|
| `api_logs` | Every API request | Keep 30 days |
| `email_events` | Every state change | Keep as long as you want metrics |
| `webhook_events` / `webhook_attempts` | Every event delivered | Keep 30 days |
| `jobs` | Completed jobs | Delete `status = 'done'` older than a few days |
| `rate_limits` | One row per bucket | Sweep windows older than your longest |

```sql
DELETE FROM api_logs WHERE created_at < now() - interval '30 days';
DELETE FROM jobs WHERE status = 'done' AND updated_at < now() - interval '3 days';
```

## Health

`GET /health` needs no authentication and checks database reachability:

```json
{ "status": "ok", "version": "0.1.0" }
```

It returns 503 with `"status": "degraded"` when Postgres is unreachable, which makes it
suitable as a load balancer check.

## Upgrading

```sh
git pull
bun install
bun run migrate
```

Migrations are forward-only in practice; `migrate:down` rolls back exactly one and is
meant for development. Take a dump before upgrading production.



---

# Send your first email

> From a running instance to a delivered message, with the state machine explained.


# Send your first email

Assumes you have Outbox running from the [quickstart](/quickstart) and an API key.

## 1. Send it

```sh
curl -X POST http://localhost:3000/emails \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@example.com>",
    "to": ["you@example.com"],
    "subject": "Hello from Outbox",
    "html": "<h1>It works</h1><p>Sent from my own server.</p>"
  }'
```

```json
{ "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }
```

That id is the handle for everything that follows.

## 2. Watch it move

```sh
curl http://localhost:3000/emails/4ef9a417-02e9-4d39-ad75-9611e0fcc33c \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

`last_event` walks through the lifecycle:

```
queued      accepted, waiting for a worker
sent        handed to the transport
delivered   accepted by the receiving server
opened      the tracking pixel loaded
clicked     a tracked link was followed
```

On the `console` transport the whole body is printed to the worker log, and the email is
marked delivered immediately. That is the point of it — you can build the entire flow
before you own a domain.

If it stays `queued` forever, no worker is running. `bun run dev` starts one; `bun run
api` alone does not.

## 3. Add the things that matter

### Plain text

Always include a text part. Outbox derives one from your HTML when you omit it, but a
hand-written version reads better and some filters weight its absence.

```json
{
  "html": "<h1>It works</h1>",
  "text": "It works"
}
```

### Reply-to

```json
{
  "from": "Acme <noreply@acme.com>",
  "reply_to": "support@acme.com"
}
```

Sending from `noreply@` and offering nowhere to reply is a choice customers notice.

### Tags

```json
{
  "tags": [
    { "name": "category", "value": "welcome" },
    { "name": "user_id", "value": "1234" }
  ]
}
```

Tags come back on the email and in webhook payloads, so you can attribute events to your
own concepts. Names and values allow letters, numbers, `_`, and `-`.

### Multiple recipients

```json
{ "to": ["a@example.com", "b@example.com"], "cc": ["c@example.com"] }
```

Everyone in `to` sees everyone else. For a mailing list you want either
[batch send](/api/emails#send-a-batch) or a [broadcast](/tutorials/broadcast-to-a-segment)
— not fifty addresses in one `to`.

Maximum 50 across to, cc, and bcc.

### Attachments

```json
{
  "attachments": [
    { "filename": "receipt.pdf", "content": "JVBERi0xLjQK..." }
  ]
}
```

Base64 in `content`, or a URL in `path` for Outbox to fetch. Up to 40MB.

### Scheduling

```json
{ "scheduled_at": "in 1 hour" }
```

Or ISO 8601. Scheduled emails can be [rescheduled or
cancelled](/api/emails#reschedule) until they send.

## 4. Make retries safe

Any network call can time out after the server accepted it. Without protection, your
retry sends a second copy.

```sh
curl -X POST http://localhost:3000/emails \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Idempotency-Key: order-1234-confirmation" \
  -H "Content-Type: application/json" \
  -d '{ … }'
```

Repeating that request with the same key replays the original response. Derive the key
from the thing you are emailing about — an order id, an invoice number — not a random
UUID, which defeats the purpose.

## 5. From an application

```ts
import { Resend } from "resend"

const resend = new Resend(process.env.OUTBOX_API_KEY, {
  baseUrl: process.env.OUTBOX_URL,
})

export const sendWelcome = async (user: { email: string; name: string }) => {
  const { data, error } = await resend.emails.send({
    from: "Acme <onboarding@acme.com>",
    to: [user.email],
    subject: `Welcome, ${user.name}`,
    html: `<h1>Welcome</h1><p>Glad you're here, ${user.name}.</p>`,
    tags: [{ name: "category", value: "welcome" }],
  })

  if (error) {
    // Log it and move on — a failed welcome email should not fail a signup.
    console.error("welcome email failed", error)
    return null
  }
  return data.id
}
```

Two habits worth forming now:

**Never block the user on an email.** Sending is fast but not instant, and a mail problem
should not become a signup problem.

**Log the id.** When someone asks whether the email went out, `last_event` answers it in
one request — but only if you kept the id.

## Next

- [Verify a domain](/tutorials/verify-a-domain) — required before real delivery.
- [Transactional email with templates](/tutorials/transactional-with-templates) — get content out of your code.
- [Handle webhooks](/tutorials/handle-webhooks) — react to bounces and opens.



---

# Verify a domain

> Publish SPF, DKIM, and DMARC records so your mail authenticates and arrives.


# Verify a domain

Outbox will not deliver from a domain you have not verified, and receiving servers would
mostly reject it anyway. This is the step that makes mail arrive.

## 1. Pick a domain

Use a subdomain, not your root domain:

```
mail.acme.com     ✓
send.acme.com     ✓
acme.com          ✗
```

Sending reputation attaches to the domain. Keeping bulk mail on a subdomain means a bad
month for your newsletter does not follow your invoices, and it keeps your existing MX
and SPF records untouched.

## 2. Add it

In the dashboard: **Domains → Add domain**. Or:

```sh
curl -X POST https://outbox.example.com/domains \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "mail.acme.com", "open_tracking": true, "click_tracking": true }'
```

Outbox generates a DKIM keypair and returns the records to publish.

## 3. Publish the records

| Record | Type | Host | Value |
|---|---|---|---|
| SPF | TXT | `mail.acme.com` | `"v=spf1 include:mail.example.com ~all"` |
| SPF | TXT | `send.mail.acme.com` | `"v=spf1 include:mail.example.com ~all"` |
| SPF | MX | `send.mail.acme.com` | `feedback-smtp.mail.example.com` priority 10 |
| DKIM | TXT | `outbox._domainkey.mail.acme.com` | `v=DKIM1; k=rsa; p=MIGfMA0…` |
| DMARC | TXT | `_dmarc.mail.acme.com` | `"v=DMARC1; p=none; rua=mailto:dmarc@mail.acme.com"` |
| Tracking | CNAME | `links.mail.acme.com` | `track.mail.example.com` |

The exact values come from your instance — copy them from the dashboard rather than this
page.

### Provider notes

Most DNS UIs want the host **relative** to the zone. If your zone is `acme.com`, enter
`outbox._domainkey.mail`, not the fully-qualified name. Entering the full name inside the
zone produces `outbox._domainkey.mail.acme.com.acme.com`, which is the single most common
reason verification fails.

Cloudflare: set DKIM, SPF, and DMARC records to **DNS only** (grey cloud). Proxying
breaks them.

## 4. Verify

```sh
curl -X POST https://outbox.example.com/domains/$DOMAIN_ID/verify \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

```json
{ "object": "domain", "id": "…", "status": "verified", "records": [ … ] }
```

| Status | Meaning |
|---|---|
| `not_started` | Nothing resolves yet |
| `pending` | Some records resolve |
| `verified` | SPF and DKIM both resolve — sending enabled |
| `failed` | Nothing resolved on the last check |

DNS propagation takes minutes to hours. Re-run verify rather than assuming failure.

Check what the world sees:

```sh
dig +short TXT outbox._domainkey.mail.acme.com
dig +short TXT mail.acme.com
dig +short TXT _dmarc.mail.acme.com
```

## 5. Send a real message

```sh
curl -X POST https://outbox.example.com/emails \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.acme.com>",
    "to": ["you@gmail.com"],
    "subject": "Authentication check",
    "html": "<p>Checking SPF, DKIM, and DMARC.</p>"
  }'
```

In Gmail, open the message → **Show original**. You want:

```
SPF:   PASS
DKIM:  PASS
DMARC: PASS
```

Anything else, fix before sending volume.

## 6. Tighten DMARC

Outbox starts you at `p=none`, which monitors without affecting delivery. Once you have
run a few weeks of clean traffic, tighten it:

```
v=DMARC1; p=none; rua=mailto:dmarc@acme.com       ← monitor
v=DMARC1; p=quarantine; pct=10; rua=…             ← 10% to spam
v=DMARC1; p=quarantine; rua=…                     ← all to spam
v=DMARC1; p=reject; rua=…                         ← reject outright
```

Move one step at a time and read the aggregate reports at `rua`. Jumping straight to
`p=reject` is how organisations discover, loudly, that some forgotten system was also
sending as their domain.

## Troubleshooting

**Verification never succeeds.** Confirm the record resolves publicly with `dig`. If
`dig` sees it and Outbox does not, your resolver may be caching an old negative response;
wait for the TTL.

**DKIM value looks truncated.** Some UIs split long TXT values across strings. Outbox uses
a 1024-bit key so the record fits in one, but if your provider wraps it anyway,
verification still passes — the check compares the `p=` tag, not the raw string.

**Verified, but Gmail says SPF fails.** SPF authenticates the return path, not the
visible `From`. Confirm the `send` subdomain records are published, not only the root.

**Mail lands in spam despite passing.** Authentication is necessary, not sufficient. New
domains have no reputation; volume has to ramp over weeks. Content, list quality, and
engagement matter as much as DNS.



---

# Migrate from Resend

> What changes, what doesn't, and how to cut over without dropping mail.


# Migrate from Resend

The API is the same. In most codebases the migration is one line — the base URL — plus
the operational work of standing up a server and moving your data.

## What stays the same

- Every endpoint path, request body, and response shape.
- The error envelope: `{ statusCode, name, message }`.
- The list envelope: `{ object, has_more, data }` with `after`/`before` cursors.
- Webhook event names and payloads.
- Webhook signatures — Svix scheme, so the same verification code works.
- Template variable syntax, including `{{{RESEND_UNSUBSCRIBE_URL}}}`.
- The `/audiences` paths, alongside `/segments`.

## What changes

| | Resend | Outbox |
|---|---|---|
| Base URL | `https://api.resend.com` | Your host |
| API key prefix | `re_` | `ob_` |
| DNS record values | Point at SES | Point at your host |
| Billing | Metered | None |
| Regions | Routed | Stored, single region |
| SMTP submission | Available | Not supported — use the HTTP API |

The DNS difference is the one with real work attached: you cannot reuse Resend's records
because they authorise Resend's servers. New domain, new records, new verification.

## 1. Stand up Outbox

Follow [self-hosting](/self-hosting). Decide your transport before you migrate: `relay`
if you want someone else to own IP reputation, `smtp` if you are prepared to run an MTA.

Set `PUBLIC_URL` to the externally reachable URL — tracking and unsubscribe links are
built from it.

## 2. Move your data

There is no import endpoint. Read from Resend, write to Outbox.

### Contacts

```ts
import { Resend } from "resend"

const source = new Resend(process.env.RESEND_API_KEY)
const target = new Resend(process.env.OUTBOX_API_KEY, { baseUrl: process.env.OUTBOX_URL })

const segment = await target.audiences.create({ name: "Migrated" })

let after: string | undefined
for (;;) {
  const page = await source.contacts.list({ audienceId: RESEND_AUDIENCE_ID, limit: 100, after })
  for (const contact of page.data.data) {
    await target.contacts.create({
      email: contact.email,
      firstName: contact.first_name,
      lastName: contact.last_name,
      unsubscribed: contact.unsubscribed,
      audienceId: segment.data.id,
    })
  }
  if (!page.data.has_more) break
  after = page.data.data[page.data.data.length - 1].id
}
```

Create [contact properties](/api/contact-properties) on Outbox first — unknown keys are
rejected rather than dropped.

### Suppressions

**Do this before your first send.** Everyone who bounced or complained on Resend must
stay suppressed, or you will re-mail dead addresses from a domain with no reputation —
the worst possible opening move.

```ts
const suppressions = await source.suppressions.list({ limit: 100 })
await target.suppressions.batch.add(suppressions.data.data.map((s) => s.email))
```

### Templates

Recreate them and publish. The variable syntax is identical, so the bodies copy across
unchanged.

### Broadcasts and emails

Historical sends do not migrate. Keep your Resend account readable for a while if you
need the archive.

## 3. Point your code at Outbox

```diff
- const resend = new Resend(process.env.RESEND_API_KEY)
+ const resend = new Resend(process.env.OUTBOX_API_KEY, {
+   baseUrl: process.env.OUTBOX_URL,
+ })
```

Better, make it switchable so you can fall back without a deploy:

```ts
export const mailer = new Resend(process.env.MAIL_API_KEY, {
  ...(process.env.MAIL_BASE_URL ? { baseUrl: process.env.MAIL_BASE_URL } : {}),
})
```

Unset `MAIL_BASE_URL` and you are on Resend; set it and you are on Outbox.

## 4. Verify domains

New records, new verification — see [Verify a domain](/tutorials/verify-a-domain). Use a
different subdomain from the one Resend uses so both can run at once during cutover.

## 5. Recreate webhooks

Signing secrets differ, so your endpoint needs Outbox's. If you want to run both
temporarily, accept either:

```ts
const secrets = [process.env.RESEND_WEBHOOK_SECRET, process.env.OUTBOX_WEBHOOK_SECRET]

let event = null
for (const secret of secrets.filter(Boolean)) {
  try {
    event = await verifyWebhook({ payload: raw, headers, webhookSecret: secret! })
    break
  } catch {}
}
if (!event) return new Response("bad signature", { status: 400 })
```

## 6. Cut over gradually

Move traffic by category rather than all at once:

```ts
const OUTBOX_CATEGORIES = new Set(["internal", "notifications"])

const client = OUTBOX_CATEGORIES.has(category) ? outbox : resend
```

Start with internal or low-stakes mail. Watch delivery, bounce, and complaint rates for a
week. Then move password resets and receipts, then marketing last — it is the most
sensitive to reputation.

## Verify the compatibility yourself

The repo ships a suite that runs the official `resend` package against Outbox:

```sh
OUTBOX_API_KEY=ob_... bun run test:compat
```

It checks sends, retrieval, listing, scheduling, cancellation, batching, audiences,
contacts, API keys, and error shapes. If you depend on a call it does not cover, add it
before you migrate.

## Rolling back

Keep the Resend key live until you are confident. Rollback is unsetting the base URL —
which is why making it an environment variable rather than a code change is worth the
five minutes.



---

# Transactional email with templates

> Move email content out of your codebase and into versioned, publishable templates.


# Transactional email with templates

Hard-coded HTML in your application means every copy change is a deploy, and marketing
cannot touch it without a pull request. Templates fix both.

## 1. Create one

```sh
curl -X POST https://outbox.example.com/templates \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Password reset",
    "alias": "password-reset",
    "from": "Acme <security@acme.com>",
    "subject": "Reset your password",
    "html": "<p>Hi {{{first_name|there}}},</p><p><a href=\"{{{reset_url}}}\">Reset your password</a></p><p>This link expires in {{{expiry_minutes}}} minutes. If you did not request it, ignore this email.</p>",
    "text": "Hi {{{first_name|there}}},\n\nReset your password: {{{reset_url}}}\n\nExpires in {{{expiry_minutes}}} minutes.",
    "variables": [
      { "key": "first_name", "type": "string", "fallback_value": "there" },
      { "key": "reset_url", "type": "string" },
      { "key": "expiry_minutes", "type": "number", "fallback_value": 30 }
    ]
  }'
```

Set an **alias**. Sending to `password-reset` rather than a UUID means your code does not
change when the template is recreated.

## 2. Publish it

A new template is a draft and cannot be sent:

```sh
curl -X POST https://outbox.example.com/templates/password-reset/publish \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

## 3. Send it

```ts
await resend.emails.send({
  to: [user.email],
  template: {
    id: "password-reset",
    variables: {
      first_name: user.firstName,
      reset_url: `https://acme.com/reset?token=${token}`,
      expiry_minutes: 30,
    },
  },
})
```

No `from`, no `subject`, no HTML — they come from the template. Override any of them by
passing it explicitly.

## 4. Edit safely

Any content change creates a **new draft version**. Production keeps using the published
one until you publish again:

```sh
curl -X PATCH https://outbox.example.com/templates/password-reset \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Reset your Acme password" }'
```

`has_unpublished_versions` becomes `true`. Nothing changes for senders until:

```sh
curl -X POST https://outbox.example.com/templates/password-reset/publish \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

This is the property that makes templates safe to hand to someone else: a mistake in the
editor cannot reach customers until someone publishes it.

## Variables

| Form | Behaviour |
|---|---|
| `{{{key}}}` | Raw insertion |
| `{{{key\|fallback}}}` | Fallback when missing or empty |
| `{{key}}` | HTML-escaped |
| `{{{contact.first_name}}}` | Contact fields, when sending to a contact |
| `{{{OUTBOX_UNSUBSCRIBE_URL}}}` | Signed per-recipient unsubscribe link |

Resolution: supplied value → inline fallback → declared `fallback_value` → empty.

**Escape anything a user typed.** `{{{name}}}` with a name of `<script>` inserts a
script tag. Use `{{name}}` for user-supplied values and reserve triple braces for HTML
you control and for URLs.

## Structuring a set

A workable convention:

| Alias | Purpose |
|---|---|
| `welcome` | After signup |
| `password-reset` | Reset link |
| `email-verification` | Confirm address |
| `invoice-receipt` | Payment succeeded |
| `payment-failed` | Payment retry needed |
| `trial-ending` | Three days left |

Then a thin wrapper so call sites stay honest:

```ts
type TemplateId =
  | "welcome"
  | "password-reset"
  | "email-verification"
  | "invoice-receipt"
  | "payment-failed"
  | "trial-ending"

export const sendTemplate = async (
  to: string,
  id: TemplateId,
  variables: Record<string, string | number>,
) => {
  const { data, error } = await resend.emails.send({ to: [to], template: { id, variables } })
  if (error) {
    console.error(`template ${id} failed for ${to}`, error)
    return null
  }
  return data.id
}
```

```ts
await sendTemplate(user.email, "password-reset", {
  first_name: user.firstName,
  reset_url: resetUrl,
  expiry_minutes: 30,
})
```

## Unsubscribe links in transactional mail

Receipts and password resets do not need one. Anything with a whiff of marketing does —
"here's what's new", "you haven't logged in lately" — even when it is technically
transactional.

Add a [topic](/api/topics) and the placeholder, and recipients can opt out of that
category without losing their receipts:

```json
{
  "template": { "id": "product-digest" },
  "topic_id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e"
}
```

## Previewing

The dashboard renders a live preview of the published version. To check variable
substitution end to end, send to yourself with the `console` transport and read the
rendered MIME in the worker log — that is the exact bytes a recipient would get.



---

# Broadcast to a segment

> Build an audience, personalise a message, and send it to everyone who should get it.


# Broadcast to a segment

A broadcast is one message to every contact in a segment, rendered per contact. This
walks through the whole path: properties, contacts, a topic, the send, and reading the
results.

## 1. Define properties

Declare the custom fields you want to personalise with, before importing:

```sh
curl -X POST https://outbox.example.com/contact-properties \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "key": "company_name", "type": "string", "fallback_value": "your team" }'
```

The fallback is what keeps `Hi {{{first_name}}} at {{{company_name}}}` from reading
badly for contacts with sparse data.

## 2. Create a segment

```sh
curl -X POST https://outbox.example.com/segments \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product updates" }'
```

## 3. Add contacts

```ts
const contacts = [
  { email: "ada@example.com", first_name: "Ada", company: "Analytical Engines" },
  { email: "grace@example.com", first_name: "Grace", company: "Compiler Co" },
]

for (const person of contacts) {
  await fetch(`${BASE}/contacts`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      email: person.email,
      first_name: person.first_name,
      properties: { company_name: person.company },
      segments: [{ id: SEGMENT_ID }],
    }),
  })
}
```

Import your suppression list **first** if you are moving from another provider. Mailing
addresses that already bounced is the fastest way to damage a new domain.

## 4. Create a topic

Marketing mail needs a way out that is not "unsubscribe from everything":

```sh
curl -X POST https://outbox.example.com/topics \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product updates",
    "description": "New features and changes, about twice a month",
    "default_subscription": "opt_in"
  }'
```

Use `opt_out` as the default where consent is a legal question rather than a preference.

## 5. Write the broadcast

```sh
curl -X POST https://outbox.example.com/broadcasts \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "'"$SEGMENT_ID"'",
    "topic_id": "'"$TOPIC_ID"'",
    "from": "Acme <news@mail.acme.com>",
    "subject": "{{{first_name|Hey}}}, three things shipped this month",
    "preview_text": "Scheduled sends, better search, and a faster dashboard",
    "html": "<p>Hi {{{first_name|there}}},</p><p>Here is what we shipped for {{{company_name}}} this month.</p><ul><li>Scheduled sends</li><li>Better search</li></ul><p><a href=\"https://acme.com/changelog\">Read the changelog</a></p><p style=\"font-size:12px;color:#888\"><a href=\"{{{OUTBOX_UNSUBSCRIBE_URL}}}\">Unsubscribe from product updates</a></p>"
  }'
```

Without `send` or `scheduled_at` this saves a draft.

`preview_text` is the preheader — the grey line after the subject in most inboxes. Left
empty, clients show the first words of your HTML, which is often "View in browser".

## 6. Preview before sending

Send yourself a copy as a normal email using the same body, or open the broadcast in the
dashboard, which renders the published content. Check:

- Every `{{{variable}}}` has a fallback.
- The unsubscribe link is present and reachable.
- It reads sensibly with images blocked.

## 7. Send

```sh
curl -X POST https://outbox.example.com/broadcasts/$BROADCAST_ID/send \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

Or schedule it:

```json
{ "scheduled_at": "2026-08-12T14:00:00Z" }
```

Fan-out runs in the worker. Each eligible contact gets a real email row, so per-recipient
tracking works exactly as it does for transactional mail.

### Who is skipped

| Reason | Cause |
|---|---|
| `unsubscribed` | The contact's `unsubscribed` flag |
| `suppressed` | The address is on the suppression list |
| `opted out of topic` | They opted out of this broadcast's topic |

## 8. Read the results

```sh
curl https://outbox.example.com/broadcasts/$BROADCAST_ID/metrics \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

```json
{
  "total": 1284,
  "sent": 1201,
  "delivered": { "count": 1180, "percentage": 91.9 },
  "opened": { "count": 512, "percentage": 39.87 },
  "clicked": { "count": 98, "percentage": 7.63 },
  "bounced": { "count": 21, "percentage": 1.63 },
  "clicked_links": [
    { "url": "https://acme.com/changelog", "clicks": 74, "unique_clicks": 61 }
  ]
}
```

Drill into any group:

```sh
curl "https://outbox.example.com/broadcasts/$BROADCAST_ID/recipients?type=bounced" \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

### Reading the numbers honestly

**Bounce rate above 2%** means list quality problems. Hard bounces are suppressed
automatically, but a high rate on a first send says the list was stale before you
imported it.

**Complaint rate above 0.1%** is a warning. Above 0.3% and mailbox providers start
throttling you. Complaints usually mean people do not remember signing up.

**Open rate** is unreliable — Apple pre-fetches images and inflates it, image blocking
deflates it. Watch the trend, not the number.

**Click rate** is the number that means something.

## Sending to a subset

There is no query-based segmentation yet. Build the subset in your own system and
maintain a segment:

```ts
const active = await db.query("SELECT email FROM users WHERE last_seen > now() - interval '30 days'")

for (const user of active) {
  await fetch(`${BASE}/contacts/${user.email}/segments/${ACTIVE_SEGMENT_ID}`, {
    method: "POST",
    headers,
  })
}
```

Adding a contact already in the segment is a no-op, so this is safe to run on a schedule.



---

# Build a welcome automation

> A branching, multi-day onboarding sequence triggered by an event from your app.


# Build a welcome automation

We will build an onboarding sequence that branches on the user's plan, waits a day, and
gives up early if they do the thing we wanted them to do.

## The shape

```
user.created
     │
     ├── plan = pro ──→ send pro welcome ──→ wait 1 day ──→ wait for project.created (3d)
     │                                                            │
     │                                                            └── timeout → send "need a hand?"
     │
     └── otherwise ──→ send free welcome ──→ wait 3 days ──→ send upgrade nudge
```

## 1. Templates first

```sh
for t in pro-welcome free-welcome need-a-hand upgrade-nudge; do
  curl -X POST https://outbox.example.com/templates \
    -H "Authorization: Bearer $OUTBOX_API_KEY" \
    -H "User-Agent: my-app/1.0" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"$t\",
      \"alias\": \"$t\",
      \"from\": \"Acme <hello@mail.acme.com>\",
      \"subject\": \"Welcome to Acme\",
      \"html\": \"<p>Hi {{{contact.first_name|there}}}!</p>\"
    }"
  curl -X POST https://outbox.example.com/templates/$t/publish \
    -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
done
```

Remember to publish — an unpublished template cannot be sent, and inside an automation
that failure is easy to miss.

## 2. The automation

```sh
curl -X POST https://outbox.example.com/automations \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding",
    "status": "disabled",
    "steps": [
      { "key": "start", "type": "trigger", "config": { "event_name": "user.created" } },
      {
        "key": "is_pro",
        "type": "condition",
        "config": { "type": "rule", "field": "event.plan", "operator": "eq", "value": "pro" }
      },
      { "key": "pro_welcome", "type": "send_email", "config": { "template_id": "pro-welcome" } },
      { "key": "day_one", "type": "delay", "config": { "duration": 1, "unit": "days" } },
      {
        "key": "await_project",
        "type": "wait_for_event",
        "config": { "event_name": "project.created", "duration": 3, "unit": "days" }
      },
      { "key": "need_a_hand", "type": "send_email", "config": { "template_id": "need-a-hand" } },
      { "key": "free_welcome", "type": "send_email", "config": { "template_id": "free-welcome" } },
      { "key": "day_three", "type": "delay", "config": { "duration": 3, "unit": "days" } },
      { "key": "upgrade_nudge", "type": "send_email", "config": { "template_id": "upgrade-nudge" } }
    ],
    "edges": [
      { "from": "start", "to": "is_pro", "type": "default" },
      { "from": "is_pro", "to": "pro_welcome", "type": "condition_met" },
      { "from": "pro_welcome", "to": "day_one", "type": "default" },
      { "from": "day_one", "to": "await_project", "type": "default" },
      { "from": "await_project", "to": "need_a_hand", "type": "default" },
      { "from": "is_pro", "to": "free_welcome", "type": "condition_not_met" },
      { "from": "free_welcome", "to": "day_three", "type": "default" },
      { "from": "day_three", "to": "upgrade_nudge", "type": "default" }
    ]
  }'
```

Note `"status": "disabled"`. Create it disabled, check the graph, then enable — an
automation that starts running the moment you create it is hard to un-send.

## 3. Trigger it

```ts
await fetch(`${BASE}/events/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "user.created",
    email: user.email,
    data: { plan: user.plan, signup_source: user.source },
  }),
})
```

Anything in `data` is available to conditions as `event.*` and to templates.

Call this **after** the user is committed to your database, not before. An automation
that welcomes someone whose signup then failed is worse than a slightly delayed welcome.

## 4. Test both branches

```sh
curl -X POST https://outbox.example.com/events/send \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "user.created", "email": "pro-test@example.com", "data": { "plan": "pro" } }'

curl -X POST https://outbox.example.com/events/send \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "user.created", "email": "free-test@example.com", "data": { "plan": "free" } }'
```

Then inspect:

```sh
curl https://outbox.example.com/automations/$AUTOMATION_ID/runs \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

```json
{
  "data": [
    { "id": "…", "email": "pro-test@example.com", "status": "waiting", "current_step_key": "day_one" },
    { "id": "…", "email": "free-test@example.com", "status": "waiting", "current_step_key": "day_three" }
  ]
}
```

Fetch a single run to see exactly which branch was taken:

```json
{
  "steps": [
    { "key": "start", "type": "trigger", "status": "completed" },
    { "key": "is_pro", "type": "condition", "status": "completed", "result": { "met": true } },
    { "key": "pro_welcome", "type": "send_email", "status": "completed", "result": { "email_id": "…" } },
    { "key": "day_one", "type": "delay", "status": "completed", "result": { "resume_at": "…" } }
  ]
}
```

Shorten the delays to seconds while testing, then change them back.

## 5. Enable it

```sh
curl -X PATCH https://outbox.example.com/automations/$AUTOMATION_ID \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "status": "enabled" }'
```

## How waiting works

`delay` and `wait_for_event` suspend the run rather than holding a worker. A 30-day
sequence costs nothing while it waits, and thousands of concurrent runs need no extra
capacity.

`wait_for_event` resumes when a matching event arrives for the same contact. If the
timeout passes first, the run **completes** rather than continuing — which is why
`await_project` flows to `need_a_hand` only on timeout. Someone who created a project
does not need the nudge, and that is exactly the behaviour you want.

## Conditions worth knowing

```json
{
  "type": "and",
  "rules": [
    { "field": "event.plan", "operator": "eq", "value": "pro" },
    { "field": "event.seats", "operator": "gte", "value": 5 },
    { "field": "contact.first_name", "operator": "exists" }
  ]
}
```

Fields resolve against `event.*`, `contact.*`, and contact properties by name. Operators:
`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`, `starts_with`,
`ends_with`, `exists`, `not_exists`.

## Practical notes

**One run per event.** Sending `user.created` twice starts two runs and sends two welcome
emails. Deduplicate on your side, or trigger from a state change you know happens once.

**A missing branch ends the run.** A condition with no `condition_not_met` edge simply
finishes for contacts that fail it. That is often what you want; make sure it is.

**Failures stop the run.** A failed step marks the run `failed` with the error recorded.
Check runs after changing templates — an unpublished template is the usual cause.

**Give steps meaningful keys.** `day_one` reads better than `step_4` when you are staring
at a run three months from now.



---

# Handle webhooks

> Receive events, verify signatures correctly, and react to bounces and complaints.


# Handle webhooks

Polling for delivery status does not scale and does not tell you about opens, clicks, or
complaints. Webhooks do.

## 1. Build the endpoint

The critical detail: **verify against the raw body**. Frameworks that parse JSON for you
will break the signature, because re-serialising changes the bytes.

### Bun

```ts
import { verifyWebhook } from "@outbox/sdk"

Bun.serve({
  port: 4000,
  routes: {
    "/webhooks/outbox": {
      POST: async (req) => {
        const raw = await req.text()

        let event: any
        try {
          event = await verifyWebhook({
            payload: raw,
            headers: {
              id: req.headers.get("svix-id"),
              timestamp: req.headers.get("svix-timestamp"),
              signature: req.headers.get("svix-signature"),
            },
            webhookSecret: process.env.OUTBOX_WEBHOOK_SECRET!,
          })
        } catch (err) {
          return new Response("invalid signature", { status: 400 })
        }

        // Acknowledge immediately; do the work out of band.
        queueMicrotask(() => handle(event).catch(console.error))
        return new Response("ok")
      },
    },
  },
})
```

### Express

```ts
import express from "express"
import { Webhook } from "svix"

const app = express()

// express.raw, not express.json — the parsed body cannot be verified.
app.post("/webhooks/outbox", express.raw({ type: "application/json" }), (req, res) => {
  const wh = new Webhook(process.env.OUTBOX_WEBHOOK_SECRET!)

  let event
  try {
    event = wh.verify(req.body, {
      "svix-id": req.header("svix-id")!,
      "svix-timestamp": req.header("svix-timestamp")!,
      "svix-signature": req.header("svix-signature")!,
    })
  } catch {
    return res.status(400).send("invalid signature")
  }

  res.send("ok")
  handle(event).catch(console.error)
})
```

### Next.js App Router

```ts
export async function POST(req: Request) {
  const raw = await req.text()
  // …verify as above
}
```

## 2. Register it

```sh
curl -X POST https://outbox.example.com/webhooks \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://acme.com/webhooks/outbox",
    "events": ["email.delivered", "email.bounced", "email.complained", "email.opened", "email.clicked"]
  }'
```

The response includes `signing_secret` — put it in your environment.

Subscribe only to what you act on. `email.sent` fires for every message and is rarely
useful; `email.bounced` and `email.complained` always are.

## 3. Handle the events

```ts
const handle = async (event: { type: string; data: any }) => {
  switch (event.type) {
    case "email.bounced": {
      const hard = event.data.bounce?.type === "Permanent"
      await db.emails.update(event.data.email_id, {
        status: "bounced",
        bounceType: hard ? "hard" : "soft",
      })
      // Outbox already suppressed hard bounces. Mirror it locally so your own
      // sending decisions know too.
      if (hard) await db.users.markEmailInvalid(event.data.to[0])
      break
    }

    case "email.complained":
      // Someone marked it as spam. Stop all marketing to them, immediately.
      await db.users.unsubscribeAll(event.data.to[0])
      break

    case "email.delivered":
      await db.emails.update(event.data.email_id, { status: "delivered" })
      break

    case "email.clicked":
      await analytics.track("email_clicked", {
        email_id: event.data.email_id,
        url: event.data.link?.url,
      })
      break
  }
}
```

## 4. Make it idempotent

Outbox retries on timeouts, so an event you already processed can arrive again. Key on
`svix-id`:

```ts
const seen = await db.webhookEvents.findUnique({ where: { id: svixId } })
if (seen) return new Response("ok")
await db.webhookEvents.create({ data: { id: svixId, type: event.type } })
```

Without this, a slow response on your side turns into duplicate work on every retry.

## 5. Respond fast

Requests time out after **10 seconds**. Acknowledge first, then work:

```ts
res.send("ok")
processInBackground(event)
```

Doing database writes, third-party calls, and image processing before responding is how
endpoints end up in retry loops.

## Retries

Non-2xx and timeouts retry with backoff:

```
5s → 30s → 5m → 30m → 2h → 5h → 10h → 24h
```

Eight attempts over roughly a day, then `exhausted`. Every attempt is recorded:

```sh
curl https://outbox.example.com/webhooks/$WEBHOOK_ID/events/$EVENT_ID/attempts \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

```json
{
  "data": [
    { "http_status_code": 500, "response": "Internal Server Error", "sent_at": "…" },
    { "http_status_code": 200, "response": "ok", "sent_at": "…" }
  ]
}
```

Your own error message comes back in `response`, which usually removes the need for
extra logging while debugging.

## Local development

Because Outbox is yours, it can reach your machine directly — no tunnel needed if both
are on the same network:

```ts
Bun.serve({
  port: 4000,
  fetch: async (req) => {
    console.log(await req.text())
    return new Response("ok")
  },
})
```

```sh
curl -X POST http://localhost:3000/webhooks \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint": "http://localhost:4000/hook", "events": ["email.sent"] }'
```

Otherwise `ngrok http 4000` and register the public URL.

## Common mistakes

**Signature always fails.** You are verifying parsed-and-re-serialised JSON. Use the raw
body.

**Events stop arriving.** Check the webhook's `status` — repeated failures do not disable
it automatically, but someone may have. Also check whether events are `exhausted`.

**Duplicate processing.** You are not deduplicating on `svix-id`.

**Everything times out under load.** You are doing the work before responding.



---

# Handle bounces

> Process delivery failures and spam complaints that arrive after a message was accepted.


# Handle bounces

Most bounces do not happen during the SMTP conversation. A receiving server
usually says `250 accepted`, discovers afterwards that the mailbox is unknown or
full, and mails a report back to your return path. Spam complaints work the same
way — the recipient hits "report spam" days later and their provider tells you.

Outbox processes both, and feeds the results into the suppression list so you
stop mailing addresses that no longer work.

## How attribution works

Every message Outbox sends carries a VERP return path:

```
bounces+4ef9a417-02e9-4d39-ad75-9611e0fcc33c@send.acme.com
```

The tag is the email's id. When a report comes back, that is what ties it to the
message that caused it — more reliably than the returned `Message-ID`, because
plenty of mail servers return only a truncated body and some return nothing at
all. Outbox falls back to the `Message-ID` when the tag is missing.

## What you need running

Bounce processing happens on the **inbound SMTP server**, so it has to be
listening:

```sh
INBOUND_ENABLED=true
INBOUND_PORT=2525
```

```sh
bun run dev        # starts it alongside the API and worker
# or
bun run inbound    # on its own
```

Forward port 25 to it, as in [Receive inbound
email](/tutorials/receive-inbound-email).

> You do **not** need to enable receiving on the domain. Bounce addresses are
> routed on their own, so you can process bounces without accepting ordinary
> mail. Enabling `receiving` is a separate decision about a separate thing.

The worker warns at startup if you are delivering with the `smtp` transport and
have no inbound server, because that combination silently loses every
asynchronous bounce.

### DNS

Adding a domain already generates the record this needs:

| Record | Type | Host | Value |
|---|---|---|---|
| SPF | MX | `send.acme.com` | `feedback-smtp.<your host>` priority 10 |

That MX is what tells the world where to send reports. If it does not resolve to
your inbound server, bounces go nowhere.

## What happens to a bounce

| Report | Severity | Outbox does |
|---|---|---|
| DSN status `5.x.x`, or a `5xx` diagnostic | hard | `email.bounced`, suppress the address |
| DSN status `4.x.x`, or `Action: delayed` | soft | `email.delivery_delayed`, record it, **no** suppression |
| ARF feedback report | complaint | `email.complained`, suppress the address |
| ARF `Feedback-Type: not-spam` | — | Nothing. It is a retraction, not a complaint |
| Anything unparseable at a bounce address | soft | Recorded as a transient failure |

The last row matters: arriving at a bounce address is itself evidence something
failed, so an unrecognised format is still recorded rather than dropped. It is
treated as soft because "we cannot tell what went wrong" is not grounds for
permanently blocking an address.

A soft bounce never suppresses. Mailbox-full and greylisting are temporary, and
suppressing on them would lose you real recipients.

## Watching it

Subscribe to the events:

```sh
curl -X POST https://outbox.example.com/webhooks \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://acme.com/webhooks/outbox",
    "events": ["email.bounced", "email.complained", "email.delivery_delayed"]
  }'
```

```json
{
  "type": "email.bounced",
  "created_at": "2026-08-10T15:41:02.114Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "to": ["dead@example.com"],
    "bounce": {
      "type": "Permanent",
      "status": "5.1.1",
      "message": "smtp; 550 5.1.1 <dead@example.com>: User unknown"
    },
    "reporting_mta": "mx.example.net"
  }
}
```

Mirror hard bounces into your own user records. Outbox will not mail the address
again, but only your application knows to stop *asking* it to.

## Reading the suppression list

```sh
curl "https://outbox.example.com/suppressions?origin=bounce" \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

```json
{
  "id": "…",
  "email": "dead@example.com",
  "origin": "bounce",
  "source_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "created_at": "2026-08-10 15:41:02.114+00"
}
```

`source_id` is the email that caused it, so "why is this address blocked" has an
answer rather than a guess.

## On the relay transport

If `OUTBOX_TRANSPORT=relay`, your upstream provider receives the bounces, not
you — the return path they use is theirs. Configure bounce forwarding on their
side, or use their webhooks. The inbound server here only sees what is addressed
to it.

## Testing it

The repo ships an end-to-end check that delivers real DSN and ARF messages to
the inbound server and asserts the outcome:

```sh
OUTBOX_API_KEY=ob_... bun run test:bounce
```

It covers a hard bounce suppressing an address, a later send to that address
being blocked, a soft bounce *not* suppressing, an ARF complaint suppressing, and
ordinary mail still being refused when receiving is off.

## Troubleshooting

**Bounces arrive but nothing happens.** Check the inbound server is running and
that the recipient really is a `bounces+…@<return path>.<domain>` address. The
log prints a line per report it processes.

**"could not attribute the report to a sent email".** The VERP tag was stripped —
some forwarders rewrite the envelope — and the report carried no usable
`Message-ID`. Nothing can be done for that individual report.

**"report named no recipient and the email had several".** A DSN that does not
name the failed address cannot be applied to a message sent to several people
without guessing which one failed, so Outbox declines to guess.

**Addresses suppressed that should not be.** Check the `origin` and `source_id`,
then remove them — see [Suppressions](/api/suppressions). If it is happening in
volume, the reports are probably being misclassified; the diagnostic is recorded
in `reason`.



---

# Receive inbound email

> Accept mail on your own domain, parse it, and act on it in your application.


# Receive inbound email

Outbox includes an SMTP server. Point a domain's MX record at it and mail addressed to
that domain is parsed, stored with attachments, and raised as `email.received`.

Useful for support inboxes, reply-to-comment threads, `+` addressing per customer, and
giving an agent a real mailbox.

## 1. Enable the listener

```sh
INBOUND_ENABLED=true
INBOUND_PORT=2525
OUTBOX_HOSTNAME=mail.acme.com
```

```sh
bun run inbound      # or `bun run dev`, which starts it when enabled
```

Port 2525 keeps the process off a privileged port. Forward 25 to it:

```sh
# Linux
iptables -t nat -A PREROUTING -p tcp --dport 25 -j REDIRECT --to-port 2525
```

Or terminate 25 at your load balancer and forward.

## 2. Enable receiving on the domain

```sh
curl -X PATCH https://outbox.example.com/domains/$DOMAIN_ID \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "capabilities": { "sending": "enabled", "receiving": "enabled" } }'
```

This adds an MX record to the domain's record set.

## 3. Publish the MX record

| Type | Host | Value | Priority |
|---|---|---|---|
| MX | `mail.acme.com` | `inbound.mail.acme.com` | 10 |

> If the domain already receives mail — a Google Workspace domain, for instance — do
> **not** point its MX at Outbox. Use a dedicated subdomain such as `inbound.acme.com`.
> Replacing a live MX record silently stops delivery of everyone's mail.

Verify:

```sh
dig +short MX mail.acme.com
```

## 4. Test it

Send a message to any address on the domain:

```sh
echo "Testing inbound" | mail -s "Hello" support@mail.acme.com
```

Then:

```sh
curl https://outbox.example.com/emails/receiving \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "received_email",
      "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
      "from": "Someone <someone@gmail.com>",
      "to": ["support@mail.acme.com"],
      "subject": "Hello",
      "created_at": "2026-08-10 14:22:01.114+00"
    }
  ]
}
```

Only addresses on a domain with receiving enabled are accepted. Everything else gets
`550 5.1.1 No such recipient here` at RCPT TO, so you are not an open relay.

## 5. React to it

Subscribe to `email.received`:

```sh
curl -X POST https://outbox.example.com/webhooks \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint": "https://acme.com/webhooks/inbound", "events": ["email.received"] }'
```

```ts
const handle = async (event: { type: string; data: any }) => {
  if (event.type !== "email.received") return

  const mail = await outbox.emails.received.get(event.data.email_id)

  await db.tickets.create({
    from: mail.data.from,
    subject: mail.data.subject,
    body: mail.data.text ?? mail.data.html,
    messageId: mail.data.message_id,
  })
}
```

The webhook carries a summary; fetch the full record for bodies and headers.

## Routing with plus addressing

`support+ticket-1234@mail.acme.com` arrives with the full address in `received_for`, so
you can route without a separate mailbox per thread:

```ts
const [address] = mail.data.received_for
const match = address.match(/\+([^@]+)@/)
const ticketId = match?.[1]
```

Reply with that address in `reply_to` and the thread routes itself.

## Threading

Preserve the headers so mail clients thread correctly:

```ts
await outbox.emails.send({
  from: "Support <support@mail.acme.com>",
  to: [mail.data.from],
  subject: mail.data.subject.startsWith("Re:") ? mail.data.subject : `Re: ${mail.data.subject}`,
  html: "<p>Thanks — we're looking into it.</p>",
  headers: {
    "In-Reply-To": mail.data.message_id,
    References: mail.data.message_id,
  },
})
```

Without `In-Reply-To` and `References` your reply starts a new thread, which reads as a
different conversation to the recipient.

## Attachments

```sh
curl https://outbox.example.com/emails/receiving/$ID/attachments \
  -H "Authorization: Bearer $OUTBOX_API_KEY" -H "User-Agent: my-app/1.0"
```

Fetch one to get Base64 `content`. The parser handles multipart, quoted-printable,
Base64, and RFC 2047 encoded headers, and keeps inline images with their `content_id`.

**Treat every attachment as hostile.** It arrived from the internet. Scan it, do not
execute it, and do not serve it back from your own domain without setting
`Content-Disposition: attachment`.

## Operational notes

**Messages are capped at 30MB.** Larger ones get `552`.

**Nothing is authenticated yet.** SPF, DKIM, and DMARC results are stored as `null` —
Outbox accepts and records rather than validating inbound. Do not treat the `From` header
as proof of identity for anything that matters.

**Everything is stored.** Raw message and attachments live in Postgres. Plan retention:

```sql
DELETE FROM received_emails WHERE created_at < now() - interval '90 days';
```

**Port 25 is often blocked.** Many providers block inbound 25 by default. Check before
building on it.



---

# Deploy to production

> Docker, systemd, TLS, scaling, and a pre-flight checklist.


# Deploy to production

Outbox is two long-running processes — an API and a worker — plus PostgreSQL. Nothing
exotic. This walks through a single-server deployment you can grow from.

## Docker Compose

```yaml
services:
  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: outbox
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: outbox
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U outbox"]
      interval: 10s
      retries: 5

  api:
    build: .
    restart: unless-stopped
    command: bun run bin/outbox.ts api
    env_file: .env
    ports:
      - "127.0.0.1:3000:3000"
    depends_on:
      postgres: { condition: service_healthy }

  worker:
    build: .
    restart: unless-stopped
    command: bun run bin/outbox.ts worker
    env_file: .env
    depends_on:
      postgres: { condition: service_healthy }

volumes:
  pgdata:
```

```dockerfile
FROM oven/bun:1.3-alpine
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
EXPOSE 3000
CMD ["bun", "run", "bin/outbox.ts", "api"]
```

Run migrations as a one-off before starting:

```sh
docker compose run --rm api bun run bin/outbox.ts migrate up
docker compose up -d
```

## systemd

If you would rather not containerise:

```ini
# /etc/systemd/system/outbox-api.service
[Unit]
Description=Outbox API
After=network.target postgresql.service

[Service]
Type=simple
User=outbox
WorkingDirectory=/opt/outbox
EnvironmentFile=/opt/outbox/.env
ExecStart=/usr/local/bin/bun run bin/outbox.ts api
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

Copy it to `outbox-worker.service` with `ExecStart=… worker`, then:

```sh
systemctl enable --now outbox-api outbox-worker
```

## TLS and the reverse proxy

```nginx
server {
  listen 443 ssl http2;
  server_name outbox.acme.com;

  ssl_certificate     /etc/letsencrypt/live/outbox.acme.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/outbox.acme.com/privkey.pem;

  client_max_body_size 50m;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}
```

Then:

```sh
PUBLIC_URL=https://outbox.acme.com
TRUSTED_PROXIES=127.0.0.1
```

`TRUSTED_PROXIES` matters. Outbox only honours `X-Forwarded-For` from a listed proxy;
otherwise the header is attacker-supplied and anyone could forge their IP past the rate
limiter.

`client_max_body_size` must exceed `MAX_ATTACHMENT_BYTES` after Base64 overhead — Base64
adds about a third.

## Scaling

**API** is stateless. Run several behind the load balancer.

**Workers** coordinate through Postgres with `SELECT … FOR UPDATE SKIP LOCKED`. Add more
processes; no configuration, no leader election.

```sh
docker compose up -d --scale worker=4
```

Raise `WORKER_CONCURRENCY` for more parallelism per worker. The practical ceiling is your
database connection count and, on the `smtp` transport, how fast receiving servers accept.

Watch the queue:

```sql
SELECT kind, status, count(*) FROM jobs GROUP BY kind, status;
```

A `pending` count that climbs and never falls means workers are down or too few.

## Backups

Everything is in Postgres, including message bodies, attachments, and **DKIM private
keys**.

```sh
pg_dump -Fc outbox > outbox-$(date +%F).dump
```

Automate it, store it off the box, and test a restore. Treat the dump as a secret: it
contains your customers' mail and the keys that authenticate your domains.

## Housekeeping

Nothing prunes automatically. A nightly cron:

```sql
DELETE FROM api_logs WHERE created_at < now() - interval '30 days';
DELETE FROM jobs WHERE status = 'done' AND updated_at < now() - interval '3 days';
DELETE FROM webhook_events WHERE created_at < now() - interval '30 days';
DELETE FROM rate_limits WHERE window_started_at < now() - interval '1 day';
```

Keep `email_events` as long as you want metrics — it is what they aggregate over.

## Monitoring

`GET /health` needs no auth and checks the database:

```json
{ "status": "ok", "version": "0.1.0" }
```

Returns 503 when Postgres is unreachable, so it works as a load balancer check.

Worth alerting on:

| Signal | Query | Meaning |
|---|---|---|
| Queue depth | `count(*) FROM jobs WHERE status='pending'` | Workers down or overloaded |
| Failed jobs | `count(*) FROM jobs WHERE status='failed'` | Something is systematically broken |
| Bounce rate | `/emails/metrics?metrics=bounce_rate` | List quality or reputation |
| Complaint rate | `/emails/metrics?metrics=complaint_rate` | Above 0.1%, act |
| Exhausted webhooks | `count(*) FROM webhook_events WHERE status='exhausted'` | A consumer is down |

## Pre-flight checklist

- [ ] `JWT_SECRET` is long and random, not the default
- [ ] `PUBLIC_URL` is the externally reachable HTTPS URL
- [ ] `TRUSTED_PROXIES` set if behind a proxy
- [ ] Postgres is not exposed to the internet
- [ ] Migrations applied; `migrate diff` reports "schema in sync"
- [ ] Transport chosen and tested end to end
- [ ] At least one domain verified, SPF/DKIM/DMARC passing at Gmail
- [ ] Suppression list imported, if migrating
- [ ] Backups automated **and a restore tested**
- [ ] Retention cron installed
- [ ] Health check wired to the load balancer
- [ ] Alerting on queue depth
- [ ] The instance owner account is one you control

## Upgrading

```sh
git pull
bun install
bun run migrate
docker compose up -d --build
```

Take a dump first. Migrations are forward-only in practice — `migrate:down` rolls back
exactly one and is meant for development.

The API is stateless, so a rolling restart drops no requests. Workers finish in-flight
jobs on shutdown; anything interrupted is reclaimed after five minutes and retried.



---

# Connect Inkling

> Pair Outbox with the Inkling CMS in one paste each direction — publish a post, subscribers get it.


# Connect Inkling

[Inkling](https://github.com/wess/inkling) is a headless CMS built on the same stack as
Outbox. Connected, they give you the loop most newsletters want: write in the CMS, hit
publish, subscribers get it.

The pairing runs both ways and each direction is one command and one paste.

| Direction | Gives you |
|---|---|
| Inkling → Outbox | Inkling can send email at all — tests, notifications, and broadcasting an entry on publish |
| Outbox → Inkling | Outbox can read published content and build a broadcast from it |

You can set up one direction, the other, or both.

## Connection tokens

Both sides speak the same token format:

```
<prefix>_<base64url({ v, url, key, name })>
```

It carries the URL *and* the API key together, so there is one field to paste rather than
two to get subtly wrong. `obxc_` tokens are issued by Outbox; `inkc_` by Inkling. Pasting
one where the other belongs is caught with a message saying so.

> A token is a credential in plain text. It is shown once, should not be committed, and
> can be revoked by deleting the key it names.

---

## Inkling sends through Outbox

### 1. Issue a token from Outbox

```sh
bun run bin/outbox.ts connect
```

```
  Outbox connection token — paste this into the other service.

obxc_eyJ2IjoxLCJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJrZXkiOiJvYl8…

  It carries http://localhost:3000 and a full-access API key named "Connection 2026-08-10".
```

Add `--send-only` for a key that can do nothing but send. The Inkling plugin also reads
segments, topics, and domains, so the default full-access key is what makes its settings
screen useful — use `--send-only` when you only want transactional sending.

### 2. Enable the plugin in Inkling

Admin → Plugins → **Outbox** → Enable. Then in **Outbox settings**:

| Setting | Value |
|---|---|
| Connection token | The `obxc_…` string |
| From address | `Acme <hello@mail.example.com>` — a domain [verified in Outbox](/tutorials/verify-a-domain) |
| Public site URL | `https://example.com`, used to link entries |

The **Email** panel now reports connection health, and warns if no sending domain is
verified yet.

### 3. Send a test

```sh
curl -X POST http://127.0.0.1:4300/ext/outbox/test \
  -H "Authorization: Bearer $INKLING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "you@example.com" }'
```

Or use the panel in the admin. Either way it goes out through Outbox and appears in your
Emails list.

### 4. Broadcast on publish

Set these in the plugin settings and publishing an entry sends it to a segment:

| Setting | Value |
|---|---|
| Broadcast on publish | on |
| Types to broadcast | `post` — comma-separated, empty means every type |
| Segment | An Outbox segment id |
| Topic | Optional. Lets people opt out of the newsletter without unsubscribing entirely |

The plugin's **targets** endpoint lists your Outbox segments and topics, so you can copy
an id without switching apps:

```sh
curl -H "Authorization: Bearer $INKLING_TOKEN" http://127.0.0.1:4300/ext/outbox/targets
```

Publish an entry and the log shows it:

```
[plugin:outbox] broadcast 066e9ccf-cf89-4244-9d33-af6a528e1855 queued for the-widget
```

A failed broadcast never fails the publish. It is logged and the entry goes live
regardless — losing a post because an email server was down would be the wrong trade.

---

## Outbox reads Inkling content

### 1. Issue a token from Inkling

```sh
bun run connect
```

```
  Inkling connection token — paste this into the other service.

inkc_eyJ2IjoxLCJ1cmwiOiJodHRwOi8vMTI3LjAuMC4xOjQzMDAiLCJrZXkiOiJpbmtf…
```

Scope it to particular types if you like:

```sh
bun run connect --scopes post,announcement
```

### 2. Paste it into Outbox

In the dashboard: **Integrations → Inkling → Connect**. Add your public site URL so
emails link back to the article.

Or from the command line:

```sh
bun run bin/outbox.ts connect inkling inkc_…
```

```
connected to inkling at http://127.0.0.1:4300 — 2 content types readable
```

The credential is verified before it is stored, so a bad paste fails immediately with a
usable message rather than at the first send.

### 3. Build a broadcast from an entry

```sh
curl -X POST https://outbox.example.com/broadcasts \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
    "from": "Acme <news@mail.example.com>",
    "source": { "provider": "inkling", "type": "post", "slug": "the-widget" },
    "send": true
  }'
```

`source` fills in the subject, HTML, and text from the published entry. Anything you pass
explicitly still wins, so overriding just the subject is one extra field.

The Integrations page browses your published content and previews exactly what a
broadcast would send.

---

## API reference

| Endpoint | Purpose |
|---|---|
| `POST /integrations/connect` | Pair from a token: `{ provider, token, settings? }` |
| `GET /integrations` | List connections |
| `GET /integrations/:provider` | One connection |
| `POST /integrations/:provider/check` | Re-probe and record health |
| `PATCH /integrations/:provider` | Update settings, e.g. `site_url` |
| `DELETE /integrations/:provider` | Disconnect |
| `GET /integrations/inkling/types` | Readable content types |
| `GET /integrations/inkling/content/:type` | Published entries |
| `GET /integrations/inkling/content/:type/:slug/preview` | Rendered email, unsent |

API keys are never returned by any of these.

## Troubleshooting

**"This is a `obxc` token; a `inkc` token was expected."** The tokens went the wrong way.
`obxc_` goes into Inkling; `inkc_` comes back to Outbox.

**"Could not reach Inkling at …"** Check the URL in the token is reachable *from the
Outbox host*. `localhost` in a container is not your laptop.

**"This API key is restricted to only send emails."** The plugin's status and targets
screens need a full-access key. Re-run `connect` without `--send-only`.

**"No verified sending domain yet."** Outbox refuses real sends from unverified domains.
See [Verify a domain](/tutorials/verify-a-domain). On the `console` transport this does
not apply, which is why the test send works before DNS does.

**Publishing sends nothing.** Check `broadcastOnPublish` is on, the entry's type is in
`broadcastTypes`, and a segment is set. The Inkling log records why it skipped.



---

# Introduction

> Base URL, authentication, required headers, response codes, and rate limits.


# API reference

The Outbox API is REST over JSON. It mirrors the Resend API: the same paths, request
bodies, response shapes, and error envelope. Any Resend SDK works against it by changing
only the base URL.

## Base URL

Whatever host you deployed to:

```
https://outbox.example.com
```

Locally that is `http://localhost:3000`. Unlike Resend there is no separate `api.`
hostname — the API is served at the root and the dashboard lives under `/app`, so a base
URL swap is all an SDK needs.

## Authentication

Send your API key as a bearer token:

```
Authorization: Bearer ob_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Keys are created in the dashboard or through [the API](/api/api-keys) and shown exactly
once. Only a SHA-256 hash is stored, so a lost key cannot be recovered — create a new one
and delete the old.

Keys carry a permission:

- **`full_access`** — every endpoint.
- **`sending_access`** — `POST /emails` and `POST /emails/batch` only. Every other
  endpoint returns `401 restricted_api_key`.

A key may also be restricted to one domain, in which case it can only send from that
domain.

## User-Agent

Every request must include a `User-Agent`. Requests without one are rejected:

```json
{
  "statusCode": 403,
  "name": "invalid_user_agent",
  "message": "The User-Agent header is required. Set it to identify your application, e.g. `my-app/1.0`."
}
```

Every official SDK and most HTTP clients set this automatically. Bare `curl` does too.
Explicitly clearing it — `curl -H "User-Agent:"` — is what trips this.

## Response codes

| Status | Meaning |
|---|---|
| `200` | Success |
| `201` | Created |
| `400` | Malformed request or bad parameter |
| `401` | Missing key, or a restricted key on a forbidden endpoint |
| `403` | Invalid key, unverified sending domain, or missing User-Agent |
| `404` | Resource not found |
| `409` | Conflict — a duplicate, or a concurrent idempotent request |
| `422` | Validation failed or a required field is missing |
| `429` | Rate limit exceeded |
| `5xx` | Server error |

## Errors

Every error uses the same envelope:

```json
{
  "statusCode": 422,
  "name": "missing_required_field",
  "message": "Missing `subject` field."
}
```

`name` is the stable machine-readable slug — switch on it rather than parsing `message`.
See [Errors](/api/errors) for the full list.

## Rate limits

The default is **10 requests per second per team**, shared across all of that team's API
keys, matching Resend's default. Change it with `RATE_LIMIT_PER_SECOND`.

Exceeding it returns 429 with the standard headers:

```
retry-after: 1
ratelimit-limit: 10
ratelimit-remaining: 0
ratelimit-reset: 1
```

Back off and retry. A client that ignores 429s will drop requests.

## Pagination

List endpoints return a consistent envelope and use cursor pagination. See
[Pagination](/api/pagination).

```json
{
  "object": "list",
  "has_more": false,
  "data": []
}
```

## Idempotency

`POST /emails` and `POST /emails/batch` accept an `Idempotency-Key` header. Repeating a
request with the same key replays the original response instead of sending again — see
[Emails](/api/emails#idempotency).

## Endpoints

| Group | Paths |
|---|---|
| [Emails](/api/emails) | `/emails`, `/emails/batch`, `/emails/:id`, `/emails/receiving` |
| [Domains](/api/domains) | `/domains` |
| [API keys](/api/api-keys) | `/api-keys` |
| [Contacts](/api/contacts) | `/contacts` |
| [Contact properties](/api/contact-properties) | `/contact-properties` |
| [Segments](/api/segments) | `/segments`, `/audiences` |
| [Topics](/api/topics) | `/topics` |
| [Broadcasts](/api/broadcasts) | `/broadcasts` |
| [Templates](/api/templates) | `/templates` |
| [Suppressions](/api/suppressions) | `/suppressions` |
| [Webhooks](/api/webhooks) | `/webhooks` |
| [Automations](/api/automations) | `/automations`, `/events/send` |
| [Metrics](/api/metrics) | `/emails/metrics`, `/segments/metrics` |
| [Logs](/api/logs) | `/logs` |



---

# Emails

> Send, retrieve, schedule, cancel, and list emails, plus attachments and inbound mail.


# Emails

## Send an email

```
POST /emails
```

### Body

| Field | Type | Notes |
|---|---|---|
| `from` | `string` | **Required.** `email@example.com` or `Name <email@example.com>` |
| `to` | `string \| string[]` | **Required.** Max 50 recipients across to, cc, and bcc |
| `subject` | `string` | **Required** unless supplied by a template |
| `html` | `string` | One of `html`, `text`, or `template` is required |
| `text` | `string` | Derived from `html` when omitted |
| `cc` | `string \| string[]` | |
| `bcc` | `string \| string[]` | |
| `reply_to` | `string \| string[]` | |
| `headers` | `object` | Custom headers. Identity and routing headers are ignored |
| `tags` | `array` | `{ name, value }`, alphanumeric plus `_` and `-` |
| `topic_id` | `string` | Gates delivery on subscription |
| `scheduled_at` | `string` | ISO 8601 or natural language |
| `attachments` | `array` | See [Attachments](#attachments) |
| `template` | `object` | `{ id, variables }` — id or alias |

```sh
curl -X POST https://outbox.example.com/emails \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@acme.com>",
    "to": ["user@example.com"],
    "subject": "Hello World",
    "html": "<strong>It works!</strong>",
    "tags": [{ "name": "category", "value": "confirm_email" }]
  }'
```

```json
{ "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }
```

The response returns as soon as the email is validated and queued. Delivery happens in
the worker — poll the email or subscribe to [webhooks](/api/webhooks) for its outcome.

### Sending domains

`from` must use a domain you have added and verified. An unverified domain returns:

```json
{
  "statusCode": 403,
  "name": "invalid_from_address",
  "message": "The acme.com domain is not verified. Add and verify it at /domains."
}
```

With `OUTBOX_TRANSPORT=console` this check is skipped, so you can develop before owning
a domain.

## Send a batch

```
POST /emails/batch
```

Takes an array of up to 100 send payloads and returns their ids in order. Attachments
are not supported in batch sends.

```sh
curl -X POST https://outbox.example.com/emails/batch \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '[
    { "from": "Acme <a@acme.com>", "to": ["one@example.com"], "subject": "One", "text": "1" },
    { "from": "Acme <a@acme.com>", "to": ["two@example.com"], "subject": "Two", "text": "2" }
  ]'
```

```json
{
  "data": [
    { "id": "ae2014de-c168-4c61-8267-70d2662a1ce1" },
    { "id": "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb" }
  ]
}
```

## Retrieve an email

```
GET /emails/:id
```

```json
{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "message_id": "<111-222-333@acme.com>",
  "to": ["user@example.com"],
  "from": "Acme <onboarding@acme.com>",
  "created_at": "2026-04-03 22:13:42.674981+00",
  "subject": "Hello World",
  "html": "<strong>It works!</strong>",
  "text": null,
  "bcc": [],
  "cc": [],
  "reply_to": [],
  "last_event": "delivered",
  "scheduled_at": null,
  "tags": [{ "name": "category", "value": "confirm_email" }]
}
```

### last_event

| Value | Meaning |
|---|---|
| `queued` | Accepted, waiting for a worker |
| `scheduled` | Waiting for its send time |
| `sent` | Handed to the transport |
| `delivered` | Accepted by the receiving server |
| `delivery_delayed` | Temporary failure, will retry |
| `opened` | Tracking pixel loaded |
| `clicked` | A tracked link was followed |
| `bounced` | Permanent failure |
| `complained` | Marked as spam |
| `failed` | Could not be sent |
| `canceled` | A scheduled send was cancelled |
| `suppressed` | Recipient is on the suppression list |

Terminal states never regress — an open arriving after a bounce leaves the bounce in
place.

`bounced`, `complained`, and `delivery_delayed` are usually set *after* delivery, from
a report that arrives at the return path minutes or days later. See [Handle
bounces](/tutorials/handle-bounces).

## List emails

```
GET /emails
```

Always paginated. Accepts `limit`, `after`, `before`. `cc`, `bcc`, and `reply_to` come
back as `null` rather than `[]` in list items, matching Resend.

## Schedule

Pass `scheduled_at` as ISO 8601 or natural language:

```json
{ "scheduled_at": "in 1 hour" }
```

Understood forms: `in 30 seconds`, `in 5 minutes`, `in 2 hours`, `in 3 days`,
`in 1 week`, `tomorrow`, `now`, and any ISO 8601 timestamp. A time in the past sends
immediately rather than erroring, which absorbs clock skew between client and server.

### Reschedule

```
PATCH /emails/:id
```

```json
{ "scheduled_at": "2026-08-05T11:52:01.858Z" }
```

Only emails in `scheduled` state can be rescheduled.

### Cancel

```
POST /emails/:id/cancel
```

Only emails in `scheduled` state can be cancelled.

## Idempotency

Pass an `Idempotency-Key` header to make a send safe to retry:

```sh
curl -X POST https://outbox.example.com/emails \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Idempotency-Key: order-1234-confirmation" \
  -H "Content-Type: application/json" \
  -d '{ "from": "...", "to": ["..."], "subject": "...", "html": "..." }'
```

| Situation | Result |
|---|---|
| Same key, same body | Replays the stored response. Nothing is sent again |
| Same key, different body | `400 invalid_idempotent_request` |
| Same key while the first is in flight | `409 concurrent_idempotent_requests` |
| A failed request | The key is released so a retry can succeed |

Keys live 24 hours. Use something derived from the thing you are emailing about — an
order id, not a random UUID.

## Attachments

Up to 40MB per email after Base64 encoding, configurable with `MAX_ATTACHMENT_BYTES`.

```json
{
  "attachments": [
    { "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." },
    { "filename": "logo.png", "path": "https://acme.com/logo.png", "content_id": "logo" }
  ]
}
```

| Field | Notes |
|---|---|
| `filename` | Required unless `path` is given |
| `content` | Base64 string or byte array |
| `path` | URL to fetch instead of inline content |
| `content_type` | Guessed from the extension when omitted |
| `content_id` | Makes it inline — reference as `cid:logo` in HTML |

Executable extensions (`.exe`, `.bat`, `.js`, `.jar` and similar) are rejected with
`422 invalid_attachment`, since receiving servers strip them anyway.

### List and retrieve

```
GET /emails/:email_id/attachments
GET /emails/:email_id/attachments/:id
```

The single-attachment response includes the Base64 `content`.

## Received emails

Available when [receiving](/tutorials/receive-inbound-email) is enabled.

```
GET /emails/receiving
GET /emails/receiving/:id
GET /emails/receiving/:email_id/attachments
GET /emails/receiving/:email_id/attachments/:id
```

```json
{
  "object": "received_email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "message_id": "<abc@sender.com>",
  "from": "Sender <sender@example.com>",
  "to": ["support@acme.com"],
  "cc": [],
  "received_for": ["support@acme.com"],
  "subject": "Help please",
  "html": "<p>My widget is broken.</p>",
  "text": "My widget is broken.",
  "headers": { "message-id": "<abc@sender.com>" },
  "spf": null,
  "dkim": null,
  "dmarc": null,
  "created_at": "2026-04-03 22:13:42.674981+00"
}
```

## Metrics

See [Metrics](/api/metrics) for `GET /emails/metrics`.



---

# Domains

> Add, verify, configure, and delete sending domains.


# Domains

A domain must be added and verified before Outbox will deliver mail from it. Adding one
generates a DKIM keypair and the DNS records you need to publish.

## Create a domain

```
POST /domains
```

| Field | Type | Notes |
|---|---|---|
| `name` | `string` | **Required.** The domain, e.g. `acme.com` |
| `region` | `string` | Stored and returned; a self-hosted install has one region |
| `custom_return_path` | `string` | Subdomain for the bounce path. Default `send` |
| `open_tracking` | `boolean` | Default `false` |
| `click_tracking` | `boolean` | Default `false` |
| `tracking_subdomain` | `string` | Default `links` |
| `tls` | `string` | `opportunistic` or `enforced` |
| `capabilities` | `object` | `{ sending, receiving }`, each `enabled` or `disabled` |

```sh
curl -X POST https://outbox.example.com/domains \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme.com", "open_tracking": true, "click_tracking": true }'
```

```json
{
  "object": "domain",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "acme.com",
  "status": "not_started",
  "created_at": "2026-04-26 20:21:26.347412+00",
  "region": "us-east-1",
  "open_tracking": true,
  "click_tracking": true,
  "tracking_subdomain": "links",
  "tls": "opportunistic",
  "custom_return_path": "send",
  "capabilities": { "sending": "enabled", "receiving": "disabled" },
  "records": [
    {
      "record": "SPF",
      "name": "send",
      "type": "MX",
      "ttl": "Auto",
      "status": "not_started",
      "value": "feedback-smtp.mail.example.com",
      "priority": 10
    },
    {
      "record": "DKIM",
      "name": "outbox._domainkey",
      "type": "TXT",
      "ttl": "Auto",
      "status": "not_started",
      "value": "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQ..."
    }
  ]
}
```

> The record **values** point at your installation rather than at SES, so they differ
> from Resend's. The record **set** and the API shape are the same.

### Records

| `record` | Type | Purpose |
|---|---|---|
| `SPF` | TXT at `@` and `send` | Authorises this host to send |
| `SPF` | MX at `send` | Return path for bounces |
| `DKIM` | TXT at `outbox._domainkey` | Public key for signature verification |
| `DMARC` | TXT at `_dmarc` | Policy, starting at `p=none` |
| `Tracking` | CNAME at `links` | Only when open or click tracking is on |
| `MX` | MX at `@` | Only when receiving is enabled |

The DKIM key is 1024-bit so the TXT record fits in a single DNS string. That is
sufficient for both transactional and marketing mail.

## Verify a domain

```
POST /domains/:domain_id/verify
```

Resolves every record and updates its status.

```json
{
  "object": "domain",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "status": "verified",
  "records": [ /* each with an updated status */ ]
}
```

| `status` | Meaning |
|---|---|
| `not_started` | Nothing resolves yet |
| `pending` | Some records resolve |
| `verified` | SPF and DKIM both resolve — sending is enabled |
| `failed` | Nothing resolved on the last check |

Tracking and receiving records are advisory and do not gate verification. DNS
propagation can take minutes to hours; re-run verify rather than assuming failure.

## Retrieve a domain

```
GET /domains/:domain_id
```

Returns the domain with its current records.

## List domains

```
GET /domains
```

Pagination is optional — omit `limit` to get everything. List items are trimmed to `id`,
`name`, `status`, `created_at`, and `region`.

## Update a domain

```
PATCH /domains/:domain_id
```

| Field | Notes |
|---|---|
| `click_tracking` | Rewrites links through your tracking subdomain |
| `open_tracking` | Injects a tracking pixel |
| `tracking_subdomain` | |
| `tls` | `opportunistic` or `enforced` |
| `custom_return_path` | |
| `capabilities` | `{ sending, receiving }` |

Toggling tracking or receiving changes which DNS records apply, so the record set is
rebuilt. Records that did not move keep their verification status.

`tls: "enforced"` refuses to deliver to a server that will not negotiate STARTTLS. That
is a deliverability trade — some receivers still do not support it.

## Delete a domain

```
DELETE /domains/:domain_id
```

Deleting a domain deletes its DKIM keys. Re-adding it generates new ones and requires
publishing DNS again.

## Events

`domain.created`, `domain.updated`, and `domain.deleted` fire to subscribed
[webhooks](/api/webhooks).



---

# API keys

> Create, list, and delete API keys, with permission and domain scoping.


# API keys

## Create an API key

```
POST /api-keys
```

| Field | Type | Notes |
|---|---|---|
| `name` | `string` | **Required** |
| `permission` | `string` | `full_access` (default) or `sending_access` |
| `domain_id` | `string` | Restrict the key to one sending domain |

```sh
curl -X POST https://outbox.example.com/api-keys \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production", "permission": "sending_access" }'
```

```json
{
  "id": "dacf4072-4119-4d88-932f-6202748ac7c8",
  "token": "ob_EXAMPLEKEYdonotusethisvalue456"
}
```

> The token is returned exactly once. Outbox stores only a SHA-256 hash, so it cannot be
> shown again — if you lose it, create a new key and delete the old one.

### Permissions

| Permission | Reach |
|---|---|
| `full_access` | Every endpoint |
| `sending_access` | `POST /emails` and `POST /emails/batch` only |

A `sending_access` key calling anything else gets:

```json
{
  "statusCode": 401,
  "name": "restricted_api_key",
  "message": "This API key is restricted to only send emails. Use a full access key for this operation."
}
```

Use `sending_access` for keys that live anywhere you would not want a full-access
credential — edge functions, CI, a service that only ever sends.

### Domain restriction

Passing `domain_id` limits the key to sending from that domain. Attempting to send from
another returns `403 invalid_api_key`. Useful in multi-tenant setups where each tenant
sends from their own domain.

## List API keys

```
GET /api-keys
```

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "91c4b0f1-2ad7-4e8b-9a0d-cf6d3c1a0e19",
      "name": "Production",
      "created_at": "2026-04-08 00:11:13.110779+00"
    }
  ]
}
```

Tokens are never included. Pagination is optional.

## Delete an API key

```
DELETE /api-keys/:api_key_id
```

```json
{}
```

Deletion is immediate — in-flight requests using that key will fail. Emails already sent
with it are unaffected; their `api_key_id` is nulled.

## Rotating a key

There is no rotate endpoint, because rotation is two calls and doing it explicitly
avoids a window where neither key works:

1. `POST /api-keys` to create the replacement.
2. Deploy it.
3. `DELETE /api-keys/:id` for the old one.

Check the [logs](/api/logs) between steps 2 and 3 to confirm nothing is still using the
old key.



---

# Contacts

> Create, update, and list contacts, with properties, segment membership, and topic subscriptions.


# Contacts

A contact is a person you can send to, unique by email within a team.

## Create a contact

```
POST /contacts
```

| Field | Type | Notes |
|---|---|---|
| `email` | `string` | **Required.** Unique within the team |
| `first_name` | `string` | |
| `last_name` | `string` | |
| `unsubscribed` | `boolean` | Default `false` |
| `properties` | `object` | Keys must already exist as [contact properties](/api/contact-properties) |
| `segments` | `array` | `[{ id }]` — adds the contact to each |
| `topics` | `array` | `[{ id, subscription }]` |

```sh
curl -X POST https://outbox.example.com/contacts \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "steve@example.com",
    "first_name": "Steve",
    "last_name": "Wozniak",
    "properties": { "company_name": "Apple" },
    "segments": [{ "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }],
    "topics": [{ "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e", "subscription": "opt_in" }]
  }'
```

```json
{ "object": "contact", "id": "e169aa45-1ecf-4183-9955-b1499d5701d3" }
```

An unknown property key is rejected rather than silently dropped:

```json
{
  "statusCode": 400,
  "name": "invalid_parameter",
  "message": "Unknown contact property `nope`. Create it first at /contact-properties."
}
```

## Retrieve a contact

```
GET /contacts/:id
```

`:id` accepts either the contact id or the email address:

```sh
curl https://outbox.example.com/contacts/steve@example.com \
  -H "Authorization: Bearer ob_xxxxxxxxx" -H "User-Agent: my-app/1.0"
```

```json
{
  "object": "contact",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "email": "steve@example.com",
  "first_name": "Steve",
  "last_name": "Wozniak",
  "created_at": "2026-10-06 23:47:56.678+00",
  "unsubscribed": false,
  "properties": { "company_name": "Apple" }
}
```

Properties fall back to the property's `fallback_value` when the contact has no value of
its own, so templates always have something to render.

## Update a contact

```
PATCH /contacts/:id
```

Accepts `first_name`, `last_name`, `unsubscribed`, and `properties`. Only supplied
fields change.

```json
{ "unsubscribed": true }
```

Setting `unsubscribed` excludes the contact from every broadcast. It does not add them
to the [suppression list](/api/suppressions) — transactional mail still reaches them,
which is usually what you want for receipts and password resets.

## List contacts

```
GET /contacts
GET /contacts?segment_id=78261eea-8f8b-4381-83c6-79fa7120f1cf
```

Pagination is optional. `segment_id` narrows to one segment's membership.

## Delete a contact

```
DELETE /contacts/:id
```

Accepts an id or an email. Deleting a contact removes their segment memberships and
topic subscriptions. Emails already sent to them are unaffected.

## Topic subscriptions

```
GET /contacts/:id/topics
```

Returns every topic in the team with this contact's effective subscription, falling back
to the topic default where they have not chosen:

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
      "name": "Weekly Newsletter",
      "description": "Weekly digest",
      "subscription": "opt_in",
      "created_at": "2026-04-08 00:11:13.110779+00"
    }
  ]
}
```

```
PATCH /contacts/:id/topics
```

```json
{
  "topics": [
    { "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e", "subscription": "opt_out" }
  ]
}
```

## Segment membership

```
GET    /contacts/:id/segments
POST   /contacts/:id/segments/:segment_id
DELETE /contacts/:id/segments/:segment_id
```

Adding a contact to a segment they are already in is a no-op, not an error.

## Audience-scoped routes

Before Segments, contacts hung off an audience. Those paths still work, so existing SDK
code that passes an `audience_id` keeps functioning:

```
POST   /audiences/:segment_id/contacts
GET    /audiences/:segment_id/contacts
GET    /audiences/:segment_id/contacts/:id
PATCH  /audiences/:segment_id/contacts/:id
DELETE /audiences/:segment_id/contacts/:id
```

They read and write the same contacts as `/contacts`. Creating through this path adds
the contact to the segment; if the contact already exists it is added rather than
rejected.

## Events

`contact.created`, `contact.updated`, and `contact.deleted` fire to subscribed
[webhooks](/api/webhooks).



---

# Segments

> Group contacts for broadcasts. Includes the legacy audiences alias.


# Segments

A segment is a named group of contacts. Broadcasts target a segment.

> Segments were previously called audiences. Every endpoint below is mounted at both
> `/segments` and `/audiences`, so older SDK code keeps working.

## Create a segment

```
POST /segments
```

```json
{ "name": "Registered Users" }
```

```json
{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "name": "Registered Users"
}
```

## Retrieve a segment

```
GET /segments/:segment_id
```

```json
{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "name": "Registered Users",
  "created_at": "2026-10-06 22:59:55.977+00"
}
```

## List segments

```
GET /segments
```

Pagination is optional.

## List a segment's contacts

```
GET /segments/:segment_id/contacts
```

Returns full contact objects, paginated.

## Delete a segment

```
DELETE /segments/:segment_id
```

Deleting a segment removes the grouping, not the contacts. Broadcasts that referenced it
keep their history; their `segment_id` becomes `null`.

## Adding and removing contacts

Membership is managed from the contact side:

```
POST   /contacts/:id/segments/:segment_id
DELETE /contacts/:id/segments/:segment_id
```

Or at creation time:

```json
{
  "email": "steve@example.com",
  "segments": [{ "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf" }]
}
```

## Metrics

```
GET /segments/metrics
```

Optionally filtered with `segment_id` (comma-separated).

```json
{
  "object": "list",
  "data": [
    {
      "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "name": "Registered Users",
      "all_contacts": 1284,
      "subscribed_contacts": 1201,
      "unsubscribed_contacts": 83
    }
  ]
}
```

`subscribed_contacts` is what a broadcast to this segment will actually attempt, before
suppression and topic checks narrow it further.



---

# Topics

> Subscription categories that let recipients opt out of one kind of mail without opting out of everything.


# Topics

A topic is a subscription category — "Weekly newsletter", "Product updates", "Billing
alerts". Without topics, unsubscribing is all-or-nothing; with them a recipient can drop
the newsletter and keep the security notices.

## Create a topic

```
POST /topics
```

| Field | Type | Notes |
|---|---|---|
| `name` | `string` | **Required** |
| `default_subscription` | `string` | **Required.** `opt_in` or `opt_out` |
| `description` | `string` | Shown on the unsubscribe page |
| `visibility` | `string` | `public` (default) or `private` |

```sh
curl -X POST https://outbox.example.com/topics \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Newsletter",
    "description": "A digest every Thursday",
    "default_subscription": "opt_in"
  }'
```

```json
{ "object": "topic", "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e" }
```

### Choosing a default

`default_subscription` decides what happens for someone who has never expressed a
preference — including people who are not contacts at all.

| Default | Behaviour | Suits |
|---|---|---|
| `opt_in` | Send unless they opted out | Product updates, transactional-adjacent mail |
| `opt_out` | Do not send unless they opted in | Marketing, anything where consent matters |

Pick `opt_out` when consent is a legal question rather than a preference.

## Retrieve a topic

```
GET /topics/:topic_id
```

```json
{
  "object": "topic",
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "name": "Weekly Newsletter",
  "description": "A digest every Thursday",
  "default_subscription": "opt_in",
  "visibility": "public",
  "created_at": "2026-04-08 00:11:13.110779+00"
}
```

## List topics

```
GET /topics
```

Always paginated.

## Update a topic

```
PATCH /topics/:topic_id
```

Accepts `name`, `description`, and `visibility`. `default_subscription` is deliberately
immutable — changing it would silently alter the consent status of everyone who never
chose.

## Delete a topic

```
DELETE /topics/:topic_id
```

Deletes the topic and every subscription to it. Emails sent with that `topic_id` keep
their history.

## Sending with a topic

Pass `topic_id` on a send or a broadcast and each recipient is checked independently:

```json
{
  "from": "Acme <news@acme.com>",
  "to": ["reader@example.com"],
  "subject": "This week at Acme",
  "html": "<p>…</p>",
  "topic_id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e"
}
```

| Recipient | Outcome |
|---|---|
| Contact, opted in | Sent |
| Contact, opted out | Skipped, `email.failed` with a reason |
| Not a contact | Follows `default_subscription` |

Each of `to`, `cc`, and `bcc` is evaluated separately, so one opted-out recipient does
not block the rest.

## Managing subscriptions

Per contact:

```
GET   /contacts/:id/topics
PATCH /contacts/:id/topics
```

```json
{
  "topics": [
    { "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e", "subscription": "opt_out" }
  ]
}
```

## Unsubscribe links

Put the placeholder in your body and Outbox replaces it per recipient with a signed URL:

```html
<a href="{{{OUTBOX_UNSUBSCRIBE_URL}}}">Unsubscribe</a>
```

`{{{RESEND_UNSUBSCRIBE_URL}}}` is accepted too, so templates carried over from Resend
work unchanged.

When the email carries a `topic_id` the link opts the recipient out of that topic only.
Without one it unsubscribes them entirely. Outbox also sets `List-Unsubscribe` and
`List-Unsubscribe-Post`, so mail clients can offer one-click unsubscribe — which
materially helps deliverability at Gmail and Outlook.



---

# Contact properties

> Define typed custom fields on contacts for use as template variables.


# Contact properties

Contact properties are the custom fields you can store on a contact and reference in
templates and broadcasts. They are declared up front, so a typo in a send is an error
rather than a blank in someone's inbox.

## Create a property

```
POST /contact-properties
```

| Field | Type | Notes |
|---|---|---|
| `key` | `string` | **Required.** Letters, numbers, and underscores; must not start with a digit |
| `type` | `string` | **Required.** `string` or `number` |
| `fallback_value` | `string \| number` | Used when a contact has no value |

```sh
curl -X POST https://outbox.example.com/contact-properties \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "key": "company_name", "type": "string", "fallback_value": "your company" }'
```

```json
{ "object": "contact_property", "id": "f30e04c9-2dd5-4fb4-a6eb-fbed047d3416" }
```

The fallback is what makes personalisation safe. `Hi {{{first_name}}} at
{{{company_name}}}` renders sensibly even for contacts imported without a company.

## Retrieve a property

```
GET /contact-properties/:contact_property_id
```

```json
{
  "object": "contact_property",
  "id": "f30e04c9-2dd5-4fb4-a6eb-fbed047d3416",
  "key": "company_name",
  "type": "string",
  "fallback_value": "your company",
  "created_at": "2026-10-06 23:47:56.678+00",
  "updated_at": "2026-10-06 23:47:56.678+00"
}
```

Properties typed `number` return their fallback as a number, not a string.

## List properties

```
GET /contact-properties
```

Pagination is optional.

## Update a property

```
PATCH /contact-properties/:contact_property_id
```

```json
{ "fallback_value": "Acme Corp" }
```

Only `fallback_value` is mutable. `key` and `type` are fixed — changing either would
invalidate values already stored against it and silently break templates.

## Delete a property

```
DELETE /contact-properties/:contact_property_id
```

Deletes the definition and every contact's value for it. Templates referencing it will
render empty.

## Setting values

Values are set on the contact, not on the property:

```sh
curl -X PATCH https://outbox.example.com/contacts/steve@example.com \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{ "properties": { "company_name": "Apple", "seat_count": 42 } }'
```

A key with no matching property is rejected:

```json
{
  "statusCode": 400,
  "name": "invalid_parameter",
  "message": "Unknown contact property `seat_cnt`. Create it first at /contact-properties."
}
```

A `number` property given a non-numeric value is rejected the same way.

## Using them in content

Properties are available by bare name, and contact fields under `contact.`:

```html
<p>Hi {{{contact.first_name|there}}},</p>
<p>{{{company_name}}} is on the {{{plan|free}}} plan with {{{seat_count}}} seats.</p>
```

Resolution order for each placeholder:

1. The contact's own value.
2. The inline fallback after `|`.
3. The property's `fallback_value`.
4. Empty string.

See [Templates](/api/templates) for the full syntax.



---

# Broadcasts

> Send one personalised message to every contact in a segment, with per-broadcast metrics.


# Broadcasts

A broadcast is one message sent to every contact in a segment. Fan-out happens in the
worker: each eligible contact gets a real email row rendered with their own values, so
tracking, events, and metrics work exactly as they do for transactional mail.

## Create a broadcast

```
POST /broadcasts
```

| Field | Type | Notes |
|---|---|---|
| `segment_id` | `string` | **Required.** `audience_id` is accepted as an alias |
| `from` | `string` | **Required** |
| `subject` | `string` | **Required.** Supports variables |
| `html` | `string` | One of `html` or `text` is required |
| `text` | `string` | |
| `preview_text` | `string` | Preheader shown in the inbox list |
| `reply_to` | `string \| string[]` | |
| `name` | `string` | Internal label. Defaults to the subject |
| `topic_id` | `string` | Gates each recipient on subscription |
| `send` | `boolean` | Send immediately instead of saving a draft |
| `scheduled_at` | `string` | ISO 8601 or natural language |

```sh
curl -X POST https://outbox.example.com/broadcasts \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
    "from": "Acme <news@acme.com>",
    "subject": "Hello {{{contact.first_name|there}}}",
    "html": "<p>Hi {{{contact.first_name|there}}}, here is this week.</p><p><a href=\"{{{OUTBOX_UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>",
    "preview_text": "This week at Acme"
  }'
```

```json
{ "object": "broadcast", "id": "559ac32e-9ef5-46fb-82a1-b76b840c0f7b" }
```

Without `send` or `scheduled_at` the broadcast is saved as a draft.

## Personalisation

Subject and body are rendered per contact:

```html
<p>Hi {{{contact.first_name|there}}}, {{{company_name}}} renews on {{{renewal_date}}}.</p>
```

Available: `contact.email`, `contact.first_name`, `contact.last_name`, and every
[contact property](/api/contact-properties) by name. Always give an inline fallback for
anything that might be missing.

## Send a broadcast

```
POST /broadcasts/:broadcast_id/send
```

```json
{ "scheduled_at": "in 2 hours" }
```

Omit the body to send now. Status moves `draft` → `sending` → `sent`, or `scheduled`
first if a time was given.

### Who gets skipped

Fan-out records a reason for every contact it skips:

| Reason | Cause |
|---|---|
| `unsubscribed` | The contact's `unsubscribed` flag |
| `suppressed` | The address is on the suppression list |
| `opted out of topic` | The broadcast has a `topic_id` they opted out of |

## Retrieve a broadcast

```
GET /broadcasts/:broadcast_id
```

```json
{
  "object": "broadcast",
  "id": "559ac32e-9ef5-46fb-82a1-b76b840c0f7b",
  "name": "Announcements",
  "audience_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "from": "Acme <news@acme.com>",
  "subject": "Hello {{{contact.first_name|there}}}",
  "reply_to": null,
  "preview_text": "This week at Acme",
  "html": "<p>…</p>",
  "text": null,
  "status": "sent",
  "created_at": "2026-12-01 19:32:22.980+00",
  "scheduled_at": null,
  "sent_at": "2026-12-01 19:33:02.114+00",
  "topic_id": null
}
```

`audience_id` is returned alongside `segment_id` with the same value, so older SDKs keep
working.

## List broadcasts

```
GET /broadcasts
```

Pagination is optional. List items are trimmed to ids, status, and timestamps.

## Update a broadcast

```
PATCH /broadcasts/:broadcast_id
```

Accepts the same content fields as create. A broadcast that is `sending` or `sent` can
no longer be edited:

```json
{
  "statusCode": 400,
  "name": "invalid_parameter",
  "message": "A broadcast that is sending or sent can no longer be edited."
}
```

## Delete a broadcast

```
DELETE /broadcasts/:broadcast_id
```

Allowed for drafts, scheduled, and sent broadcasts. A broadcast currently `sending`
cannot be deleted.

## Metrics

```
GET /broadcasts/:broadcast_id/metrics
```

```json
{
  "object": "broadcast_metrics",
  "broadcast_id": "559ac32e-9ef5-46fb-82a1-b76b840c0f7b",
  "status": "sent",
  "total": 1284,
  "sent": 1201,
  "remaining": 0,
  "delivered": { "count": 1180, "percentage": 91.9 },
  "opened": { "count": 512, "percentage": 39.87 },
  "clicked": { "count": 98, "percentage": 7.63 },
  "unsubscribed": { "count": 4, "percentage": 0.31 },
  "bounced": { "count": 21, "percentage": 1.63 },
  "complained": { "count": 1, "percentage": 0.07 },
  "suppressed": { "count": 0, "percentage": 0 },
  "clicked_links": [
    { "url": "https://acme.com/pricing", "clicks": 74, "unique_clicks": 61 }
  ]
}
```

`total` counts every contact considered, including skipped ones; `sent` counts those
actually queued. Percentages are against `total`.

`clicked_links` requires click tracking on the sending domain.

## List recipients

```
GET /broadcasts/:broadcast_id/recipients?type=clicked
```

| Parameter | Notes |
|---|---|
| `type` | **Required.** `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`, `unsubscribed`, `suppressed` |
| `limit` | Up to 100 |
| `email` | Filter to one address |
| `bounce_type` | Filter bounces by `hard` or `soft` |

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "8b9a1f2c-...",
      "contact_id": "e169aa45-...",
      "email": "reader@example.com",
      "count": 3,
      "bounce_type": null
    }
  ]
}
```

`count` is how many times that recipient produced the event — useful for spotting the
difference between one enthusiastic reader and broad engagement.



---

# Templates

> Versioned email content with typed variables and a draft/publish workflow.


# Templates

Templates keep email content out of your codebase. Each edit creates a new version;
publishing promotes one to current. Sends always use the published version, so editing a
template cannot break production mid-flight.

## Create a template

```
POST /templates
```

| Field | Type | Notes |
|---|---|---|
| `name` | `string` | **Required** |
| `html` | `string` | **Required** |
| `alias` | `string` | Stable id you can send to instead of the UUID |
| `from` | `string` | Default sender |
| `subject` | `string` | Supports variables |
| `text` | `string` | |
| `reply_to` | `string \| string[]` | |
| `variables` | `array` | `{ key, type, fallback_value }`, max 50 |

```sh
curl -X POST https://outbox.example.com/templates \
  -H "Authorization: Bearer ob_xxxxxxxxx" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-confirmation",
    "alias": "order-confirmation",
    "from": "Acme <orders@acme.com>",
    "subject": "Your order of {{{PRODUCT}}}",
    "html": "<p>Thanks! {{{PRODUCT}}} costs {{{PRICE}}}.</p>",
    "variables": [
      { "key": "PRODUCT", "type": "string", "fallback_value": "item" },
      { "key": "PRICE", "type": "number", "fallback_value": 0 }
    ]
  }'
```

```json
{ "object": "template", "id": "34a080c9-b17d-4187-ad80-5af20266e535" }
```

A newly created template is a **draft**. It cannot be sent until published.

## Variable syntax

```html
<p>Hi {{{first_name|there}}},</p>
<p>Your {{{PRODUCT}}} ships {{{ship_date}}}.</p>
<p><a href="{{{OUTBOX_UNSUBSCRIBE_URL}}}">Unsubscribe</a></p>
```

| Form | Behaviour |
|---|---|
| `{{{KEY}}}` | Inserts raw |
| `{{{KEY\|fallback}}}` | Inserts, or the fallback when missing or empty |
| `{{KEY}}` | Inserts HTML-escaped |
| `{{{contact.first_name}}}` | Dotted paths into the render context |
| `{{{OUTBOX_UNSUBSCRIBE_URL}}}` | Replaced with a signed per-recipient URL |

Resolution order: the supplied value, then the inline fallback, then the declared
variable's `fallback_value`, then empty.

Use double braces for anything a user typed. Triple braces do not escape, which is
correct for HTML fragments and wrong for a display name.

## Publish

```
POST /templates/:id/publish
```

Promotes the latest version to current and sets status to `published`.

```json
{
  "object": "template",
  "id": "34a080c9-b17d-4187-ad80-5af20266e535",
  "current_version_id": "b2693018-7abb-4b4b-b4cb-aadf72dc06bd"
}
```

Sending with an unpublished template returns:

```json
{
  "statusCode": 400,
  "name": "invalid_parameter",
  "message": "Template has no published version. Publish it before sending."
}
```

## Retrieve a template

```
GET /templates/:id
```

`:id` accepts the template id or its alias.

```json
{
  "object": "template",
  "id": "34a080c9-b17d-4187-ad80-5af20266e535",
  "current_version_id": "b2693018-7abb-4b4b-b4cb-aadf72dc06bd",
  "alias": "order-confirmation",
  "name": "order-confirmation",
  "created_at": "2026-10-06 23:47:56.678+00",
  "updated_at": "2026-10-06 23:47:56.678+00",
  "status": "published",
  "published_at": "2026-10-06 23:47:56.678+00",
  "from": "Acme <orders@acme.com>",
  "subject": "Your order of {{{PRODUCT}}}",
  "reply_to": null,
  "html": "<p>Thanks! {{{PRODUCT}}} costs {{{PRICE}}}.</p>",
  "text": null,
  "variables": [
    {
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "key": "PRODUCT",
      "type": "string",
      "fallback_value": "item",
      "created_at": "2026-10-06 23:47:56.678+00",
      "updated_at": "2026-10-06 23:47:56.678+00"
    }
  ],
  "has_unpublished_versions": false
}
```

`has_unpublished_versions` tells you an edit is waiting — useful for a "publish changes"
badge in your own tooling.

## List templates

```
GET /templates
```

Always paginated.

## Update a template

```
PATCH /templates/:id
```

`name` and `alias` change in place. Any content change — `html`, `text`, `subject`,
`from`, `reply_to`, `variables` — creates a **new draft version**. Live sends keep using
the published version until you publish again.

## Duplicate

```
POST /templates/:id/duplicate
```

Copies the current content and variables into a new template named `<name> (copy)` with
no alias.

## Delete

```
DELETE /templates/:id
```

Deletes the template and all its versions. Emails already sent keep their content.

## Sending with a template

```json
{
  "to": ["buyer@example.com"],
  "template": {
    "id": "order-confirmation",
    "variables": { "PRODUCT": "Widget", "PRICE": 42 }
  }
}
```

`from` and `subject` come from the template when you do not override them, so a send can
be as small as a recipient and a variable bag. Anything you pass explicitly wins.



---

# Suppressions

> The team do-not-send list that bounces and complaints feed automatically.


# Suppressions

The suppression list protects your sending reputation. Every send checks it per
recipient, so an address that hard-bounced once is not retried into a wall.

## How addresses land here

| `origin` | Cause |
|---|---|
| `bounce` | A permanent delivery failure. Added automatically |
| `complaint` | A spam report |
| `manual` | Added through the API or dashboard |

Automatic suppression is the important one. Repeatedly mailing addresses that hard-bounce
is one of the fastest ways to damage a sending domain, and it is entirely avoidable.

## Add a suppression

```
POST /suppressions
```

```json
{ "email": "bounced@example.com" }
```

```json
{
  "object": "suppression",
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "email": "bounced@example.com"
}
```

Adding an address that is already suppressed updates its origin rather than failing.

## Add up to 100

```
POST /suppressions/batch/add
```

```json
{ "emails": ["a@example.com", "b@example.com"] }
```

```json
{
  "object": "list",
  "data": [
    { "id": "…", "email": "a@example.com" },
    { "id": "…", "email": "b@example.com" }
  ]
}
```

Useful when importing a do-not-contact list from another provider — do that before your
first send, not after.

## Retrieve a suppression

```
GET /suppressions/:suppression
```

Accepts an id or an email address.

```json
{
  "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
  "email": "bounced@example.com",
  "origin": "bounce",
  "source_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "created_at": "2026-10-06 23:47:56.678+00"
}
```

`source_id` is the email that caused it, for `bounce` and `complaint` origins, and
`null` for manual entries. It answers "why is this address blocked" without guessing.

## List suppressions

```
GET /suppressions
GET /suppressions?origin=bounce
```

Always paginated. `origin` filters to `bounce`, `complaint`, or `manual`.

## Remove a suppression

```
DELETE /suppressions/:suppression
```

Accepts an id or an email.

## Remove up to 100

```
POST /suppressions/batch/remove
```

```json
{ "emails": ["a@example.com"], "ids": ["e169aa45-…"] }
```

Either or both keys. Returns what was actually removed.

## When to remove

Removing a `manual` entry is routine — someone asked to be re-added.

Removing a `bounce` entry deserves a reason. If the mailbox genuinely came back (a
typo'd domain now registered, a mailbox un-suspended), fine. If you are removing it
because the numbers look bad, you are choosing to re-send to an address that already
told you it does not exist, and receiving servers notice.

`complaint` entries should essentially never be removed. Someone marked your mail as
spam; mailing them again is how domains get blocklisted.

## Suppression and unsubscribe

These are different mechanisms and it is worth keeping them straight:

| | Suppression list | `unsubscribed` flag | Topic opt-out |
|---|---|---|---|
| Scope | Every email | Broadcasts only | One topic |
| Set by | Bounces, complaints, you | Contact or unsubscribe link | Contact or unsubscribe link |
| Blocks transactional | Yes | No | Only if sent with that topic |

A password reset should still reach someone who unsubscribed from marketing. It should
not reach an address that does not exist. That is the distinction.

## Events

`suppression.added` and `suppression.removed` fire to subscribed
[webhooks](/api/webhooks).



---

# Webhooks

> Event types, Svix-compatible signatures, delivery history, and retries.


# Webhooks

Webhooks push events to your endpoint as they happen, so you do not have to poll.

## Create a webhook

```
POST /webhooks
```

```json
{
  "endpoint": "https://acme.com/webhooks/outbox",
  "events": ["email.delivered", "email.bounced", "email.complained"]
}
```

```json
{
  "object": "webhook",
  "id": "4dd369bc-aa82-4ff3-97de-514ae3000ee0",
  "endpoint": "https://acme.com/webhooks/outbox",
  "events": ["email.delivered", "email.bounced", "email.complained"],
  "status": "enabled",
  "signing_secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
  "created_at": "2026-04-08 00:11:13.110779+00"
}
```

The signing secret is returned on create, retrieve, and list, so it can be fetched again
if lost.

## Event types

| Group | Events |
|---|---|
| Sending | `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.scheduled`, `email.suppressed` |
| Engagement | `email.opened`, `email.clicked` |
| Receiving | `email.received` |
| Contacts | `contact.created`, `contact.updated`, `contact.deleted` |
| Domains | `domain.created`, `domain.updated`, `domain.deleted` |
| Suppressions | `suppression.added`, `suppression.removed` |

An unknown event type is rejected at create time rather than silently ignored.

## Payload

```json
{
  "type": "email.delivered",
  "created_at": "2026-02-22T23:41:12.126Z",
  "data": {
    "email_id": "56761188-7520-42d8-8898-ff6fc54ce618",
    "message_id": "<111-222-333@acme.com>",
    "from": "Acme <onboarding@acme.com>",
    "to": ["user@example.com"],
    "subject": "Sending this example",
    "created_at": "2026-02-22T23:41:11.894Z",
    "tags": { "category": "confirm_email" }
  }
}
```

Note that `tags` arrive as an object map here, while the send API takes and returns an
array of `{ name, value }`. That asymmetry is Resend's, kept for compatibility.

`email.clicked` adds the link; `email.bounced` adds the bounce type and message.

## Verifying signatures

Outbox signs with the Svix scheme, so the standard Svix libraries verify Outbox payloads
unchanged. Every request carries both header families:

```
svix-id: msg_2XcQ8vLpNrKmT3wYbZaFhJdEgV
svix-timestamp: 1740267672
svix-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
webhook-id: msg_2XcQ8vLpNrKmT3wYbZaFhJdEgV
webhook-timestamp: 1740267672
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
```

With the Svix library:

```ts
import { Webhook } from "svix"

const wh = new Webhook(process.env.OUTBOX_WEBHOOK_SECRET!)
const event = wh.verify(rawBody, {
  "svix-id": req.headers["svix-id"],
  "svix-timestamp": req.headers["svix-timestamp"],
  "svix-signature": req.headers["svix-signature"],
})
```

Or with the Outbox SDK:

```ts
import { verifyWebhook } from "@outbox/sdk"

const event = await verifyWebhook({
  payload: rawBody,
  headers: {
    id: req.headers["svix-id"],
    timestamp: req.headers["svix-timestamp"],
    signature: req.headers["svix-signature"],
  },
  webhookSecret: process.env.OUTBOX_WEBHOOK_SECRET!,
})
```

> Verify against the **raw request body**. Parsing to JSON and re-serialising changes the
> bytes and the signature will not match. This is the single most common integration
> mistake.

The signature is HMAC-SHA256 over `${id}.${timestamp}.${body}` using the secret after
`whsec_`, Base64-decoded. Timestamps outside a five-minute window are rejected, which
blocks replay.

## Retries

Non-2xx responses and timeouts retry with exponential backoff:

```
5s → 30s → 5m → 30m → 2h → 5h → 10h → 24h
```

Eight attempts across roughly a day, then the event is marked `exhausted`. Requests time
out after 10 seconds, so acknowledge quickly and do the work asynchronously.

Your endpoint should be idempotent. A timeout after you processed the event still
retries, so the same `svix-id` can legitimately arrive twice.

## Delivery history

```
GET /webhooks/:webhook_id/events
GET /webhooks/:webhook_id/events/:event_id
GET /webhooks/:webhook_id/events/:event_id/attempts
```

Attempts record what actually happened:

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "attempt",
      "id": "9c1f…",
      "http_status_code": 500,
      "response": "Internal Server Error",
      "sent_at": "2026-02-22T23:41:12.126Z"
    }
  ]
}
```

That response body is usually enough to debug an integration without adding logging on
your side.

## Manage

```
GET    /webhooks
PATCH  /webhooks/:webhook_id
DELETE /webhooks/:webhook_id
```

`PATCH` accepts `endpoint`, `events`, and `status` (`enabled` or `disabled`). Disabling
stops delivery without losing history — better than deleting while you fix an endpoint.

## Local development

Webhooks need a publicly reachable URL. Either tunnel:

```sh
ngrok http 3000
```

Or point the webhook at a local server, since a self-hosted Outbox can reach your
machine directly:

```ts
Bun.serve({
  port: 4000,
  fetch: async (req) => {
    console.log(JSON.parse(await req.text()))
    return new Response("ok")
  },
})
```

See [Handle webhooks](/tutorials/handle-webhooks) for a complete integration.



---

# Automations

> Event-triggered workflows built as a step graph, with branching, delays, and waits.


# Automations

An automation runs a sequence of steps whenever your application sends a matching event.
Welcome series, drip campaigns, trial expiry, abandoned cart — anything shaped as "when
X happens, do these things, maybe waiting in between".

## Model

An automation is a graph of **steps** connected by **edges**.

| Step type | Behaviour |
|---|---|
| `trigger` | Entry point. Exactly one per automation |
| `condition` | Branches on `condition_met` / `condition_not_met` edges |
| `delay` | Suspends the run, resumes after a duration |
| `wait_for_event` | Suspends until a named event arrives |
| `send_email` | Sends inline content or a template |
| `add_to_segment` | Adds the contact to a segment |
| `contact_update` | Updates contact fields |
| `contact_delete` | Deletes the contact |

Edges carry a `type` of `default`, `condition_met`, or `condition_not_met`.

## Create an automation

```
POST /automations
```

```json
{
  "name": "Welcome series",
  "status": "enabled",
  "steps": [
    { "key": "start", "type": "trigger", "config": { "event_name": "user.created" } },
    {
      "key": "check_plan",
      "type": "condition",
      "config": { "type": "rule", "field": "event.plan", "operator": "eq", "value": "pro" }
    },
    { "key": "wait", "type": "delay", "config": { "duration": 1, "unit": "days" } },
    { "key": "pro_welcome", "type": "send_email", "config": { "template_id": "pro-welcome" } },
    {
      "key": "free_welcome",
      "type": "send_email",
      "config": {
        "from": "Acme <hi@acme.com>",
        "subject": "Welcome to Acme",
        "html": "<p>Hi {{{contact.first_name|there}}}!</p>"
      }
    }
  ],
  "edges": [
    { "from": "start", "to": "check_plan", "type": "default" },
    { "from": "check_plan", "to": "wait", "type": "condition_met" },
    { "from": "wait", "to": "pro_welcome", "type": "default" },
    { "from": "check_plan", "to": "free_welcome", "type": "condition_not_met" }
  ]
}
```

Validation is strict, because a broken graph fails silently at 3am otherwise:

- Exactly one `trigger` step, and it must have `config.event_name`.
- Every edge must reference steps that exist.

## Conditions

```json
{
  "type": "rule",
  "field": "event.plan",
  "operator": "eq",
  "value": "pro"
}
```

Fields read from the run context: `event.*` for the event payload, `contact.*` for
contact fields, and contact properties by name.

| Operator | Meaning |
|---|---|
| `eq`, `neq` | Equality, numeric when both sides are numbers |
| `gt`, `gte`, `lt`, `lte` | Numeric comparison |
| `contains`, `not_contains` | Substring |
| `starts_with`, `ends_with` | Substring |
| `exists`, `not_exists` | Presence and non-emptiness |

Group rules with `and` / `or`:

```json
{
  "type": "and",
  "rules": [
    { "field": "event.plan", "operator": "eq", "value": "pro" },
    { "field": "event.seats", "operator": "gte", "value": 5 }
  ]
}
```

## Delays and waits

```json
{ "key": "wait", "type": "delay", "config": { "duration": 3, "unit": "days" } }
```

Units: `seconds`, `minutes`, `hours`, `days`, `weeks`. `{ "seconds": 90 }` also works.

```json
{
  "key": "await_purchase",
  "type": "wait_for_event",
  "config": { "event_name": "order.completed", "duration": 7, "unit": "days" }
}
```

Both suspend the run rather than holding a worker, so a 30-day sequence costs nothing
while it waits. A `wait_for_event` that times out completes the run rather than
continuing down the graph.

## Trigger a run

```
POST /events/send
```

```json
{
  "name": "user.created",
  "email": "new@example.com",
  "data": { "plan": "pro", "seats": 12 }
}
```

Pass `email` or `contact_id`. Anything in `data` is available to conditions and templates
as `event.*`.

```json
{ "object": "event", "id": "5f8c…", "name": "user.created" }
```

Every enabled automation whose trigger matches starts a run. The same call also resumes
any run parked on `wait_for_event` for that name.

## Inspect runs

```
GET /automations/:automation_id/runs
GET /automations/:automation_id/runs/:run_id
```

```json
{
  "object": "automation_run",
  "id": "b0f1…",
  "contact_id": "e169aa45-…",
  "email": "new@example.com",
  "status": "completed",
  "current_step_key": null,
  "context": { "event": { "plan": "pro" }, "event_name": "user.created" },
  "started_at": "2026-08-10 13:37:47.113+00",
  "completed_at": "2026-08-10 13:37:49.882+00",
  "error": null,
  "steps": [
    { "key": "start", "type": "trigger", "status": "completed", "error": null },
    { "key": "check_plan", "type": "condition", "status": "completed", "result": { "met": true } },
    { "key": "pro_welcome", "type": "send_email", "status": "completed", "result": { "email_id": "…" } }
  ]
}
```

Run statuses: `running`, `waiting`, `completed`, `failed`, `canceled`. The step list is
the debugging tool — it shows exactly which branch was taken and why.

## Custom events

```
GET  /automations/events
POST /automations/events
```

Registering an event name up front makes it available in the dashboard picker. Sending
an unregistered name still works and registers it automatically.

## Manage

```
GET    /automations
GET    /automations/:automation_id
PATCH  /automations/:automation_id
DELETE /automations/:automation_id
```

`PATCH` accepts `name`, `description`, `status`, and a full `steps`/`edges` replacement.
Supplying steps rewrites the whole graph.

New automations default to `disabled` — enable one deliberately, after checking the
graph, rather than discovering it live.

See [Build a welcome automation](/tutorials/welcome-automation) for a worked example.



---

# Metrics

> Aggregate email and segment metrics with configurable granularity and dimensions.


# Metrics

## Email metrics

```
GET /emails/metrics
```

Aggregates over `email_events`, so it reflects the same data the dashboard charts.

### Parameters

| Parameter | Notes |
|---|---|
| `start_date` | ISO 8601. Defaults to 30 days ago |
| `end_date` | ISO 8601. Defaults to now |
| `granularity` | `hourly`, `daily` (default), `weekly`, `monthly` |
| `timezone` | IANA name for bucket boundaries. Default `UTC` |
| `metrics` | Comma-separated. See below |
| `dimensions` | Comma-separated: `period`, `domain`, `email` |
| `domain_id` | Comma-separated filter |
| `email_id` | Comma-separated filter |
| `sort_by` | A metric or dimension name |
| `sort_order` | `asc` or `desc` |

### Available metrics

Counts: `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`,
`delivery_delayed`, `failed`, `canceled`, `suppressed`.

Rates, returned as percentages: `delivery_rate`, `open_rate`, `click_rate`,
`bounce_rate`, `complaint_rate`.

| Rate | Computed as |
|---|---|
| `delivery_rate` | delivered ÷ sent |
| `open_rate` | opened ÷ delivered |
| `click_rate` | clicked ÷ delivered |
| `bounce_rate` | bounced ÷ sent |
| `complaint_rate` | complained ÷ delivered |

Open and click rates use *delivered* as the denominator, not sent — a message that never
arrived cannot be opened, and dividing by sent understates engagement.

### Example

```sh
curl "https://outbox.example.com/emails/metrics?start_date=2026-07-01&end_date=2026-07-08&granularity=daily&dimensions=period&metrics=sent,delivered,open_rate" \
  -H "Authorization: Bearer ob_xxxxxxxxx" -H "User-Agent: my-app/1.0"
```

```json
{
  "object": "list",
  "data": [
    { "period": "2026-07-01T00:00:00.000Z", "sent": 1204, "delivered": 1180, "open_rate": 43.39 },
    { "period": "2026-07-02T00:00:00.000Z", "sent": 998, "delivered": 981, "open_rate": 41.08 }
  ],
  "start_date": "2026-07-01T00:00:00.000Z",
  "end_date": "2026-07-08T00:00:00.000Z",
  "granularity": "daily"
}
```

Without `dimensions` you get a single bucket covering the whole range — useful for a
headline number.

Combine dimensions to slice:

```
?dimensions=period,domain&metrics=sent,bounce_rate
```

### Counting

Counts are **distinct emails**, not raw events. One recipient opening the same message
five times counts once toward `opened`. Per-recipient counts live in
[broadcast recipients](/api/broadcasts#list-recipients).

### On open tracking

Open rates are directionally useful and precisely wrong. Apple Mail Privacy Protection
pre-fetches images, inflating opens; clients that block images suppress them entirely.
Outbox drops obvious bot and proxy user-agents, which helps but does not fix it.

Trust clicks. Watch opens as a trend, not a number.

## Segment metrics

```
GET /segments/metrics
```

| Parameter | Notes |
|---|---|
| `segment_id` | Comma-separated filter |
| `sort_by`, `sort_order` | |

```json
{
  "object": "list",
  "data": [
    {
      "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "name": "Registered Users",
      "all_contacts": 1284,
      "subscribed_contacts": 1201,
      "unsubscribed_contacts": 83
    }
  ]
}
```

## Dashboard summary

```
GET /dashboard/summary
```

Session-authenticated rather than key-authenticated — it backs the dashboard's own
counters. Returns totals for emails, contacts, domains, broadcasts, templates, segments,
suppressions, webhooks, automations, API keys, and pending jobs.

`queued_jobs` is the one to watch operationally. If it climbs and does not fall, no
worker is running.



---

# Logs

> Every API request, with its body and response, for debugging integrations.


# Logs

Outbox records every API request your team makes — method, path, status, user agent, IP,
duration, and both bodies. When an integration misbehaves this is usually the fastest way
to find out what was actually sent, rather than what you believe was sent.

## List logs

```
GET /logs
```

Always paginated. Newest first.

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "log",
      "id": "37e4414c-5e25-4dbc-a071-43552a4bd53b",
      "created_at": "2026-03-30 13:43:54.622865+00",
      "endpoint": "/emails",
      "method": "POST",
      "response_status": 200,
      "user_agent": "resend-node:6.18.1"
    }
  ]
}
```

## Retrieve a log

```
GET /logs/:log_id
```

Adds the request and response bodies:

```json
{
  "object": "log",
  "id": "37e4414c-5e25-4dbc-a071-43552a4bd53b",
  "created_at": "2026-03-30 13:43:54.622865+00",
  "endpoint": "/emails",
  "method": "POST",
  "response_status": 422,
  "user_agent": "resend-node:6.18.1",
  "request_body": {
    "from": "Acme <onboarding@acme.com>",
    "to": ["user@example.com"]
  },
  "response_body": {
    "statusCode": 422,
    "name": "missing_required_field",
    "message": "Missing `subject` field."
  }
}
```

## What gets logged

Every authenticated API request, plus unauthenticated attempts against API paths, which
is how you spot a deploy still carrying a deleted key.

Not logged: the dashboard's own calls, tracking pixel and click redirects, unsubscribe
pages, and `/health`. Those would drown the useful entries.

## Privacy

Request bodies are stored verbatim, which means **message content, recipient addresses,
and Base64 attachments are in this table**. That is what makes it useful for debugging
and what makes it sensitive.

Two consequences worth acting on:

1. It grows quickly when you send attachments. Prune it.
2. It is a copy of your customers' mail. Treat access to it, and to database backups,
   accordingly.

API keys are never logged — authorization headers are not recorded at all.

## Retention

Nothing prunes automatically; retention is your policy. A reasonable default:

```sql
DELETE FROM api_logs WHERE created_at < now() - interval '30 days';
```

Run it from cron. If you send large attachments, consider seven days, or strip bodies
older than a few days while keeping the metadata:

```sql
UPDATE api_logs
SET request_body = NULL, response_body = NULL
WHERE created_at < now() - interval '7 days'
  AND request_body IS NOT NULL;
```

## Debugging with logs

A few patterns that come up:

**"The email never arrived."** Find the request, confirm it returned 200 and an id, then
look at the email's `last_event`. A 200 means Outbox accepted it — delivery is a separate
question answered by events and webhooks.

**"We're getting 422s."** The response body names the exact field. Compare
`request_body` against what your code believes it sends; the difference is usually a
camelCase key that never got converted.

**"Something is still using the old key."** Filter by user agent and watch for 403s after
you delete a key.



---

# Pagination

> Cursor pagination, the list envelope, and how to walk a full result set.


# Pagination

List endpoints return a consistent envelope and page with cursors rather than offsets, so
results stay stable while records are being created and deleted underneath you.

## The envelope

```json
{
  "object": "list",
  "has_more": true,
  "data": [ /* … */ ]
}
```

| Field | Meaning |
|---|---|
| `object` | Always `list` |
| `has_more` | Whether more items exist beyond this page |
| `data` | The items |

## Parameters

| Parameter | Notes |
|---|---|
| `limit` | 1–100. Default 20 |
| `after` | Cursor. Returns the page **starting after** this id |
| `before` | Cursor. Returns the page **ending before** this id |

Cursors are resource ids and are **exclusive** — the item you name is never in the
result. Passing both `after` and `before` is an error:

```json
{
  "statusCode": 400,
  "name": "invalid_parameter",
  "message": "You can only use either `after` or `before`, not both simultaneously."
}
```

An id that does not exist is also an error, rather than silently returning page one:

```json
{
  "statusCode": 400,
  "name": "invalid_parameter",
  "message": "The provided pagination cursor does not exist."
}
```

## Always vs optionally paginated

Endpoints added later always paginate. Older ones return everything when you omit
`limit`, matching Resend's behaviour.

| Always paginated | Optional |
|---|---|
| `/emails`, `/templates`, `/topics`, `/suppressions`, `/logs`, `/automations`, `/webhooks/:id/events` | `/domains`, `/api-keys`, `/broadcasts`, `/segments`, `/contacts`, `/contact-properties`, `/webhooks`, `/emails/receiving` |

Relying on the unbounded form is fine for a few hundred rows and a bad idea for a
hundred thousand. Pass `limit` and page.

## Walking forward

```ts
const all = []
let after: string | undefined

for (;;) {
  const url = new URL("https://outbox.example.com/emails")
  url.searchParams.set("limit", "100")
  if (after) url.searchParams.set("after", after)

  const res = await fetch(url, {
    headers: { authorization: `Bearer ${key}`, "user-agent": "my-app/1.0" },
  })
  const page = await res.json()

  all.push(...page.data)
  if (!page.has_more) break
  after = page.data[page.data.length - 1].id
}
```

The cursor is the id of the **last** item on the page you just received.

## Walking backward

`before` takes the id of the **first** item on your current page and returns the page
before it:

```ts
const previous = await fetch(
  `https://outbox.example.com/emails?limit=25&before=${page.data[0].id}`,
  { headers: { authorization: `Bearer ${key}`, "user-agent": "my-app/1.0" } },
)
```

## Ordering

Lists are newest first, ordered by `(created_at, id)`. The compound key matters: rows
created in the same millisecond still have a deterministic order, so paging never skips
or repeats an item.

The comparison happens inside the database rather than by round-tripping a timestamp
through the client, because Postgres stores microseconds and most languages' date types
do not — truncating would leave the cursor row inside its own range.

## Filters

Some endpoints add filters that combine with pagination:

| Endpoint | Filter |
|---|---|
| `/contacts` | `segment_id` |
| `/suppressions` | `origin` |
| `/broadcasts/:id/recipients` | `type` (required), `email`, `bounce_type` |
| `/emails/metrics` | `domain_id`, `email_id` |

## Rate limits while paging

Paging a large set can outrun the 10 requests per second limit. Handle 429 by honouring
`retry-after`:

```ts
if (res.status === 429) {
  await new Promise((r) => setTimeout(r, Number(res.headers.get("retry-after") ?? 1) * 1000))
  continue
}
```

Larger pages beat faster requests — `limit=100` costs the same one request as `limit=20`.



---

# Errors

> The error envelope and every error name Outbox returns.


# Errors

Every error uses the same envelope:

```json
{
  "statusCode": 422,
  "name": "missing_required_field",
  "message": "Missing `subject` field."
}
```

Switch on `name`. It is the stable machine-readable slug; `message` is written for humans
and may change.

## Reference

### 400

| `name` | Cause |
|---|---|
| `validation_error` | The request body failed schema validation |
| `invalid_parameter` | A parameter had an unacceptable value |
| `invalid_idempotency_key` | The key was empty or longer than 256 characters |
| `invalid_idempotent_request` | The same idempotency key was reused with a different body |

### 401

| `name` | Cause |
|---|---|
| `missing_api_key` | No `Authorization` header |
| `restricted_api_key` | A `sending_access` key called a non-send endpoint |
| `invalid_access` | A dashboard endpoint was called without a session |

### 403

| `name` | Cause |
|---|---|
| `invalid_api_key` | The key does not exist, or is domain-restricted and was used elsewhere |
| `invalid_user_agent` | No `User-Agent` header |
| `invalid_from_address` | `from` is malformed, its domain is unverified, or sending is disabled for it |

### 404

| `name` | Cause |
|---|---|
| `not_found` | The resource, or the endpoint, does not exist |

### 409

| `name` | Cause |
|---|---|
| `concurrent_idempotent_requests` | The original request with this key is still in flight |
| `invalid_parameter` | A uniqueness constraint was violated — a duplicate |

### 422

| `name` | Cause |
|---|---|
| `missing_required_field` | A required field was absent |
| `validation_error` | The body did not match the expected shape |
| `invalid_attachment` | Missing content, a blocked extension, or over the size limit |
| `invalid_access` | The operation is not permitted on this resource |

### 429

| `name` | Cause |
|---|---|
| `rate_limit_exceeded` | More than `RATE_LIMIT_PER_SECOND` requests in a second |

### 5xx

| `name` | Cause |
|---|---|
| `application_error` | An unhandled server error. Check the server log |

## Handling them

```ts
const res = await fetch(`${base}/emails`, { method: "POST", headers, body })

if (!res.ok) {
  const error = await res.json()

  switch (error.name) {
    case "rate_limit_exceeded": {
      const wait = Number(res.headers.get("retry-after") ?? 1) * 1000
      await new Promise((r) => setTimeout(r, wait))
      return retry()
    }
    case "invalid_from_address":
      // Not retryable — verify the domain first.
      throw new Error(error.message)
    case "missing_required_field":
    case "validation_error":
      // A bug in the caller. Do not retry.
      throw new Error(error.message)
    default:
      if (res.status >= 500) return retryWithBackoff()
      throw new Error(error.message)
  }
}
```

### What to retry

| Retry | Do not retry |
|---|---|
| `429` — after `retry-after` | `4xx` validation and auth errors |
| `5xx` — with backoff | `invalid_from_address` |
| Network timeouts — with an idempotency key | `restricted_api_key` |

Always use an [idempotency key](/api/emails#idempotency) when retrying a send. A timeout
does not tell you whether the message was accepted, and retrying without one is how
people send the same receipt twice.

## Common mistakes

**403 `invalid_user_agent`** — you cleared the header. Set it to something identifying
your application.

**403 `invalid_from_address` in production but not locally** — locally you were on the
`console` transport, which skips the domain check. Verify the domain.

**422 `validation_error` with an SDK** — usually a camelCase key that reached the wire
unconverted. Check `request_body` in the [logs](/api/logs).

**409 `concurrent_idempotent_requests`** — two identical requests raced. Wait and retry;
the first will have completed.



---

# SDKs

> Use the official Resend SDKs against Outbox, or the bundled zero-dependency client.


# SDKs

## Use a Resend SDK

Outbox implements the Resend API, so every official Resend SDK works against it. Change
the base URL and nothing else.

### JavaScript / TypeScript

```ts
import { Resend } from "resend"

const resend = new Resend(process.env.OUTBOX_API_KEY, {
  baseUrl: "https://outbox.example.com",
})

const { data, error } = await resend.emails.send({
  from: "Acme <onboarding@acme.com>",
  to: ["user@example.com"],
  subject: "Hello World",
  html: "<strong>It works!</strong>",
})
```

This is verified rather than asserted: the repo's `bun run test:compat` runs the official
`resend` package against a live Outbox and checks sends, retrieval, listing, scheduling,
cancellation, batching, audiences, contacts, API keys, and error shapes.

### Python

```python
import resend

resend.api_key = os.environ["OUTBOX_API_KEY"]
resend.api_url = "https://outbox.example.com"

resend.Emails.send({
    "from": "Acme <onboarding@acme.com>",
    "to": ["user@example.com"],
    "subject": "Hello World",
    "html": "<strong>It works!</strong>",
})
```

### Ruby

```ruby
Resend.api_key = ENV["OUTBOX_API_KEY"]
Resend.base_url = "https://outbox.example.com"

Resend::Emails.send({
  from: "Acme <onboarding@acme.com>",
  to: ["user@example.com"],
  subject: "Hello World",
  html: "<strong>It works!</strong>"
})
```

### Go, PHP, Rust, Java, .NET, Elixir

Each exposes a base URL or client option. Set it to your Outbox host; the request and
response shapes are identical.

### SMTP

Not currently supported. Outbox speaks SMTP outbound and inbound, but does not accept
submission over SMTP — use the HTTP API.

## The bundled client

`@outbox/sdk` ships in the repo. Zero dependencies, functional, and it accepts keys in
either camelCase or snake_case.

```ts
import { createClient } from "@outbox/sdk"

const outbox = createClient({
  apiKey: process.env.OUTBOX_API_KEY!,
  baseUrl: "https://outbox.example.com",
})

const { data, error } = await outbox.emails.send({
  from: "Acme <onboarding@acme.com>",
  to: ["user@example.com"],
  subject: "Hello World",
  html: "<strong>It works!</strong>",
})
```

It returns `{ data, error }` rather than throwing, matching the Resend SDK's ergonomics:

```ts
if (error) {
  console.error(error.name, error.message)
} else {
  console.log(error === null && data.id)
}
```

### Surface

```ts
outbox.emails.send / get / list / update / cancel
outbox.emails.attachments.list / get
outbox.emails.received.list / get
outbox.emails.metrics
outbox.batch.send
outbox.domains.create / get / list / update / verify / remove
outbox.apiKeys.create / list / remove
outbox.segments.create / get / list / remove / contacts / metrics
outbox.audiences.create / get / list / remove
outbox.contacts.create / get / list / update / remove
outbox.contacts.topics.list / update
outbox.contacts.segments.list / add / remove
outbox.contactProperties.create / get / list / update / remove
outbox.topics.create / get / list / update / remove
outbox.broadcasts.create / get / list / update / send / remove / metrics / recipients
outbox.templates.create / get / list / update / publish / duplicate / remove
outbox.suppressions.add / get / list / remove
outbox.suppressions.batch.add / remove
outbox.webhooks.create / get / list / update / remove / verify
outbox.webhooks.events.list / get / attempts
outbox.automations.create / get / list / update / remove / runs / run
outbox.events.send
outbox.logs.list / get
```

### Idempotency

```ts
await outbox.emails.send(
  { from: "…", to: ["…"], subject: "…", html: "…" },
  { idempotencyKey: `order-${orderId}-confirmation` },
)
```

### Verifying webhooks

```ts
import { verifyWebhook } from "@outbox/sdk"

const event = await verifyWebhook({
  payload: rawBody,
  headers: {
    id: req.headers["svix-id"],
    timestamp: req.headers["svix-timestamp"],
    signature: req.headers["svix-signature"],
  },
  webhookSecret: process.env.OUTBOX_WEBHOOK_SECRET!,
})
```

Throws on a bad signature, a missing header, or a timestamp outside the five-minute
window. Uses Web Crypto, so it runs in Node, Bun, Deno, Cloudflare Workers, and the
browser — though not the browser, please.

Pass the **raw body**. Re-serialising parsed JSON changes the bytes and verification will
fail.

## Direct HTTP

There is nothing unusual about the API — bearer token, JSON, and a `User-Agent`:

```sh
curl -X POST https://outbox.example.com/emails \
  -H "Authorization: Bearer $OUTBOX_API_KEY" \
  -H "User-Agent: my-app/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@acme.com>",
    "to": ["user@example.com"],
    "subject": "Hello World",
    "html": "<strong>It works!</strong>"
  }'
```