# Delivrie

> Delivrie is an email API for developers: send transactional and marketing email from your own domain, receive replies, and get delivery events as webhooks. REST API at https://delivrie.io/api (Bearer API keys), an official Node.js/TypeScript SDK (`npm install delivrie`), an SMTP relay at smtp.delivrie.io, and a remote MCP server at https://delivrie.io/api/mcp. The API matches Resend's request and response shapes.

Key facts: send with POST https://delivrie.io/api/emails and `Authorization: Bearer $DELIVRIE_API_KEY`, JSON `{ from, to, subject, html | text }`. `from` must be on a verified domain (or onboarding@delivrie.io for tests to your team and *@test.delivrie.io). Errors are JSON `{ statusCode, name, message }`. Send an Idempotency-Key header so retries never double-send. Never call the API from browser code.


---



---

# Introduction

What Delivrie is, how the API works, and where to start: base URL, authentication, SDKs, SMTP and the MCP server.

Delivrie is an email platform for developers. Send transactional email (receipts, sign-in codes, password resets) and marketing email (broadcasts, automations) from your own domain, receive replies in an inbox, and get every delivery event as a webhook.

You can reach Delivrie four ways. They all share the same account, limits, logs and webhooks.

| Way in | Use it when | Start here |
| --- | --- | --- |
| REST API | You're writing code in any language | [Quickstart](/docs/quickstart) |
| Node.js SDK | You're on Node.js, Bun, Deno, Workers or Vercel Edge | [Node.js SDK](/docs/sdks) |
| SMTP relay | A framework, CMS or plugin already sends email over SMTP | [SMTP](/docs/smtp) |
| MCP server | An AI assistant should send email or manage your account | [MCP server](/docs/mcp) |

## The API in one minute

- **Base URL:** `https://delivrie.io/api`
- **Authentication:** send your API key in the `Authorization` header: `Authorization: Bearer dlv_your_key`. Create keys in the dashboard under [API keys](https://delivrie.io/api-keys).
- **Format:** JSON in, JSON out. Send `Content-Type: application/json` on requests with a body.
- **Errors:** every error is JSON with `statusCode`, `name` and `message`. See [Errors](/docs/errors).
- **Lists:** list endpoints return `{ "object": "list", "data": [...] }` and take `limit` (1 to 100, default 50) and `offset`. When `has_more` is `true`, ask for the next page with a higher `offset`.
- **Safe retries:** send an `Idempotency-Key` header with every email send. See [Idempotency and retries](/docs/idempotency).
- **Server side only:** never call the API from browser code; your key would be visible to anyone. See [CORS](/docs/cors).

```bash cURL
curl -X POST https://delivrie.io/api/emails \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <onboarding@delivrie.io>",
    "to": "delivered@test.delivrie.io",
    "subject": "Hello from Delivrie",
    "html": "<p>It works!</p>"
  }'
```

```ts Node.js
import { Delivrie } from "delivrie";

const delivrie = new Delivrie(process.env.DELIVRIE_API_KEY);
const { data, error } = await delivrie.emails.send({
  from: "Acme <onboarding@delivrie.io>",
  to: "delivered@test.delivrie.io",
  subject: "Hello from Delivrie",
  html: "<p>It works!</p>",
});
```

```python Python
import os, requests

res = requests.post(
    "https://delivrie.io/api/emails",
    headers={"Authorization": f"Bearer {os.environ['DELIVRIE_API_KEY']}"},
    json={
        "from": "Acme <onboarding@delivrie.io>",
        "to": "delivered@test.delivrie.io",
        "subject": "Hello from Delivrie",
        "html": "<p>It works!</p>",
    },
)
print(res.status_code, res.json())
```

`onboarding@delivrie.io` is a shared sender for testing: it can email the [test addresses](/docs/test-mode) and the people on your team. To email anyone else, [verify your own domain](/docs/domains) and send from it.

The response is `{ "id": "<email id>" }`. Delivery happens in the background; follow it in the dashboard under Emails, with `GET /emails/:id`, or with [webhooks](/docs/webhooks).

## Building with an AI coding assistant?

Point it at [delivrie.io/llms.txt](https://delivrie.io/llms.txt). It lists every guide and endpoint as plain Markdown, so Claude, Cursor, Codex, v0 and other tools read the docs directly. [Build with AI](/docs/build-with-ai) has prompts you can paste and a rules file for your project.

## Coming from Resend?

The API uses the same request and response shapes, so most code keeps working. See [Migrate from Resend](/docs/migrate-from-resend).


---

# Quickstart

Send your first email in five minutes: create an account and API key, test with the shared sender, then verify your own domain.

This takes about five minutes. You'll send a test email right away, then set up your own domain so you can email anyone.

## 1. Create an account

Sign up at [delivrie.io/signup](https://delivrie.io/signup). The Free plan includes 4,000 emails a month (up to 133 a day), so you don't need a card.

## 2. Create an API key

Open [API keys](https://delivrie.io/api-keys) in the dashboard and click **Create API key**.

- **Full access** keys can call every endpoint. Use them for scripts and back-office tools.
- **Sending access** keys can only send email, optionally from one domain. Use them in production apps.

Keys start with `dlv_` and are shown once. Store the key in an environment variable, never in your code:

```bash .env
DELIVRIE_API_KEY=dlv_your_key
```

## 3. Send a test email

You can send before you verify a domain. Use the shared sender `onboarding@delivrie.io` as the `from` address, and send to either:

- the **test addresses** `delivered@test.delivrie.io`, `bounced@test.delivrie.io` and `complained@test.delivrie.io`. They behave like real inboxes and fire real events. See [Test addresses](/docs/test-mode).
- **yourself and your teammates**: the email addresses of people on your Delivrie team.

```bash cURL
curl -X POST https://delivrie.io/api/emails \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-1" \
  -d '{
    "from": "Acme <onboarding@delivrie.io>",
    "to": "delivered@test.delivrie.io",
    "subject": "My first Delivrie email",
    "html": "<h1>It works</h1><p>Sent with Delivrie.</p>"
  }'
```

```ts Node.js
// npm install delivrie
import { Delivrie } from "delivrie";

const delivrie = new Delivrie(process.env.DELIVRIE_API_KEY);

const { data, error } = await delivrie.emails.send(
  {
    from: "Acme <onboarding@delivrie.io>",
    to: "delivered@test.delivrie.io",
    subject: "My first Delivrie email",
    html: "<h1>It works</h1><p>Sent with Delivrie.</p>",
  },
  { idempotencyKey: "quickstart-1" },
);

if (error) throw new Error(`${error.name}: ${error.message}`);
console.log("Sent", data.id);
```

```python Python
import os, requests

res = requests.post(
    "https://delivrie.io/api/emails",
    headers={
        "Authorization": f"Bearer {os.environ['DELIVRIE_API_KEY']}",
        "Idempotency-Key": "quickstart-1",
    },
    json={
        "from": "Acme <onboarding@delivrie.io>",
        "to": "delivered@test.delivrie.io",
        "subject": "My first Delivrie email",
        "html": "<h1>It works</h1><p>Sent with Delivrie.</p>",
    },
)
res.raise_for_status()
print("Sent", res.json()["id"])
```

A successful send returns `200` with `{ "id": "..." }`. Open [Emails](https://delivrie.io/emails) in the dashboard to watch it move from queued to sent to delivered.

> **Note:** If you get `422 validation_error`, read the `message`. It says exactly what's wrong, for example a missing field or a `from` domain that isn't verified yet.

## 4. Verify your domain

To send to anyone, add a domain you own.

1. Open [Domains](https://delivrie.io/domains/new) and add a subdomain such as `mail.acme.com`. A subdomain keeps your main domain's reputation separate from your app's email.
2. Add the DNS records Delivrie shows you at your DNS provider: a DKIM `TXT` record, and an `MX` and `TXT` record on the `send` subdomain for SPF and bounces.
3. Click **Verify DNS records**. Most providers update within minutes.

Then send from any address on that domain, like `orders@mail.acme.com`, to anyone. [Domains and DNS](/docs/domains) explains each record, and [Why isn't my domain verifying?](/docs/domain-not-verifying) covers the usual fixes.

## 5. Next steps

- Track deliveries, bounces and opens with [webhooks](/docs/webhooks).
- Reuse designs with [templates](/docs/templates).
- Find your framework under SDKs and frameworks: [Next.js](/docs/nextjs), [Express](/docs/express), [Python](/docs/python), [PHP and Laravel](/docs/php), [Ruby and Rails](/docs/ruby), [Go](/docs/go), [Rust](/docs/rust), [Supabase](/docs/supabase), [Cloudflare Workers](/docs/cloudflare-workers).
- Before you go live, read the [Deliverability guide](/docs/deliverability).


---

# Build with AI

Use Delivrie with Claude, Cursor, Codex, v0, Lovable, Bolt and other AI tools: llms.txt, Markdown docs, a rules file for your repo, prompts to paste and the MCP server.

AI coding tools write better email code when they read the right docs. Delivrie publishes everything in formats they understand, and gives your assistant a way to act on your account directly.

## Give your assistant the docs

| URL | What it is |
| --- | --- |
| [delivrie.io/llms.txt](https://delivrie.io/llms.txt) | An index of every guide and API endpoint, with links to Markdown versions |
| [delivrie.io/llms-full.txt](https://delivrie.io/llms-full.txt) | All guides and the full API reference in one Markdown file |
| `https://delivrie.io/docs/<page>.md` | Any docs page as Markdown, for example [/docs/quickstart.md](https://delivrie.io/docs/quickstart.md) or [/docs/api/send-email.md](https://delivrie.io/docs/api/send-email.md) |

Every docs page also has **Copy page** (Markdown for your clipboard) and **Open in Claude** buttons.

In Cursor, add `https://delivrie.io/llms-full.txt` under **Settings → Indexing & Docs → Add Doc**, then type `@Docs` in chat and pick Delivrie. In Claude, ChatGPT or v0, paste the link into your message and ask the assistant to read it.

## Add a rules file to your project

Assistants follow project rules on every request. Save this as `AGENTS.md` (Codex, Cursor, Copilot, Jules and most agents), `CLAUDE.md` (Claude Code) or `.cursor/rules/delivrie.mdc` (Cursor):

```markdown AGENTS.md
## Email: Delivrie

- Send email with Delivrie. Docs: https://delivrie.io/llms.txt (Markdown: append .md to any docs URL).
- Node/TypeScript: use the `delivrie` npm package. `new Delivrie(process.env.DELIVRIE_API_KEY)`.
  Calls return `{ data, error }` and never throw for API errors: always check `error`.
- Other languages: POST https://delivrie.io/api/emails with `Authorization: Bearer $DELIVRIE_API_KEY`
  and JSON `{ from, to, subject, html | text }`.
- Read the key from the DELIVRIE_API_KEY environment variable. Never hard-code it and never call
  Delivrie from browser code: send from a server route, server action or edge function.
- `from` must be on a verified domain, as "Name <address@domain>". Ours is: mail.example.com
- Pass an idempotency key derived from the business event (e.g. `order-${order.id}-receipt`)
  so retries never send twice.
- In tests and local development, send to delivered@test.delivrie.io (or bounced@ / complained@).
- Delivery results arrive as signed webhooks (Standard Webhooks). Verify with `verifyWebhook`
  from the `delivrie` package before trusting a payload.
```

Change `mail.example.com` to your verified domain.

## Prompts to paste

Start a new chat with one of these, filling in the brackets.

```text Add email
Add transactional email to this app with Delivrie (https://delivrie.io/llms-full.txt).
Send a [welcome email] when [a user signs up]. Use the `delivrie` npm package
(or plain fetch to https://delivrie.io/api/emails if this isn't a JS project),
read DELIVRIE_API_KEY from the environment, send only from server code,
use "[App name] <[hello@mail.example.com]>" as the sender, and pass an
idempotency key based on the user id. Show me where to add the env var.
```

```text Webhooks
Using Delivrie webhooks (https://delivrie.io/docs/webhooks.md), add an endpoint at
[/api/webhooks/delivrie] that verifies the signature with `verifyWebhook` from the
`delivrie` package using DELIVRIE_WEBHOOK_SECRET, reads the raw request body before
parsing it, and [marks the user's email as invalid] on email.bounced and
email.complained. Return 200 quickly and 400 when the signature is wrong.
```

```text Migrate
Migrate this project from Resend to Delivrie following
https://delivrie.io/docs/migrate-from-resend.md. Keep behaviour the same,
change only what the guide says, and list the environment variables I need to set.
```

```text v0 / Lovable / Bolt
Add a contact form that emails me through Delivrie. Create a server route
(never call Delivrie from the browser) that POSTs to https://delivrie.io/api/emails
with Authorization: Bearer ${DELIVRIE_API_KEY}, from "[Site] <[forms@mail.example.com]>",
to "[me@example.com]", reply_to the visitor's email, and the message as text.
Show a success state, and an error state using the API's error message.
```

## Let the assistant use your account (MCP)

The [MCP server](/docs/mcp) at `https://delivrie.io/api/mcp` gives assistants 64 tools: send email, check delivery, add domains, manage contacts, broadcasts and templates, read logs and reply to inbox threads. You approve which team and scopes it can use, and you can revoke it under Settings → Connected apps.

```bash Claude Code
claude mcp add --transport http delivrie https://delivrie.io/api/mcp
```

```json Cursor
// ~/.cursor/mcp.json
{
  "mcpServers": {
    "delivrie": { "url": "https://delivrie.io/api/mcp" }
  }
}
```

```toml Codex
# ~/.codex/config.toml
[mcp_servers.delivrie]
command = "npx"
args = ["-y", "mcp-remote", "https://delivrie.io/api/mcp"]
```

```text v0
v0 → Settings → MCP connections → Add custom connection
Name     Delivrie
URL      https://delivrie.io/api/mcp
Header   Authorization: Bearer dlv_your_key
```

Then ask things like "Send a test email to delivered@test.delivrie.io from onboarding@delivrie.io", "Why did my last email to ada@example.com bounce?" or "Add mail.example.com and tell me which DNS records to create". [MCP server](/docs/mcp) has setup for Claude Desktop, ChatGPT, Antigravity and VS Code, plus the full tool list.

## Check your assistant's work

AI-written email code usually fails in one of these ways:

- **The key is in client code.** Search the project for `dlv_` and for `delivrie.io/api` in files that run in the browser. Move those calls to the server.
- **Errors are ignored.** With the SDK, check `error` on every call. With `fetch`, check `res.ok`; the body's `message` explains the problem.
- **No idempotency key,** so a retried request sends the email twice.
- **Webhook body parsed before verification.** Signature checks need the raw body exactly as received.
- **Unverified sender.** `from` must use a domain verified in your Delivrie team, or `onboarding@delivrie.io` while testing.


---

# Migrate from Resend

Move from Resend to Delivrie without rewriting your app: same request shapes, point the Resend SDK at Delivrie with one environment variable, or switch to the delivrie package.

Delivrie's API uses the same endpoints, field names and response shapes as Resend's, so most apps switch by changing two environment variables. Plan for about 30 minutes, most of it waiting for DNS.

## 1. Add your domain to Delivrie

Add the same sending domain in [Domains](https://delivrie.io/domains/new). Delivrie gives you a new DKIM record (its own selector, so it sits next to Resend's without conflict) and SPF records for a bounce subdomain.

> **Important:** Resend and Delivrie both use the `send` subdomain for bounces by default, and a name can only have one SPF record. To keep Resend working while you switch, set a different bounce subdomain when you add the domain: in the dashboard under **Advanced options**, or with `"return_path": "bounces"` in [`POST /domains`](/docs/api/create-domain). You can remove Resend's records after the switch.

Leave out `region` when you create the domain, or use `eu-west-1`. Other regions aren't available yet.

## 2. Create a Delivrie API key

Create one in [API keys](https://delivrie.io/api-keys). Delivrie keys start with `dlv_`. `full_access` and `sending_access` work the same way as in Resend.

## 3. Point your code at Delivrie

### Option A: keep the Resend SDK

The official Resend SDKs can send to another API address. Set two environment variables and redeploy:

| SDK | Set these |
| --- | --- |
| Node.js (`resend`) | `RESEND_BASE_URL=https://delivrie.io/api` and `RESEND_API_KEY=dlv_...` |
| Python (`resend`) | `RESEND_API_URL=https://delivrie.io/api` and `RESEND_API_KEY=dlv_...` |
| PHP (`resend/resend-php`, Laravel) | `RESEND_BASE_URL=https://delivrie.io/api` and `RESEND_API_KEY=dlv_...` |
| Go (`resend-go`) | `RESEND_BASE_URL=https://delivrie.io/api/` (keep the trailing slash) |

No code changes. `resend.emails.send`, `resend.batch.send`, `resend.emails.get`, scheduling, tags and idempotency keys behave the same. The Node SDK's `react` option keeps working too, because the SDK turns your React Email component into HTML before sending.

### Option B: switch to the Delivrie SDK (Node.js)

```bash
npm uninstall resend && npm install delivrie
```

```ts Before (Resend)
import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);
const { data, error } = await resend.emails.send({
  from: "Acme <hello@mail.acme.com>",
  to: ["ada@example.com"],
  subject: "Welcome",
  html: "<p>Welcome to Acme</p>",
});
```

```ts After (Delivrie)
import { Delivrie } from "delivrie";

const delivrie = new Delivrie(process.env.DELIVRIE_API_KEY);
const { data, error } = await delivrie.emails.send({
  from: "Acme <hello@mail.acme.com>",
  to: ["ada@example.com"],
  subject: "Welcome",
  html: "<p>Welcome to Acme</p>",
});
```

Same `{ data, error }` result, same field names. React Email works the same way too: pass `react: <Welcome />` and keep `@react-email/render` installed.

### Option C: plain HTTP

Replace `https://api.resend.com` with `https://delivrie.io/api` and your `re_...` key with a `dlv_...` key. Paths and bodies stay the same.

## 4. Update webhooks

Create a webhook in [Webhooks](https://delivrie.io/webhooks) with the same events. Event names (`email.sent`, `email.delivered`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.received` and the rest) and the `{ type, created_at, data }` body are the same.

Signatures use the same HMAC scheme, but the headers are named `webhook-id`, `webhook-timestamp` and `webhook-signature` (the [Standard Webhooks](https://www.standardwebhooks.com) names) instead of `svix-id`, `svix-timestamp` and `svix-signature`. Use `verifyWebhook` from the `delivrie` package, or any Standard Webhooks library, with your new `whsec_` secret. See [Webhooks](/docs/webhooks) for code.

## What's different

| Resend | Delivrie |
| --- | --- |
| `https://api.resend.com` | `https://delivrie.io/api` |
| Keys start with `re_` | Keys start with `dlv_` |
| Attachments by `path` (a URL) | Send base64 `content` instead; `path` isn't supported yet |
| Audiences (`/audiences/:id/contacts`) | Contacts live at `/contacts`; group them with [segments](/docs/contacts) |
| Broadcasts to an audience | Broadcasts go to a `segment_id` |
| `svix-*` webhook headers | `webhook-*` headers, same signing |
| Several sending regions | `eu-west-1` today |
| `onboarding@resend.dev` for testing | `onboarding@delivrie.io`, plus [test addresses](/docs/test-mode) |

Things Delivrie adds: an [SMTP relay](/docs/smtp) on ports 587 and 465, an [inbox](/docs/inbox) for replies, [automations](/docs/automations) triggered by events, an [MCP server](/docs/mcp) for AI assistants, and billing in naira or dollars.

## Move your contacts and templates

- **Contacts:** export a CSV from Resend and import it in [Contacts → Import](https://delivrie.io/contacts/import), or loop over them with [`POST /contacts`](/docs/api/create-contact).
- **Templates:** copy the HTML into a new [template](/docs/templates). Variables use the same `{{{name}}}` syntax, then publish and send with `template: { id: "your-alias", variables: {...} }`. In broadcasts, `{{{RESEND_UNSUBSCRIBE_URL}}}` keeps working as an alias for `{{{unsubscribe_url}}}`.
- **Suppressions:** add addresses that bounced or complained on Resend with [`POST /suppressions`](/docs/api/add-suppression), so you don't email them again.

## Switch-over checklist

1. Domain verified in Delivrie, with a non-`send` bounce subdomain if Resend is still live.
2. `dlv_` key stored in your production environment.
3. Send a test to `delivered@test.delivrie.io` from your production sender and check it in [Emails](https://delivrie.io/emails).
4. Webhook endpoint updated for the new header names and secret, and **Send test event** returns 200.
5. Deploy. Watch [Emails](https://delivrie.io/emails) and [Logs](https://delivrie.io/logs) for an hour.
6. Remove Resend's DNS records and keys when you're happy.


---

# API keys

Create, scope, store and rotate Delivrie API keys: full access vs sending access, domain-restricted keys, and what to do if a key leaks.

Every API request needs a key in the `Authorization` header:

```http
Authorization: Bearer dlv_your_key
```

## Create a key

In the dashboard, open [API keys](https://delivrie.io/api-keys) and click **Create API key**, or call [`POST /api-keys`](/docs/api/create-api-key) with a full access key:

```bash
curl -X POST https://delivrie.io/api/api-keys \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production web app", "permission": "sending_access" }'
```

The response contains the key in `token`. It's shown once: Delivrie stores only a hash, so copy it straight into your secret store.

## Permissions

| Permission | Can do | Use for |
| --- | --- | --- |
| `full_access` | Every endpoint: domains, contacts, webhooks, keys, logs and sending | Scripts, back-office tools, CI |
| `sending_access` | Only sending: `POST /emails`, `POST /emails/batch`, rescheduling, canceling and forwarding emails, `POST /events` and inbox replies | Production apps |

Add `domain_id` to a sending key to limit it to one domain. Sending from any other domain then fails with `403 restricted_api_key`. Calling an endpoint a sending key can't use also returns `403 restricted_api_key`.

## Store keys safely

- Keep keys in environment variables or your platform's secret store (Vercel, Netlify, Fly, Supabase, Cloudflare and GitHub Actions all have one). Name it `DELIVRIE_API_KEY`; the Node.js SDK reads it automatically.
- Never put a key in browser or mobile app code, a public repo, or a URL.
- Use a separate key per app and environment, so you can revoke one without breaking the others.

## Rotate or revoke

Create the new key, deploy it, then delete the old one in [API keys](https://delivrie.io/api-keys) (or with `DELETE /api-keys/:id`). Deletion takes effect immediately; requests with the old key get `401 invalid_api_key`.

> **Warning:** If a key leaks, delete it straight away, then check [Logs](https://delivrie.io/logs) for requests you don't recognise. Every API request is logged, along with the key that made it.

## Keys for AI assistants

You don't need to give an assistant your API key. Connect it to the [MCP server](/docs/mcp) instead: you approve the team and scopes in your browser, and can revoke access under Settings → Connected apps.


---

# Plans and limits

Email allowances, daily limits, domains, webhooks, data retention and team seats on Free, Starter, Pro and Scale, plus what happens when you reach a limit.

| | Free | Starter | Pro | Scale |
| --- | --- | --- | --- | --- |
| Emails a month | 4,000 | 20,000 | 60,000 | 100,000 |
| Daily limit | 133 | None | None | None |
| Over the allowance | Sending pauses (or uses credits) | Keeps sending, billed per 1,000 | Keeps sending, billed per 1,000 | Keeps sending, billed per 1,000 |
| Domains | 1 | 10 | 10 | 1,000 |
| Webhook endpoints | 1 | 10 | 10 | Unlimited |
| Team members | 1 | 5 | 5 | Unlimited |
| Email content kept (sent and received) | 30 days | 30 days | 30 days | 30 days |
| API request logs kept | 30 days | 30 days | 30 days | 30 days |

Prices are on the [pricing page](https://delivrie.io/pricing). Enterprise plans with custom volumes, retention and support are available through [sales](https://delivrie.io/contact-sales).

## What counts as an email

Each email you send through the API or SMTP counts as one, whether it goes to one recipient or several in `to`, `cc` and `bcc`. A batch of 50 counts as 50. Sends to the [test addresses](/docs/test-mode) count too. Broadcasts are billed through the marketing plan instead.

Check where you are with `GET /usage` or in [Billing](https://delivrie.io/billing):

```json
{
  "object": "usage",
  "plan": "free",
  "emails_this_month": 1840,
  "monthly_allowance": 4000,
  "emails_today": 37,
  "daily_limit": 133,
  "credits_emails": 0,
  "overage_after_allowance": false
}
```

## When you reach a limit

**Free plan.** At 133 emails in a day or 4,000 in a month, sends fail with `429 daily_quota_exceeded` or `429 monthly_quota_exceeded`. If you've bought pay-as-you-go credits, Delivrie uses them instead and keeps sending. One credit is one email, and credits never expire. Daily limits reset at midnight UTC; monthly limits on the 1st (UTC).

**Paid plans.** Sending never stops at the allowance. Emails over it are billed per 1,000 at the end of the month. To put a ceiling on that, set a spending cap in [Billing](https://delivrie.io/billing); a send that would go past it fails with `429 spending_cap_reached`.

**Domains and webhooks.** Adding more than your plan allows fails with `403 plan_limit_reached`.

> **Tip:** Treat `429` quota errors as "stop and alert someone", not "retry in a loop". Retrying won't succeed until the limit resets or the plan changes.


---

# Node.js SDK

The official delivrie npm package for Node.js and TypeScript: install, configuration, results and errors, retries, every method, attachments and webhook verification.

The `delivrie` package is the official SDK for Node.js and TypeScript. It has no dependencies and uses only web-standard APIs (`fetch` and Web Crypto), so the same code runs on Node.js 18+, Bun, Deno, Cloudflare Workers and Vercel Edge. Source: [github.com/codeddesigner/delivrie](https://github.com/codeddesigner/delivrie/tree/main/sdk/node).

```bash npm
npm install delivrie
```

```bash pnpm
pnpm add delivrie
```

```bash yarn
yarn add delivrie
```

```bash bun
bun add delivrie
```

## Create a client

```ts
import { Delivrie } from "delivrie";

const delivrie = new Delivrie(process.env.DELIVRIE_API_KEY);
```

If you leave out the key, the client reads `DELIVRIE_API_KEY` from the environment. On edge runtimes without `process.env` (Cloudflare Workers, for example), pass the key from your bindings: `new Delivrie(env.DELIVRIE_API_KEY)`.

CommonJS works too: `const { Delivrie } = require("delivrie")`.

| Option | Default | What it does |
| --- | --- | --- |
| `baseUrl` | `https://delivrie.io/api` | API address |
| `timeout` | `30000` | Milliseconds before a request gives up |
| `maxRetries` | `2` | Retries for server errors and network failures |
| `fetch` | global `fetch` | Your own fetch, for tests or older runtimes |
| `headers` | none | Extra headers on every request |

```ts
const delivrie = new Delivrie(process.env.DELIVRIE_API_KEY, { timeout: 10_000, maxRetries: 3 });
```

## Send an email

```ts
const { data, error } = await delivrie.emails.send({
  from: "Acme <orders@mail.acme.com>",
  to: "ada@example.com",
  subject: "Your order is confirmed",
  html: "<p>Order <b>#1042</b> is on its way.</p>",
  replyTo: "support@acme.com",
  tags: [{ name: "category", value: "receipt" }],
}, { idempotencyKey: "order-1042-receipt" });
```

Field names match the API (`reply_to`, `scheduled_at`). `replyTo` and `scheduledAt` are accepted as aliases, and `scheduledAt` can be a `Date`. Every field is described in [Send an email](/docs/send-email).

## React Email

Pass a [React Email](https://react.email) component as `react`, and the SDK renders it to HTML and plain text for you:

```bash
npm install @react-email/components @react-email/render
```

```tsx
import { Welcome } from "./emails/welcome";

await delivrie.emails.send({
  from: "Acme <hello@mail.acme.com>",
  to: "ada@example.com",
  subject: "Welcome to Acme",
  react: <Welcome name="Ada" />,
});
```

`react` works in `emails.batch` too. If you also pass `html`, the `html` wins. Without `@react-email/render` installed, the call returns an error named `react_render_error` explaining what to install. On edge runtimes that can't load it at run time, render first with `await render(<Welcome />)` and pass the result as `html`.

## Results and errors

Every method resolves to `{ data, error }`, and exactly one of them is `null`. API errors never throw, so there's no `try`/`catch` to forget:

```ts
const { data, error } = await delivrie.emails.send(email);
if (error) {
  console.error(error.statusCode, error.name, error.message);
  return;
}
console.log(data.id);
```

`error.name` is the API's error name, like `validation_error` or `monthly_quota_exceeded` (see [Errors](/docs/errors)). Problems that never reach the API come back with `statusCode: 0` and the name `network_error`, `timeout` or `aborted`.

## Retries and idempotency

- `GET` and `DELETE` requests are retried up to `maxRetries` times on `5xx` responses and network failures, with exponential backoff.
- Sends (`POST`) are retried **only when you pass `idempotencyKey`**. The key makes the retry return the original email instead of sending a second one.

```ts
await delivrie.emails.send(email, { idempotencyKey: `welcome-${user.id}` });
```

Cancel a request with an `AbortSignal`: `delivrie.emails.send(email, { signal: AbortSignal.timeout(5000) })`.

## Attachments

Pass `content` as a base64 string, a Node.js `Buffer` or a `Uint8Array`; the SDK encodes bytes for you. Up to 40 MB per email.

```ts
import { readFile } from "node:fs/promises";

await delivrie.emails.send({
  from: "Billing <billing@mail.acme.com>",
  to: "ada@example.com",
  subject: "Your invoice",
  text: "Your invoice is attached.",
  attachments: [{ filename: "invoice-1042.pdf", content: await readFile("invoice-1042.pdf") }],
});
```

## Methods

| Resource | Methods |
| --- | --- |
| `emails` | `send(email, opts?)`, `batch(emails, opts?)`, `get(id)`, `list({ limit, offset, direction })`, `listReceived()`, `update(id, { scheduled_at })`, `cancel(id)`, `forward(id, { to, from, note })` |
| `domains` | `create({ name })`, `get(id)`, `verify(id)`, `update(id, {...})`, `list()`, `remove(id)` |
| `apiKeys` | `create({ name, permission, domain_id })`, `list()`, `remove(id)` |
| `webhooks` | `create({ endpoint, events })`, `list()`, `deliveries(id)`, `test(id)`, `replay(deliveryId)`, `verify(opts)` |
| `contacts` | `create({...})`, `get(idOrEmail)`, `update(idOrEmail, {...})`, `list({...})`, `remove(idOrEmail)` |
| `segments` | `create({ name })`, `list()`, `remove(id)`, `addContacts(id, contacts)` |
| `topics`, `contactProperties` | `list()` |
| `broadcasts` | `create({...})`, `get(id)`, `list()`, `send(id, { scheduled_at })`, `cancel(id)`, `recipients(id)`, `remove(id)` |
| `templates` | `create({...})`, `get(idOrAlias)`, `list()`, `publish(id)` |
| `suppressions` | `add(email \| emails)`, `list()`, `remove(email)` |
| `events` | `send({ event, email, data })`, `list()` |
| `automations` | `list()`, `get(id)`, `create({...})`, `runs(id)`, `publish(id)`, `pause(id)`, `resume(id)` |
| `inbox.threads` | `list({...})`, `get(id)`, `update(id, {...})`, `reply(id, { text \| html })` |
| `inbox.labels` | `list()` |
| `metrics` | `get({ days, domain_id })` |
| `logs` | `list({ limit, offset })`, `get(id)` |
| `usage` | `get()` |

For anything not wrapped yet, call the API directly with the same auth, retries and error handling:

```ts
const { data, error } = await delivrie.request("GET", "/emails/received", undefined, { query: { limit: 10 } });
```

## Verify webhooks

`verifyWebhook` checks a webhook's signature against the raw request body and your `whsec_` secret, rejects requests older than five minutes, and returns the parsed event. It's `async` because it uses Web Crypto.

```ts
import { verifyWebhook } from "delivrie";

export async function POST(req: Request) {
  try {
    const event = await verifyWebhook({
      payload: await req.text(),
      headers: req.headers,
      secret: process.env.DELIVRIE_WEBHOOK_SECRET!,
    });
    // event.type, event.data
    return new Response("ok");
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
}
```

With Express, read the raw body with `express.raw({ type: "application/json" })` and pass `req.body` and `req.headers`. More in [Webhooks](/docs/webhooks).

## TypeScript

Types ship with the package: `SendEmailRequest`, `Email`, `Domain`, `Contact`, `WebhookEvent`, `DelivrieErrorResponse` and more.

```ts
import type { SendEmailRequest, WebhookEvent } from "delivrie";
```


---

# Next.js

Send email from Next.js with Delivrie: App Router route handlers, Server Actions, React Email templates, webhooks and deploying on Vercel.

Send from server code only: route handlers, Server Actions or `getServerSideProps`. Never from client components, because the API key would ship to the browser.

## 1. Install and add your key

```bash
npm install delivrie
```

```bash .env.local
DELIVRIE_API_KEY=dlv_your_key
```

On Vercel, add the same variable under **Project → Settings → Environment Variables**. Don't prefix it with `NEXT_PUBLIC_`, which would expose it to the browser.

Create one client to share:

```ts lib/delivrie.ts
import { Delivrie } from "delivrie";

export const delivrie = new Delivrie(process.env.DELIVRIE_API_KEY);
```

## 2a. Send from a route handler

```ts app/api/send/route.ts
import { delivrie } from "@/lib/delivrie";

export async function POST(req: Request) {
  const { email, name } = await req.json();

  const { data, error } = await delivrie.emails.send({
    from: "Acme <hello@mail.acme.com>",
    to: email,
    subject: `Welcome to Acme, ${name}`,
    html: `<p>Hi ${name}, thanks for signing up.</p>`,
  }, { idempotencyKey: `welcome-${email}` });

  if (error) return Response.json({ error: error.message }, { status: error.statusCode || 500 });
  return Response.json({ id: data.id });
}
```

> **Warning:** Escape anything users type before putting it in `html`, or use React Email (below), which escapes for you.

## 2b. Or from a Server Action

```tsx app/contact/page.tsx
import { delivrie } from "@/lib/delivrie";

async function sendMessage(formData: FormData) {
  "use server";
  const { error } = await delivrie.emails.send({
    from: "Website <forms@mail.acme.com>",
    to: "team@acme.com",
    replyTo: String(formData.get("email")),
    subject: "New contact form message",
    text: String(formData.get("message")),
  });
  if (error) throw new Error(error.message);
}

export default function Page() {
  return (
    <form action={sendMessage}>
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button type="submit">Send</button>
    </form>
  );
}
```

## React Email

Build templates as React components with [React Email](https://react.email) and send them with the `react` option:

```bash
npm install @react-email/components @react-email/render
```

```tsx emails/welcome.tsx
import { Html, Body, Heading, Text, Button } from "@react-email/components";

export default function Welcome({ name }: { name: string }) {
  return (
    <Html>
      <Body style={{ fontFamily: "sans-serif" }}>
        <Heading>Welcome, {name}</Heading>
        <Text>Thanks for joining Acme.</Text>
        <Button href="https://acme.com/start">Get started</Button>
      </Body>
    </Html>
  );
}
```

Pass the component as `react`; the SDK renders it to HTML and plain text:

```tsx app/api/welcome/route.tsx
import Welcome from "@/emails/welcome";
import { delivrie } from "@/lib/delivrie";

export async function POST(req: Request) {
  const { email, name } = await req.json();
  const { data, error } = await delivrie.emails.send({
    from: "Acme <hello@mail.acme.com>",
    to: email,
    subject: "Welcome to Acme",
    react: <Welcome name={name} />,
  });
  return error ? Response.json(error, { status: 502 }) : Response.json(data);
}
```

Preview templates while you design them with `npx react-email dev`.

## Receive webhooks

```ts app/api/webhooks/delivrie/route.ts
import { verifyWebhook } from "delivrie";

export async function POST(req: Request) {
  let event;
  try {
    event = await verifyWebhook({
      payload: await req.text(),
      headers: req.headers,
      secret: process.env.DELIVRIE_WEBHOOK_SECRET!,
    });
  } catch {
    return new Response("invalid signature", { status: 400 });
  }

  if (event.type === "email.bounced" || event.type === "email.complained") {
    // mark event.data.to as undeliverable in your database
  }
  return new Response("ok");
}
```

Add the endpoint in [Webhooks](https://delivrie.io/webhooks) as `https://your-app.com/api/webhooks/delivrie` and copy its signing secret into `DELIVRIE_WEBHOOK_SECRET`.

## Edge runtime

The SDK works on the Edge runtime without changes: add `export const runtime = "edge"` to the route file.

## Common problems

- **`Missing API key`:** the variable isn't set in this environment. Check `.env.local` locally and the Vercel project settings for Preview and Production, then redeploy.
- **It works locally but not on Vercel:** environment variables apply to new deployments only. Redeploy after adding them.
- **`422` saying the from domain isn't verified:** use a sender on a domain verified in [Domains](https://delivrie.io/domains), or `onboarding@delivrie.io` while testing.


---

# Node.js and Express

Send email from Node.js, Express, Fastify, NestJS or Hono with Delivrie, and verify webhooks with the raw request body.

## Install

```bash
npm install delivrie
```

Set `DELIVRIE_API_KEY` in your environment (a `.env` file loaded with `node --env-file=.env`, or your host's settings).

## Send an email

```js server.js
import express from "express";
import { Delivrie } from "delivrie";

const app = express();
const delivrie = new Delivrie(process.env.DELIVRIE_API_KEY);

app.post("/signup", express.json(), async (req, res) => {
  const { email } = req.body;
  // ...create the user...

  const { data, error } = await delivrie.emails.send({
    from: "Acme <hello@mail.acme.com>",
    to: email,
    subject: "Confirm your email",
    html: `<p>Click <a href="https://acme.com/confirm?e=${encodeURIComponent(email)}">here</a> to confirm.</p>`,
  }, { idempotencyKey: `confirm-${email}` });

  if (error) return res.status(502).json({ error: error.message });
  res.json({ ok: true, emailId: data.id });
});

app.listen(3000);
```

## Verify webhooks in Express

Signature checks need the body exactly as it arrived, so use `express.raw` on the webhook route (not `express.json`):

```js server.js
import { verifyWebhook } from "delivrie";

app.post("/webhooks/delivrie", express.raw({ type: "application/json" }), async (req, res) => {
  try {
    const event = await verifyWebhook({
      payload: req.body,          // a Buffer
      headers: req.headers,
      secret: process.env.DELIVRIE_WEBHOOK_SECRET,
    });
    console.log(event.type, event.data.email_id);
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);
  }
});
```

Register any `express.json()` middleware after this route, or only on the routes that need it.

## Other frameworks

The SDK is framework-agnostic. A few notes:

- **Fastify:** add a content-type parser that keeps the raw body for the webhook route (`fastify.addContentTypeParser("application/json", { parseAs: "buffer" }, (req, body, done) => done(null, body))`).
- **NestJS:** create the client once in a provider and inject it; enable `rawBody: true` in `NestFactory.create` for webhooks.
- **Hono and other fetch-style frameworks:** use `await c.req.text()` as the payload and `c.req.raw.headers` as the headers.

## Without the SDK

Any HTTP client works:

```js
const res = await fetch("https://delivrie.io/api/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DELIVRIE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1042-receipt",
  },
  body: JSON.stringify({ from: "Acme <orders@mail.acme.com>", to: "ada@example.com", subject: "Receipt", html: "<p>Thanks!</p>" }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.name}: ${body.message}`);
```

## Nodemailer

Already using Nodemailer? Point it at the [SMTP relay](/docs/smtp) instead:

```js
import nodemailer from "nodemailer";

const transport = nodemailer.createTransport({
  host: "smtp.delivrie.io",
  port: 587,
  secure: false, // STARTTLS
  auth: { user: "delivrie", pass: process.env.DELIVRIE_API_KEY },
});

await transport.sendMail({ from: "Acme <hello@mail.acme.com>", to: "ada@example.com", subject: "Hi", text: "Hello" });
```


---

# Python

Send email from Python, Django, Flask and FastAPI with the official delivrie package, verify webhooks, or use Django's SMTP backend.

The official [`delivrie`](https://pypi.org/project/delivrie/) package covers the whole API. It has no dependencies, works on Python 3.10 and later, and comes in sync and async versions. (Already using the `resend` package? Set `RESEND_API_URL=https://delivrie.io/api` and it talks to Delivrie; see [Migrate from Resend](/docs/migrate-from-resend).)

```bash
pip install delivrie
```

## Send an email

Create an API key in [API keys](https://delivrie.io/api-keys) and set it as `DELIVRIE_API_KEY`.

```python send.py
from delivrie import Delivrie

client = Delivrie()  # reads DELIVRIE_API_KEY

email = client.emails.send(
    from_="Acme <hello@mail.acme.com>",
    to="ada@example.com",
    subject="Welcome to Acme",
    html="<p>Thanks for signing up.</p>",
    idempotency_key="welcome-42",
)
print(email["id"])
```

`from` is a Python keyword, so pass `from_`, or pass a dict exactly like the REST API: `client.emails.send({"from": ..., "to": ..., ...})`. A `datetime` works for `scheduled_at`, `bytes` for attachment content and a dict for `tags`.

With an `idempotency_key`, the SDK retries network errors, rate limits and server errors safely: a retry returns the original email instead of sending a second one. Without one, sends aren't retried. See [Idempotency and retries](/docs/idempotency).

## Errors

Methods return the API's JSON as a dict and raise `DelivrieError` on failure:

```python
from delivrie import DelivrieError

try:
    client.emails.send(from_="Acme <hello@mail.acme.com>", to="ada@example.com", subject="Hi", text="Hello")
except DelivrieError as e:
    print(e.status_code, e.name, e.message)
```

Branch on `e.name` (see [Errors](/docs/errors)). `status_code` is 0 for `network_error` and `timeout`.

## Templates and attachments

```python
client.emails.send(
    from_="Acme <billing@mail.acme.com>",
    to="ada@example.com",
    template={"id": "invoice", "variables": {"first_name": "Ada", "total": "$20.00"}},
    attachments=[{"filename": "invoice.pdf", "content": open("invoice.pdf", "rb").read()}],
)
```

## Async (FastAPI)

```python main.py
from delivrie import AsyncDelivrie, DelivrieError
from fastapi import FastAPI, HTTPException

app = FastAPI()
client = AsyncDelivrie()

@app.post("/signup")
async def signup(email: str):
    try:
        sent = await client.emails.send(
            from_="Acme <hello@mail.acme.com>",
            to=email,
            subject="Welcome",
            html="<p>Thanks for signing up.</p>",
            idempotency_key=f"welcome-{email}",
        )
    except DelivrieError as e:
        raise HTTPException(502, e.message)
    return {"email_id": sent["id"]}
```

## Django

The simplest setup is Django's SMTP backend with the [SMTP relay](/docs/smtp), so `send_mail` and password-reset emails go through Delivrie:

```python settings.py
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.delivrie.io"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "delivrie"
EMAIL_HOST_PASSWORD = os.environ["DELIVRIE_API_KEY"]
DEFAULT_FROM_EMAIL = "Acme <hello@mail.acme.com>"
```

For templates, scheduling or tags, call the SDK from your views or tasks instead.

## Flask

```python app.py
from delivrie import Delivrie, DelivrieError
from flask import Flask, request

app = Flask(__name__)
client = Delivrie()

@app.post("/contact")
def contact():
    try:
        client.emails.send(
            from_="Website <forms@mail.acme.com>",
            to="team@acme.com",
            reply_to=request.form["email"],
            subject="New contact form message",
            text=request.form["message"],
        )
    except DelivrieError as e:
        return e.message, 502
    return "Sent", 200
```

## Verify webhooks

Pass the raw body, before parsing it:

```python webhooks.py
import os
from delivrie import verify_webhook, WebhookVerificationError

@app.post("/webhooks/delivrie")
def delivrie_webhook():
    try:
        event = verify_webhook(request.get_data(), request.headers, os.environ["DELIVRIE_WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return "", 400
    if event["type"] == "email.bounced":
        ...
    return "", 204
```

In Django pass `request.body` and `request.headers`; in FastAPI, `await request.body()` and `request.headers`.

## Everything else

The client uses the same names as the [Node.js SDK](/docs/sdks), in snake_case: `client.domains`, `client.api_keys`, `client.webhooks`, `client.contacts`, `client.segments`, `client.broadcasts`, `client.templates`, `client.suppressions`, `client.events`, `client.automations`, `client.inbox.threads`, `client.metrics`, `client.logs` and `client.usage`. For anything else, `client.request("GET", "/path")` calls the API directly.

## Without the SDK

The API is a single JSON request, so `requests` or `httpx` work too:

```python
import os, requests

res = requests.post(
    "https://delivrie.io/api/emails",
    headers={"Authorization": f"Bearer {os.environ['DELIVRIE_API_KEY']}", "Idempotency-Key": "welcome-42"},
    json={"from": "Acme <hello@mail.acme.com>", "to": "ada@example.com", "subject": "Welcome", "html": "<p>Hi</p>"},
    timeout=30,
)
res.raise_for_status()
print(res.json()["id"])
```


---

# PHP and Laravel

Send email from PHP and Laravel with Delivrie: Laravel's SMTP mailer, Guzzle or curl, and webhook verification.

## Laravel

Laravel's mail system works with the [SMTP relay](/docs/smtp) out of the box, so `Mail::to(...)->send(...)`, notifications and password resets all go through Delivrie. Update `.env`:

```bash .env
MAIL_MAILER=smtp
MAIL_HOST=smtp.delivrie.io
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=delivrie
MAIL_PASSWORD=dlv_your_key
MAIL_FROM_ADDRESS=hello@mail.acme.com
MAIL_FROM_NAME="Acme"
```

Then clear the config cache (`php artisan config:clear`) and send as usual:

```php
use Illuminate\Support\Facades\Mail;
use App\Mail\OrderShipped;

Mail::to($user)->send(new OrderShipped($order));
```

Already on Laravel's `resend` mailer? Set `RESEND_BASE_URL=https://delivrie.io/api` and `RESEND_API_KEY=dlv_your_key` instead; see [Migrate from Resend](/docs/migrate-from-resend).

## Plain PHP with the HTTP API

```php send.php
<?php
$ch = curl_init('https://delivrie.io/api/emails');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DELIVRIE_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-1042-receipt',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'from' => 'Acme <orders@mail.acme.com>',
        'to' => 'ada@example.com',
        'subject' => 'Your receipt',
        'html' => '<p>Thanks for your order.</p>',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("{$body['name']}: {$body['message']}");
}
echo $body['id'];
```

With Guzzle:

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://delivrie.io/api/']);
$res = $client->post('emails', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('DELIVRIE_API_KEY')],
    'json' => ['from' => 'Acme <hello@mail.acme.com>', 'to' => 'ada@example.com', 'subject' => 'Hi', 'text' => 'Hello'],
]);
$id = json_decode($res->getBody(), true)['id'];
```

## WordPress

Use any SMTP plugin (WP Mail SMTP, FluentSMTP, Post SMTP) with host `smtp.delivrie.io`, port `587`, encryption TLS, username `delivrie` and an API key as the password. See [SMTP](/docs/smtp).

## Verify webhooks

```php webhook.php
<?php
function verify_delivrie_webhook(string $payload, array $headers, string $secret, int $tolerance = 300): array {
    $id = $headers['webhook-id'] ?? '';
    $ts = $headers['webhook-timestamp'] ?? '';
    if (abs(time() - (int) $ts) > $tolerance) throw new Exception('timestamp too old');
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "$id.$ts.$payload", $key, true));
    foreach (explode(' ', $headers['webhook-signature'] ?? '') as $sig) {
        [$version, $value] = array_pad(explode(',', $sig, 2), 2, '');
        if ($version === 'v1' && hash_equals($expected, $value)) return json_decode($payload, true);
    }
    throw new Exception('invalid signature');
}

$event = verify_delivrie_webhook(
    file_get_contents('php://input'),
    array_change_key_case(getallheaders(), CASE_LOWER),
    getenv('DELIVRIE_WEBHOOK_SECRET'),
);
```

In Laravel, use `$request->getContent()` for the payload and `collect($request->headers->all())->map(fn ($v) => $v[0])->all()` for the headers, and exclude the route from CSRF protection.


---

# Ruby and Rails

Send email from Ruby on Rails with Action Mailer over SMTP, or from any Ruby app with Net::HTTP, and verify Delivrie webhooks.

## Rails (Action Mailer)

Point Action Mailer at the [SMTP relay](/docs/smtp) and your existing mailers, Devise emails and `deliver_later` jobs send through Delivrie:

```ruby config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: "smtp.delivrie.io",
  port: 587,
  user_name: "delivrie",
  password: ENV.fetch("DELIVRIE_API_KEY"),
  authentication: :plain,
  enable_starttls_auto: true,
}
config.action_mailer.default_options = { from: "Acme <hello@mail.acme.com>" }
```

## Any Ruby app (HTTP API)

```ruby send.rb
require "net/http"
require "json"

uri = URI("https://delivrie.io/api/emails")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('DELIVRIE_API_KEY')}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = "welcome-42"
req.body = {
  from: "Acme <hello@mail.acme.com>",
  to: "ada@example.com",
  subject: "Welcome",
  html: "<p>Welcome to Acme</p>",
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
body = JSON.parse(res.body)
raise "#{body['name']}: #{body['message']}" unless res.is_a?(Net::HTTPSuccess)
puts body["id"]
```

## Verify webhooks

```ruby app/controllers/delivrie_webhooks_controller.rb
require "openssl"
require "base64"

class DelivrieWebhooksController < ActionController::API
  def create
    payload = request.raw_post
    id, ts, sigs = request.headers["webhook-id"], request.headers["webhook-timestamp"], request.headers["webhook-signature"].to_s
    return head(:bad_request) if (Time.now.to_i - ts.to_i).abs > 300

    key = Base64.decode64(ENV.fetch("DELIVRIE_WEBHOOK_SECRET").delete_prefix("whsec_"))
    expected = Base64.strict_encode64(OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{ts}.#{payload}"))
    valid = sigs.split(" ").any? do |s|
      version, value = s.split(",", 2)
      version == "v1" && ActiveSupport::SecurityUtils.secure_compare(value.to_s, expected)
    end
    return head(:bad_request) unless valid

    event = JSON.parse(payload)
    # event["type"], event["data"]
    head :ok
  end
end
```


---

# Go

Send email from Go with Delivrie using net/http, with typed request and error structs, and verify webhooks.

There's no Go module yet; `net/http` and `encoding/json` are all you need. (Already using `resend-go`? Set `RESEND_BASE_URL=https://delivrie.io/api/` and it talks to Delivrie; see [Migrate from Resend](/docs/migrate-from-resend).)

## Send an email

```go main.go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Email struct {
	From    string   `json:"from"`
	To      []string `json:"to"`
	Subject string   `json:"subject"`
	HTML    string   `json:"html,omitempty"`
	Text    string   `json:"text,omitempty"`
	ReplyTo string   `json:"reply_to,omitempty"`
}

type APIError struct {
	StatusCode int    `json:"statusCode"`
	Name       string `json:"name"`
	Message    string `json:"message"`
}

func (e *APIError) Error() string { return e.Name + ": " + e.Message }

var client = &http.Client{Timeout: 30 * time.Second}

func Send(email Email, idempotencyKey string) (string, error) {
	body, _ := json.Marshal(email)
	req, _ := http.NewRequest("POST", "https://delivrie.io/api/emails", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("DELIVRIE_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	if idempotencyKey != "" {
		req.Header.Set("Idempotency-Key", idempotencyKey)
	}
	res, err := client.Do(req)
	if err != nil {
		return "", err
	}
	defer res.Body.Close()
	if res.StatusCode >= 400 {
		var apiErr APIError
		json.NewDecoder(res.Body).Decode(&apiErr)
		return "", &apiErr
	}
	var out struct{ ID string `json:"id"` }
	return out.ID, json.NewDecoder(res.Body).Decode(&out)
}

func main() {
	id, err := Send(Email{
		From:    "Acme <hello@mail.acme.com>",
		To:      []string{"ada@example.com"},
		Subject: "Welcome",
		HTML:    "<p>Welcome to Acme</p>",
	}, "welcome-42")
	if err != nil {
		fmt.Println("send failed:", err)
		return
	}
	fmt.Println("sent", id)
}
```

## Verify webhooks

```go webhook.go
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"errors"
	"io"
	"net/http"
	"strconv"
	"strings"
	"time"
)

func VerifyWebhook(r *http.Request, secret string) ([]byte, error) {
	payload, err := io.ReadAll(r.Body)
	if err != nil {
		return nil, err
	}
	id, ts := r.Header.Get("webhook-id"), r.Header.Get("webhook-timestamp")
	t, err := strconv.ParseInt(ts, 10, 64)
	if err != nil || time.Since(time.Unix(t, 0)).Abs() > 5*time.Minute {
		return nil, errors.New("bad timestamp")
	}
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return nil, err
	}
	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(id + "." + ts + "."))
	mac.Write(payload)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
	for _, sig := range strings.Split(r.Header.Get("webhook-signature"), " ") {
		if v, value, ok := strings.Cut(sig, ","); ok && v == "v1" && hmac.Equal([]byte(value), []byte(expected)) {
			return payload, nil
		}
	}
	return nil, errors.New("invalid signature")
}
```

Decode the returned payload into a struct with `Type string` and `Data json.RawMessage` fields, then switch on `Type`.


---

# Rust

Send email from Rust with Delivrie using reqwest and serde, handle API errors, send attachments and verify webhooks.

There's no Rust crate yet. The API is plain JSON over HTTPS, so `reqwest` and `serde` cover it.

```toml Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

## Send an email

```rust src/main.rs
use serde::{Deserialize, Serialize};

#[derive(Serialize)]
struct Email<'a> {
    from: &'a str,
    to: Vec<&'a str>,
    subject: &'a str,
    #[serde(skip_serializing_if = "Option::is_none")]
    html: Option<&'a str>,
    #[serde(skip_serializing_if = "Option::is_none")]
    text: Option<&'a str>,
}

#[derive(Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
struct ApiError {
    status_code: u16,
    name: String,
    message: String,
}

#[derive(Deserialize)]
struct Sent {
    id: String,
}

async fn send(client: &reqwest::Client, email: &Email<'_>, idempotency_key: &str) -> Result<String, ApiError> {
    let key = std::env::var("DELIVRIE_API_KEY").expect("set DELIVRIE_API_KEY");
    let res = client
        .post("https://delivrie.io/api/emails")
        .bearer_auth(key)
        .header("Idempotency-Key", idempotency_key)
        .json(email)
        .send()
        .await
        .map_err(|e| ApiError { status_code: 0, name: "network_error".into(), message: e.to_string() })?;

    if res.status().is_success() {
        let sent: Sent = res.json().await.map_err(|e| ApiError { status_code: 0, name: "decode_error".into(), message: e.to_string() })?;
        Ok(sent.id)
    } else {
        Err(res.json::<ApiError>().await.unwrap_or(ApiError {
            status_code: 0,
            name: "application_error".into(),
            message: "unreadable error body".into(),
        }))
    }
}

#[tokio::main]
async fn main() {
    let client = reqwest::Client::new();
    let email = Email {
        from: "Acme <hello@mail.acme.com>",
        to: vec!["ada@example.com"],
        subject: "Welcome",
        html: Some("<p>Welcome to Acme</p>"),
        text: None,
    };
    match send(&client, &email, "welcome-42").await {
        Ok(id) => println!("sent {id}"),
        Err(e) => eprintln!("{} {}: {}", e.status_code, e.name, e.message),
    }
}
```

Reuse one `reqwest::Client` for the whole app; it keeps connections open between requests.

## Attachments

Add the `base64` crate and send the file as base64 `content`:

```rust
use base64::{engine::general_purpose::STANDARD, Engine};

let pdf = std::fs::read("invoice.pdf")?;
let body = serde_json::json!({
    "from": "Billing <billing@mail.acme.com>",
    "to": ["ada@example.com"],
    "subject": "Your invoice",
    "text": "Attached.",
    "attachments": [{ "filename": "invoice.pdf", "content": STANDARD.encode(pdf) }]
});
```

## Verify webhooks

```toml Cargo.toml
hmac = "0.12"
sha2 = "0.10"
base64 = "0.22"
```

```rust src/webhook.rs
use base64::{engine::general_purpose::STANDARD, Engine};
use hmac::{Hmac, Mac};
use sha2::Sha256;

pub fn verify(payload: &[u8], id: &str, timestamp: &str, signatures: &str, secret: &str) -> bool {
    let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64;
    match timestamp.parse::<i64>() {
        Ok(ts) if (now - ts).abs() <= 300 => {}
        _ => return false,
    }
    let Ok(key) = STANDARD.decode(secret.trim_start_matches("whsec_")) else { return false };
    signatures.split(' ').any(|sig| {
        let Some(("v1", value)) = sig.split_once(',') else { return false };
        let Ok(given) = STANDARD.decode(value) else { return false };
        let mut mac = Hmac::<Sha256>::new_from_slice(&key).unwrap();
        mac.update(format!("{id}.{timestamp}.").as_bytes());
        mac.update(payload);
        mac.verify_slice(&given).is_ok() // constant-time comparison
    })
}
```

Pass the raw body bytes and the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers. In Axum, take the body as `Bytes` and read headers from `HeaderMap`.


---

# Supabase

Use Delivrie with Supabase: send Supabase Auth emails (sign-up, magic links, password resets) through custom SMTP, and send app email from Edge Functions.

## Send Supabase Auth emails through Delivrie

Supabase's built-in email service is rate-limited and meant for testing. Point Auth at the [SMTP relay](/docs/smtp) so confirmation, magic-link and password-reset emails come from your own domain:

1. In the Supabase dashboard, open **Authentication → Emails → SMTP Settings** and turn on **Enable custom SMTP**.
2. Fill in:

| Field | Value |
| --- | --- |
| Sender email | An address on your verified domain, like `auth@mail.acme.com` |
| Sender name | Your app's name |
| Host | `smtp.delivrie.io` |
| Port | `587` (or `465`) |
| Username | `delivrie` |
| Password | A Delivrie API key (a sending access key is enough) |

3. Save, then raise the email rate limit under **Authentication → Rate Limits** to suit your app.

Every Auth email then shows up in [Emails](https://delivrie.io/emails) with its delivery status.

## Send from an Edge Function

```ts supabase/functions/send-welcome/index.ts
import { Delivrie } from "npm:delivrie";

const delivrie = new Delivrie(Deno.env.get("DELIVRIE_API_KEY"));

Deno.serve(async (req) => {
  const { email, name } = await req.json();
  const { data, error } = await delivrie.emails.send({
    from: "Acme <hello@mail.acme.com>",
    to: email,
    subject: `Welcome, ${name}`,
    html: `<p>Thanks for joining Acme.</p>`,
  }, { idempotencyKey: `welcome-${email}` });

  if (error) return Response.json({ error: error.message }, { status: 502 });
  return Response.json({ id: data.id });
});
```

Set the secret and deploy:

```bash
supabase secrets set DELIVRIE_API_KEY=dlv_your_key
supabase functions deploy send-welcome
```

## Send when a row changes

To email users when something happens in your database (a new order, say), create a Database Webhook in **Database → Webhooks** that calls your Edge Function on `INSERT`. The function receives `{ type, table, record }` and sends the email with `record` fields.

## Webhooks into Supabase

Receive Delivrie events in an Edge Function with `verifyWebhook` from `npm:delivrie`, then write bounces or opens to a table. Deploy it with `--no-verify-jwt`, because Delivrie authenticates with its signature rather than a Supabase JWT:

```bash
supabase functions deploy delivrie-webhooks --no-verify-jwt
```


---

# Cloudflare Workers

Send email from Cloudflare Workers, Pages Functions, Deno and Bun with the Delivrie SDK, which runs on web-standard APIs with no Node.js dependencies.

The `delivrie` SDK uses only `fetch` and Web Crypto, so it runs in Workers without the `nodejs_compat` flag.

```bash
npm install delivrie
npx wrangler secret put DELIVRIE_API_KEY
```

```ts src/index.ts
import { Delivrie, verifyWebhook } from "delivrie";

interface Env {
  DELIVRIE_API_KEY: string;
  DELIVRIE_WEBHOOK_SECRET: string;
}

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const url = new URL(req.url);
    const delivrie = new Delivrie(env.DELIVRIE_API_KEY); // Workers have no process.env: pass the key

    if (url.pathname === "/send" && req.method === "POST") {
      const { email } = await req.json<{ email: string }>();
      const { data, error } = await delivrie.emails.send({
        from: "Acme <hello@mail.acme.com>",
        to: email,
        subject: "Hello from the edge",
        html: "<p>Sent from a Cloudflare Worker.</p>",
      });
      return error ? Response.json(error, { status: 502 }) : Response.json(data);
    }

    if (url.pathname === "/webhooks/delivrie" && req.method === "POST") {
      try {
        const event = await verifyWebhook({ payload: await req.text(), headers: req.headers, secret: env.DELIVRIE_WEBHOOK_SECRET });
        console.log(event.type);
        return new Response("ok");
      } catch {
        return new Response("invalid signature", { status: 400 });
      }
    }

    return new Response("Not found", { status: 404 });
  },
};
```

## Deno and Bun

```ts Deno
import { Delivrie } from "npm:delivrie";
const delivrie = new Delivrie(Deno.env.get("DELIVRIE_API_KEY"));
```

```ts Bun
import { Delivrie } from "delivrie"; // bun add delivrie
const delivrie = new Delivrie(); // reads DELIVRIE_API_KEY from the environment
```

## Vercel Edge and Netlify Edge

Vercel's Edge runtime exposes `process.env`, so `new Delivrie()` picks up `DELIVRIE_API_KEY` from your project settings. On Netlify Edge Functions, pass the key yourself: `new Delivrie(Netlify.env.get("DELIVRIE_API_KEY"))`.


---

# Send an email

Everything about POST /emails: every field, display names, multiple recipients, cc and bcc, reply-to, HTML and text, attachments and inline images, tags, custom headers, scheduling and batch sending.

`POST https://delivrie.io/api/emails` sends one email. It returns as soon as the email is accepted, with its id; delivery happens in the background.

```bash cURL
curl -X POST https://delivrie.io/api/emails \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d '{
    "from": "Acme <orders@mail.acme.com>",
    "to": ["ada@example.com"],
    "subject": "Your order is confirmed",
    "html": "<p>Order <b>#1042</b> is on its way.</p>",
    "tags": [{ "name": "category", "value": "receipt" }]
  }'
```

```ts Node.js
const { data, error } = await delivrie.emails.send({
  from: "Acme <orders@mail.acme.com>",
  to: ["ada@example.com"],
  subject: "Your order is confirmed",
  html: "<p>Order <b>#1042</b> is on its way.</p>",
  tags: [{ name: "category", value: "receipt" }],
}, { idempotencyKey: "order-1042-receipt" });
```

```python Python
res = requests.post(
    "https://delivrie.io/api/emails",
    headers={"Authorization": f"Bearer {key}", "Idempotency-Key": "order-1042-receipt"},
    json={
        "from": "Acme <orders@mail.acme.com>",
        "to": ["ada@example.com"],
        "subject": "Your order is confirmed",
        "html": "<p>Order <b>#1042</b> is on its way.</p>",
        "tags": [{"name": "category", "value": "receipt"}],
    },
)
```

Response:

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

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `from` | string | Yes | `"Name <address@domain>"` or `"address@domain"`. The domain must be verified in your team. |
| `to` | string or string[] | Yes | Up to 50 addresses. |
| `subject` | string | Yes, unless you use `template` | |
| `html` | string | One of `html`, `text` or `template` | |
| `text` | string | | Plain-text version. Generated from `html` when you leave it out. |
| `cc`, `bcc` | string or string[] | | |
| `reply_to` | string or string[] | | Where replies go. |
| `template` | object | | `{ "id": "alias-or-id", "variables": { ... } }`. See [Templates](/docs/templates). |
| `scheduled_at` | string | | When to send. See [Scheduling](#scheduling). |
| `tags` | object[] | | `[{ "name": "...", "value": "..." }]`. Returned in webhook events. |
| `headers` | object | | Custom headers, like `{ "X-Order-Id": "1042" }`. |
| `attachments` | object[] | | See [Attachments](#attachments). |

Send the `Idempotency-Key` header too, so a retried request never sends twice. See [Idempotency and retries](/docs/idempotency).

## Senders and display names

`from` must use a domain you've verified in [Domains](https://delivrie.io/domains), including any subdomain of it. Add a display name in angle-bracket form: `"Acme Support <support@mail.acme.com>"`. If the name has commas or other punctuation, wrap it in quotes: `"\"Acme, Inc.\" <hello@mail.acme.com>"`.

Until your domain is verified, send from `onboarding@delivrie.io` to the [test addresses](/docs/test-mode) and to members of your team.

## Recipients

Each email can have up to 50 addresses in `to`. Everyone in `to` and `cc` sees each other; use `bcc` to hide recipients. To send different content to each person (a receipt per customer, say), send one email each, or up to 100 at a time with [batch sending](#batch-sending).

Addresses on your [suppression list](/docs/suppressions) are skipped automatically. If every recipient is suppressed, the email's status becomes `suppressed` and nothing is sent.

## HTML and plain text

Send `html`, `text`, or both. When you only send `html`, Delivrie builds the plain-text part for you, which helps deliverability. Inline your CSS (most email clients ignore `<style>` blocks), keep the width under about 600px, and use absolute `https://` URLs for images and links.

## Attachments

Attach files as base64 `content`. The total size can be up to 40 MB per email.

```json
"attachments": [
  {
    "filename": "invoice-1042.pdf",
    "content": "JVBERi0xLjcKJc...",
    "content_type": "application/pdf"
  }
]
```

| Field | Notes |
| --- | --- |
| `filename` | Required. Shown to the recipient. |
| `content` | Required. Base64-encoded file. (The Node.js SDK also accepts a `Buffer` or `Uint8Array`.) |
| `content_type` | Optional. Worked out from the filename when you leave it out. |
| `content_id` | Optional. Set it to show the file inline (see below). |

Attachments by URL (`path`) aren't supported yet. Download the file and send its contents instead.

### Inline images

Give the attachment a `content_id` and reference it in your HTML with `cid:`:

```json
{
  "html": "<p>Your QR code:</p><img src=\"cid:qr-1042\" width=\"200\">",
  "attachments": [{ "filename": "qr.png", "content": "iVBORw0KGgo...", "content_id": "qr-1042" }]
}
```

## Tags

Tags label emails so you can find them later and route webhook events. Names and values can use ASCII letters, numbers, `_` and `-`, up to 256 characters each.

```json
"tags": [{ "name": "category", "value": "password_reset" }, { "name": "user_id", "value": "u_8812" }]
```

Tags come back in every webhook event as an object: `"tags": { "category": "password_reset", "user_id": "u_8812" }`.

## Custom headers

```json
"headers": { "X-Order-Id": "1042", "List-Unsubscribe": "<https://acme.com/unsubscribe?u=8812>" }
```

Delivrie builds `From`, `To`, `Cc`, `Bcc`, `Subject`, `Date`, `MIME-Version` and the content headers from your fields, and ignores those names in `headers`. Header values can't contain line breaks.

## Scheduling

Set `scheduled_at` to send later, up to 30 days ahead. It accepts:

- an ISO 8601 date: `"2026-12-01T09:00:00Z"` or `"2026-12-01T10:00:00+01:00"`
- a phrase, read as UTC: `"in 10 minutes"`, `"in 2 hours"`, `"tomorrow at 9am"`

The email gets status `scheduled`. Change the time with `PATCH /emails/:id` and `{ "scheduled_at": "..." }`, or cancel it with `POST /emails/:id/cancel`, any time before it sends. Times less than 30 seconds away send right away.

## Batch sending

`POST /emails/batch` takes an array of up to 100 emails, each with its own recipients and content, and returns their ids in the same order:

```bash
curl -X POST https://delivrie.io/api/emails/batch \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: digest-2026-11-14" \
  -d '[
    { "from": "Acme <hi@mail.acme.com>", "to": "ada@example.com", "subject": "Your digest", "html": "<p>Hi Ada</p>" },
    { "from": "Acme <hi@mail.acme.com>", "to": "sam@example.com", "subject": "Your digest", "html": "<p>Hi Sam</p>" }
  ]'
```

```json
{ "data": [{ "id": "4ef9a417-..." }, { "id": "9a1c22b0-..." }] }
```

Batch emails can't have attachments or `scheduled_at`. If any email in the batch is invalid, the whole batch is rejected and nothing is sent, so you can fix it and retry. To send the same email to a list of subscribers, use [broadcasts](/docs/broadcasts) instead.

## After you send

- Check status in [Emails](https://delivrie.io/emails), or with `GET /emails/:id`, which returns the email and its events. See [Statuses and events](/docs/email-status).
- Get pushed updates with [webhooks](/docs/webhooks).
- If a send fails, the response says why. See [Errors](/docs/errors).


---

# Idempotency and retries

Make email sends safe to retry with the Idempotency-Key header, choose good keys, and know which errors to retry.

Networks fail. If your request times out, you can't tell whether the email went out. Send an `Idempotency-Key` header, and retrying with the same key returns the original email instead of sending a second one.

```bash
curl -X POST https://delivrie.io/api/emails \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d '{ "from": "Acme <orders@mail.acme.com>", "to": "ada@example.com", "subject": "Receipt", "html": "<p>Thanks!</p>" }'
```

The first request sends the email and returns `{ "id": "..." }`. Every later request with the same key, from the same team, returns the same `id` and sends nothing, even if the body changed.

## Choosing keys

Build the key from the business event the email belongs to, not from a random value made at send time:

| Email | Good key |
| --- | --- |
| Order receipt | `order-1042-receipt` |
| Welcome email | `welcome-user-8812` |
| Password reset | `reset-8812-2026-11-14T10:05` (one per reset request) |
| Weekly digest | `digest-user-8812-2026-w46` |

Keep keys under 256 characters. They're kept with the email, so the same key never sends twice for your team, however much later you retry. Use a new key when you really do want to send again.

Batch sends take one key for the whole batch (`POST /emails/batch` with `Idempotency-Key: digest-2026-11-14`). Retrying the batch returns the same ids in the same order.

## When to retry

| Response | What to do |
| --- | --- |
| `2xx` | Done. |
| Network error or timeout | Retry with the same key, with backoff (1s, 2s, 4s...). |
| `5xx` | Retry with the same key, with backoff. |
| `429` with `daily_quota_exceeded`, `monthly_quota_exceeded` or `spending_cap_reached` | Don't retry. It won't succeed until the limit resets or your plan changes. Alert someone. |
| `4xx` (anything else) | Don't retry. Fix the request; the `message` says what's wrong. |

The [Node.js SDK](/docs/sdks) does this for you: pass `idempotencyKey` and it retries network errors and `5xx` responses up to twice. Without a key, it never retries a send.

## Queues and background jobs

If you send from a job queue (BullMQ, Sidekiq, Celery, Laravel queues, Inngest, Trigger.dev), derive the key from the job's identity, not the attempt. The queue can then retry the job freely and the customer still gets one email.

```ts
worker.process("send-receipt", async (job) => {
  const { error } = await delivrie.emails.send(receiptFor(job.data.orderId), {
    idempotencyKey: `order-${job.data.orderId}-receipt`,
  });
  if (error && error.statusCode >= 500) throw new Error(error.message); // let the queue retry
});
```

## SMTP

Messages sent through the [SMTP relay](/docs/smtp) are deduplicated by their `Message-ID` header, so an app that retries an SMTP send doesn't send twice.


---

# Templates

Create reusable email templates with variables and fallbacks, publish versions, and send them from the API by id or alias.

Templates keep email design out of your code. Build them in the dashboard's visual or HTML editor (or with the API), publish a version, and send by alias with just the data that changes.

## Create and publish

1. Open [Templates](https://delivrie.io/templates) and click **Create template**. Start from blank or from one of the ready-made templates (below).
2. Give it an **alias**, a stable name your code sends by, like `order-confirmation`.
3. Write the subject and body using variables (below), set a default From address, and click **Publish**.

Or with the API:

```bash
curl -X POST https://delivrie.io/api/templates \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order confirmation",
    "alias": "order-confirmation",
    "from": "Acme <orders@mail.acme.com>",
    "subject": "Order {{order_id}} confirmed",
    "html": "<p>Hi {{first_name|there}},</p><p>Order {{order_id}} is on its way.</p>"
  }'

curl -X POST https://delivrie.io/api/templates/order-confirmation/publish \
  -H "Authorization: Bearer $DELIVRIE_API_KEY"
```

Only published versions can be sent. Editing a template doesn't change what's sent until you publish again, and every publish is kept in the version history so you can roll back.

## Ready-made templates

Delivrie includes 22 designed templates you can start from, each with its variables already set up:

| Category | Templates |
| --- | --- |
| Account | Welcome, Verify email, Sign-in link, Team invitation, Account closed |
| Security | Verification code, Password reset, Password changed, New sign-in alert |
| Billing | Payment receipt, Invoice, Payment failed, Trial ending, Subscription renewed |
| Commerce | Order confirmation, Order shipped, Cart reminder |
| Marketing | Newsletter, Product announcement, Feedback request, Event invitation, We miss you |

They use a card layout: your logo above a white card, the content inside it, and the footer below. They're built with email-safe table layouts and adapt to phone screens. Everything is editable after you create one. Transactional templates have no unsubscribe link; marketing ones do.

## Brand kit

On the Starter plan and above, set your brand once in [Settings → Brand](https://delivrie.io/settings/brand): logo, button and text colours, background, font, button corners, postal address, support email and social links. New templates are created with your brand already applied. To restyle a template or broadcast you already have, open it, click **Styles**, then **Apply brand kit**.

Use a PNG or JPG logo, at least twice the height it's shown at so it stays sharp on high-resolution screens. Most email apps don't show SVG images.

## Send a template

Pass `template` instead of `html`/`text`. `subject` and `from` are optional; the template's defaults are used when you leave them out.

```bash cURL
curl -X POST https://delivrie.io/api/emails \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "ada@example.com",
    "template": {
      "id": "order-confirmation",
      "variables": { "first_name": "Ada", "order_id": "#1042" }
    }
  }'
```

```ts Node.js
await delivrie.emails.send({
  from: "Acme <orders@mail.acme.com>",
  to: "ada@example.com",
  template: { id: "order-confirmation", variables: { first_name: "Ada", order_id: "#1042" } },
}); // `subject` comes from the template
```

```python Python
requests.post("https://delivrie.io/api/emails", headers=auth, json={
    "to": "ada@example.com",
    "template": {"id": "order-confirmation", "variables": {"first_name": "Ada", "order_id": "#1042"}},
})
```

`template.id` takes the template's id or its alias.

## Variables

| Syntax | Inserts | Use for |
| --- | --- | --- |
| `{{first_name}}` | The value, HTML-escaped | Anything a user typed: names, messages, addresses |
| `{{{reset_url}}}` | The value exactly as given | HTML snippets and URLs you build yourself |
| `{{first_name\|there}}` | The value, or `there` if it's missing or empty | Friendly fallbacks |

Variables work in the subject, the HTML and the text version. Missing variables without a fallback become an empty string. You can also set a default fallback for each variable in the template editor.

> **Warning:** Never put user input in a `{{{triple}}}` variable. It's inserted unescaped, so someone could inject HTML into your email.

## Broadcast and automation variables

In [broadcasts](/docs/broadcasts), variables come from the contact: `{{first_name}}`, `{{last_name}}`, `{{email}}` and any [contact property](/docs/contacts), like `{{plan}}`. `{{{unsubscribe_url}}}` inserts the recipient's unsubscribe link.

In [automations](/docs/automations), templates can also use the data sent with the triggering event.

## List and fetch

- `GET /templates` lists templates with their alias and status.
- `GET /templates/:id` (id or alias) returns one template.


---

# Test addresses

Test deliveries, bounces, complaints and suppressions with Delivrie's test addresses, without risking your sender reputation.

Send to these addresses to test your integration end to end. They go through the full pipeline, so you get real statuses and real [webhook](/docs/webhooks) events, but no real inbox receives them and they never hurt your reputation.

| Address | What happens | Events you get |
| --- | --- | --- |
| `delivered@test.delivrie.io` | Accepted and delivered | `email.sent`, `email.delivered` |
| `bounced@test.delivrie.io` | Rejected as a hard bounce | `email.sent`, `email.bounced` |
| `complained@test.delivrie.io` | Delivered, then marked as spam | `email.sent`, `email.delivered`, `email.complained` |
| `suppressed@test.delivrie.io` | Rejected as if on the provider's suppression list | `email.sent`, `email.bounced` |

Use the addresses exactly as written. Variations like `delivered+signup@test.delivrie.io` aren't test addresses and would be sent for real.

## Who can send to them

Send from a verified domain, or from the shared sender `onboarding@delivrie.io` before you've verified one.

## Things to know

- Test sends count toward your plan's allowance like any other email.
- Bounces and complaints from test addresses are **not** added to your suppression list, so you can repeat tests.
- Use them in CI: they give you a real round trip (send, then webhook) without emailing anyone.

```ts
// A test that checks your bounce handling end to end
await delivrie.emails.send({
  from: "Acme <onboarding@delivrie.io>",
  to: "bounced@test.delivrie.io",
  subject: "Bounce test",
  text: "This should bounce.",
});
// Your webhook endpoint should receive email.bounced within a few seconds.
```


---

# Statuses and events

What each email status means (queued, sent, delivered, bounced, complained and more), how to read an email's event history, and how statuses map to webhook events.

Every email has a status (`last_event` in the API) and a history of events. Check them in [Emails](https://delivrie.io/emails), with `GET /emails/:id`, or as they happen with [webhooks](/docs/webhooks).

## Statuses

| Status | Meaning | Final? |
| --- | --- | --- |
| `scheduled` | Waiting for its `scheduled_at` time | No |
| `queued` | Accepted and about to be handed to the mail servers | No |
| `sent` | Delivrie's mail servers accepted it and are delivering it | No |
| `delivery_delayed` | The recipient's server is temporarily refusing it; Delivrie keeps retrying | No |
| `delivered` | The recipient's mail server accepted it | Yes, unless opened or clicked later |
| `opened` | The recipient opened it (needs open tracking on the domain) | |
| `clicked` | The recipient clicked a link (needs click tracking on the domain) | |
| `bounced` | The recipient's server rejected it | Yes |
| `complained` | The recipient marked it as spam | Yes |
| `failed` | It couldn't be sent, for example because the domain stopped being verified. `error` says why | Yes |
| `canceled` | A scheduled email you canceled | Yes |
| `suppressed` | Every recipient was on your [suppression list](/docs/suppressions), so nothing was sent | Yes |

`delivered` means the receiving server accepted the message. Whether it lands in the inbox or spam folder is up to the receiving provider; the [Deliverability guide](/docs/deliverability) covers how to stay in the inbox.

## Event history

`GET /emails/:id` returns the email with every event:

```json
{
  "object": "email",
  "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
  "from": "Acme <orders@mail.acme.com>",
  "to": ["ada@example.com"],
  "subject": "Your order is confirmed",
  "last_event": "delivered",
  "created_at": "2026-11-14T09:12:04Z",
  "events": [
    { "type": "sent", "data": { "message_id": "0102019..." }, "created_at": "2026-11-14T09:12:05Z" },
    { "type": "delivered", "data": { "smtp_response": "250 2.0.0 OK", "latency_ms": 812 }, "created_at": "2026-11-14T09:12:06Z" }
  ]
}
```

Bounce events include the type (`Permanent` or `Transient`), the sub-type and the receiving server's message, which usually says exactly why: a mailbox that doesn't exist, a full inbox, or a blocked sender.

## Bounces and complaints

- A **permanent bounce** (the address doesn't exist) adds the address to your suppression list, so you don't send to it again.
- A **transient bounce** (mailbox full, server busy) doesn't suppress the address.
- A **complaint** suppresses the address and unsubscribes the contact from broadcasts.

## Webhook events

| Status | Webhook event |
| --- | --- |
| `sent` | `email.sent` |
| `delivered` | `email.delivered` |
| `delivery_delayed` | `email.delivery_delayed` |
| `opened` | `email.opened` |
| `clicked` | `email.clicked` |
| `bounced` | `email.bounced` |
| `complained` | `email.complained` |
| `failed` | `email.failed` |

## Retention

After 30 days, an email's HTML, text and attachments are deleted. Its recipients, subject, status and events stay, so logs and metrics keep working.

Email content is kept for 30 days on every plan, for both sent and received email. Enterprise plans can keep it longer.

Use webhooks to keep your own copy if you need it longer.


---

# Errors

Every Delivrie API error, what causes it and how to fix it, with the JSON error format and which errors are safe to retry.

Errors use standard HTTP status codes and a JSON body:

```json
{
  "statusCode": 422,
  "name": "validation_error",
  "message": "The from domain mail.acme.com is not verified yet (status: pending)."
}
```

Branch on `name` in code and show `message` to people: it's written to say exactly what went wrong. Every request, including failed ones, appears in [Logs](https://delivrie.io/logs) with its request and response bodies.

## Error reference

| Status | `name` | Cause | Fix |
| --- | --- | --- | --- |
| 401 | `missing_api_key` | No `Authorization` header | Add `Authorization: Bearer dlv_...` |
| 401 | `invalid_api_key` | The key doesn't exist or was deleted | Check the key; create a new one in [API keys](https://delivrie.io/api-keys) |
| 403 | `restricted_api_key` | A sending-only key called another endpoint, or sent from a domain it isn't allowed to use | Use a full access key, or send from the key's domain |
| 403 | `plan_limit_reached` | You've reached your plan's domain or webhook limit | Remove one, or upgrade in [Billing](https://delivrie.io/billing) |
| 403 | `sending_paused` | Sending is paused because your bounce or complaint rate went over the limit (see [Deliverability](/docs/deliverability)) | Fix the cause, then email support@delivrie.io to resume |
| 403 | `insufficient_scope` | An MCP or OAuth connection wasn't granted this scope | Reconnect and approve the scope |
| 404 | `not_found` | Nothing with that id in this team | Check the id, and that the key belongs to the right team |
| 409 | `domain_exists` | The domain is already in this team | Use the existing domain |
| 409 | `domain_in_use` | Another team owns the domain | Claim it from the Domains page if it's yours |
| 422 | `validation_error` | A field is missing or invalid, or the `from` domain isn't verified | Read `message`; it names the field |
| 429 | `daily_quota_exceeded` | Free plan: 133 emails today | Wait until midnight UTC, buy credits or upgrade |
| 429 | `monthly_quota_exceeded` | Free plan: 4,000 emails this month | Buy credits or upgrade |
| 429 | `spending_cap_reached` | This send would take overage past your spending cap | Raise or remove the cap in [Billing](https://delivrie.io/billing) |
| 500 | `application_error` | Something failed on our side | Retry with the same idempotency key |
| 503 | `sending_not_configured` | Sending is temporarily unavailable | Retry later; check [status](https://delivrie.io/status) |

## Common `validation_error` messages

| Message | What to do |
| --- | --- |
| Request body must be valid JSON | Send a JSON body with `Content-Type: application/json` |
| Missing from / to / subject field | Add the field |
| Provide html or text | Add a body, or send a `template` |
| The from domain X is not verified | Add and verify the domain in [Domains](https://delivrie.io/domains), or fix a typo in `from` |
| X can only send to members of your team | You're using `onboarding@delivrie.io`. Verify your own domain to email anyone |
| to can have at most 50 addresses | Split the send, or use [batch sending](/docs/send-email) |
| Attachments are limited to 40 MB per email | Send a link to the file instead |
| Attachment path isn't supported yet | Send base64 `content` |
| scheduled_at must be an ISO 8601 date or a phrase... | Use `2026-12-01T09:00:00Z` or a phrase like `in 1 hour` |
| Template X has no published version | Publish the template |
| Tag names and values can only contain... | Use letters, numbers, `_` and `-` only |

## Retrying

Retry `5xx` errors and network failures with the same `Idempotency-Key`. Don't retry `4xx` errors, including quota `429`s; they won't succeed until something changes. See [Idempotency and retries](/docs/idempotency).

## Errors in the SDK

The [Node.js SDK](/docs/sdks) returns errors instead of throwing: `const { data, error } = await delivrie.emails.send(...)`. `error` has the same `statusCode`, `name` and `message`. Problems that never reach the API have `statusCode: 0` and the name `network_error`, `timeout` or `aborted`.


---

# CORS and browser apps

Why you shouldn't call the Delivrie API from the browser, and how to send email from React, Vue, mobile and no-code front ends through a small server route instead.

If you call `https://delivrie.io/api` from code that runs in a browser or mobile app, anyone can open developer tools, copy your API key and send email as you. So keep the key on a server.

## Send through a server route

Put the API call in code you control on the server, and have your front end call that:

```ts app/api/contact/route.ts (Next.js)
import { Delivrie } from "delivrie";

const delivrie = new Delivrie(process.env.DELIVRIE_API_KEY);

export async function POST(req: Request) {
  const { email, message } = await req.json();
  if (!email || !message) return Response.json({ error: "Missing fields" }, { status: 400 });

  const { error } = await delivrie.emails.send({
    from: "Website <forms@mail.acme.com>",
    to: "team@acme.com",
    replyTo: email,
    subject: "New message from the website",
    text: message,
  });
  return error ? Response.json({ error: error.message }, { status: 502 }) : Response.json({ ok: true });
}
```

```ts Front end
await fetch("/api/contact", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, message }),
});
```

Good places for that server code: a Next.js route handler or Server Action, a [Supabase Edge Function](/docs/supabase), a [Cloudflare Worker](/docs/cloudflare-workers), a Vercel or Netlify function, Firebase Cloud Functions, or your own backend.

## Protect the route

A public route that sends email can be abused too. Before sending:

- Send to fixed addresses you control (like your team inbox) rather than an address from the request, or only to the signed-in user's own address.
- Rate-limit by IP or user.
- Add a CAPTCHA (Turnstile, hCaptcha or reCAPTCHA) to public forms.
- Use a [sending access key](/docs/api-keys) limited to one domain.

## No-code and AI app builders

Lovable, Bolt, v0, Replit and similar tools can generate the server route for you. Ask them to "send email from a server function using the Delivrie API, reading DELIVRIE_API_KEY from secrets, never from the browser". See [Build with AI](/docs/build-with-ai) for prompts.


---

# SMTP

Send through Delivrie's SMTP relay from WordPress, Laravel, Django, Rails, Ghost, Supabase Auth, Nodemailer and anything else that speaks SMTP.

Anything that can send over SMTP can send through Delivrie: CMSs, frameworks, no-code tools, printers and legacy apps. SMTP mail gets the same limits, logs, webhooks and suppressions as the API.

## Settings

| Setting | Value |
| --- | --- |
| Host | `smtp.delivrie.io` |
| Port | `587` with STARTTLS, or `465` with SSL/TLS |
| Alternative ports | `2587` (STARTTLS) and `2465` (SSL/TLS), for hosts that block the usual ones |
| Username | `delivrie` |
| Password | A Delivrie API key (`dlv_...`). A sending access key is enough |
| Encryption | Required. On 587 choose STARTTLS (sometimes called TLS); on 465 choose SSL/TLS (sometimes called SSL or SMTPS) |

The `From` address must be on a verified domain, the same as with the API.

## Examples

```js Nodemailer
const transport = nodemailer.createTransport({
  host: "smtp.delivrie.io",
  port: 587,
  secure: false, // upgrades with STARTTLS
  auth: { user: "delivrie", pass: process.env.DELIVRIE_API_KEY },
});
```

```bash Laravel .env
MAIL_MAILER=smtp
MAIL_HOST=smtp.delivrie.io
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=delivrie
MAIL_PASSWORD=dlv_your_key
```

```python Django
EMAIL_HOST = "smtp.delivrie.io"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "delivrie"
EMAIL_HOST_PASSWORD = os.environ["DELIVRIE_API_KEY"]
```

```ruby Rails
config.action_mailer.smtp_settings = {
  address: "smtp.delivrie.io", port: 587, user_name: "delivrie",
  password: ENV.fetch("DELIVRIE_API_KEY"), authentication: :plain, enable_starttls_auto: true,
}
```

```bash swaks (testing)
swaks --server smtp.delivrie.io:587 --tls \
  --auth-user delivrie --auth-password "$DELIVRIE_API_KEY" \
  --from hello@mail.acme.com --to delivered@test.delivrie.io
```

Step-by-step setup for [Supabase Auth](/docs/supabase), [WordPress and Laravel](/docs/php), [Django](/docs/python) and [Rails](/docs/ruby) is in their guides.

## What's supported

- To, Cc and Bcc come from the message and the SMTP envelope.
- Attachments are kept, up to 40 MB per message.
- Custom `X-` headers and `List-Unsubscribe` are passed through.
- Tag a message with an `X-Delivrie-Tags` header: `X-Delivrie-Tags: source=wordpress, order`. Tags appear in the dashboard and in webhook events.
- Each message is sent once even if your app retries, based on its `Message-ID`.

## SMTP replies

| Reply | Meaning | What to do |
| --- | --- | --- |
| `535` | Authentication failed | The username must be `delivrie` and the password a valid API key |
| `550` | The API rejected the message | The reply says why, for example an unverified From domain |
| `452` | A sending limit was reached | Retry later, or check your plan in [Billing](https://delivrie.io/billing) |

After five failed logins from one IP address, logins from that address are blocked for 15 minutes.

## Troubleshooting connections

- **Timeouts:** some hosts (DigitalOcean, Google Cloud, some home ISPs) block outbound ports 25, 465 and 587. Use port `2587` or `2465`.
- **TLS errors on 465:** your client is trying STARTTLS on an SSL port. Choose SSL/TLS, or switch to 587.
- **"Must issue a STARTTLS command first":** turn on encryption. Plain-text logins aren't accepted.


---

# Receiving email

Receive email on your domain with Delivrie: set up the MX record, choose which addresses accept mail, get email.received webhooks, read messages with the API and forward them.

Delivrie can receive email for your domain: replies to your app's emails, a `support@` address, inbound parsing for tickets or uploads. Every received message is stored, sent to your webhooks as `email.received`, and grouped into conversations in the [Inbox](/docs/inbox).

## Set it up

1. Open your domain in [Domains](https://delivrie.io/domains) and turn on **Receiving**.
2. Pick where mail arrives:
   - **A subdomain** such as `in.acme.com` (recommended). Your normal email at `acme.com`, like Google Workspace, keeps working.
   - **The domain itself.** Only do this if nothing else receives mail for it, because its MX record will point at Delivrie.
3. Choose which addresses accept mail: **all addresses** (`anything@in.acme.com`) or **only specific addresses** (mail to anything else is dropped).
4. Add the `MX` record Delivrie shows, priority `10`, and click **Verify DNS records**.

> **Warning:** Adding Delivrie's MX record to a domain that already receives mail elsewhere (Google Workspace, Microsoft 365, Zoho) sends that mail to Delivrie instead. Use a subdomain unless you mean to move your inbox.

You can also configure receiving with [`PATCH /domains/:id`](/docs/api/update-domain):

```json
{
  "receiving_enabled": true,
  "receiving_subdomain": "in",
  "receiving_mode": "specific",
  "receiving_addresses": ["support@in.acme.com", "billing@in.acme.com"]
}
```

## Get received mail as a webhook

Add a [webhook](/docs/webhooks) subscribed to `email.received`:

```json
{
  "type": "email.received",
  "created_at": "2026-11-14T10:22:31.000Z",
  "data": {
    "email_id": "a5c3e1f0-...",
    "from": "Ada Lovelace <ada@example.com>",
    "to": ["support@in.acme.com"],
    "subject": "Re: Your order is confirmed",
    "created_at": "2026-11-14T10:22:30.000Z",
    "message_id": "<CAF=abc123@mail.gmail.com>",
    "attachments": [{ "filename": "photo.jpg", "content_type": "image/jpeg", "size": 248213 }]
  }
}
```

Fetch the full message, with its HTML and text, using `GET /emails/:email_id`.

## Read received mail with the API

```bash
# Newest first; filter by the address it was sent to
curl "https://delivrie.io/api/emails/received?to=support@in.acme.com&limit=20" \
  -H "Authorization: Bearer $DELIVRIE_API_KEY"
```

`GET /emails?direction=inbound` lists received mail too.

## Reply and forward

- **Reply** from the [Inbox](/docs/inbox), or with `POST /inbox/threads/:id/reply`. Delivrie sets `In-Reply-To` and `References`, so the reply lands in the same conversation in the sender's mail app.
- **Forward** a received email with `POST /emails/:id/forward` and `{ "to": "ops@acme.com", "from": "Acme <support@mail.acme.com>" }`.

## Make your app's emails replyable

Set `reply_to` to a receiving address when you send, and customer replies come back to Delivrie:

```json
{ "from": "Acme <orders@mail.acme.com>", "reply_to": "support@in.acme.com", "to": "ada@example.com", "subject": "Your order is confirmed", "html": "..." }
```

## How long received mail is kept

Received email and Inbox replies are kept for 30 days on every plan. After that the message body and attachments are deleted; the sender, subject and thread stay. Save anything you need longer from the `email.received` webhook.

## Spam and security checks

Each received email's `received` event records the receiving server's spam, virus, SPF, DKIM and DMARC verdicts. Check them before acting on mail automatically, especially for messages that trigger actions in your app.


---

# Inbox

A shared inbox for received email: conversations grouped into threads, labels, archiving, replies from the dashboard or API, and AI agents that answer through MCP.

The [Inbox](https://delivrie.io/inbox) groups [received email](/docs/receiving) into conversations so your team, or an AI agent, can read and reply in one place.

## How threads work

A message joins an existing thread when it replies to an earlier message (its `In-Reply-To` or `References` header points at one), or when the same person writes to the same address with the same subject within 30 days. Otherwise it starts a new thread. Replies you send from the Inbox join their thread.

Each thread has a mailbox (the address mail arrived at), a contact (the other person), a subject, a snippet of the latest message, unread and open/archived status, labels, and `needs_reply`, which is `true` when the latest message is from the contact.

## API

| Request | What it does |
| --- | --- |
| `GET /inbox/threads` | List threads, newest first. Filters: `status` (`open`, the default, `archived` or `all`), `unread=true`, `needs_reply=true`, `mailbox`, `label`, `q` (searches subject, contact and snippet), `limit` |
| `GET /inbox/threads/:id` | A thread with its messages (up to 100), as text |
| `POST /inbox/threads/:id/reply` | Reply with `{ "text": "..." }` or `{ "html": "..." }`. Optional `from`; defaults to the mailbox address |
| `PATCH /inbox/threads/:id` | Change `status` (`open` or `archived`), `unread` (boolean) or `labels` (names; new labels are created) |
| `GET /inbox/labels` | List labels |

```bash
# Threads waiting for an answer
curl "https://delivrie.io/api/inbox/threads?needs_reply=true" -H "Authorization: Bearer $DELIVRIE_API_KEY"

# Reply, then archive
curl -X POST https://delivrie.io/api/inbox/threads/THREAD_ID/reply \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "text": "Thanks Ada, your refund is on its way." }'

curl -X PATCH https://delivrie.io/api/inbox/threads/THREAD_ID \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "archived", "labels": ["refunds"] }'
```

Plain-text replies are wrapped in simple HTML for you. The reply's subject gets `Re:` and the right threading headers, so it stays in the same conversation in the customer's mail app.

## Let an AI agent handle support

Connect an assistant to the [MCP server](/docs/mcp) and it can work the inbox with the `list_inbox_threads`, `get_inbox_thread`, `reply_to_thread` and `update_thread` tools. For example, in Claude:

```text
Check my Delivrie inbox for threads that need a reply. For each one, read it,
draft an answer using our refund policy (below), and show me the drafts before
sending. Archive and label "done" any thread you answer.
```

Approve the `read` and `send` scopes, and leave out `manage`, if the agent should read and reply but not change your account.


---

# Domains and DNS

Add and verify a sending domain: which DNS records Delivrie needs (DKIM, SPF return path, DMARC, MX for receiving), how to enter them at common DNS providers, tracking and TLS settings.

To send from your own address, add the domain to Delivrie and publish a few DNS records that prove you own it and let mailbox providers trust your mail.

## Use a subdomain

Send from a subdomain such as `mail.acme.com` or `notify.acme.com` rather than `acme.com`. Your app's email then builds its own reputation, and a problem with it can't affect the mail your team sends from `acme.com`. Customers still see whatever `from` name and address you choose, like `Acme <orders@mail.acme.com>`.

## Add the domain

In [Domains](https://delivrie.io/domains/new), enter the domain and click **Add domain**. Or with the API:

```bash
curl -X POST https://delivrie.io/api/domains \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "mail.acme.com" }'
```

The response lists the records to add. Options: `return_path` (bounce subdomain, default `send`), `open_tracking` and `click_tracking` (both off by default). Mail is sent from Ireland (`eu-west-1`).

## The DNS records

For `mail.acme.com`, you'll see records like these:

| Purpose | Type | Name | Value |
| --- | --- | --- | --- |
| DKIM (signs your mail) | `TXT` | `<selector>._domainkey.mail.acme.com` | `p=MIGfMA0GCSq...` (your public key) |
| Return path: bounces | `MX` | `send.mail.acme.com` | `feedback-smtp.eu-west-1.amazonses.com`, priority `10` |
| Return path: SPF | `TXT` | `send.mail.acme.com` | `v=spf1 include:_spf.delivrie.io ~all` |
| DMARC (recommended) | `TXT` | `_dmarc.mail.acme.com` | `v=DMARC1; p=none;` |
| Receiving (optional) | `MX` | `mail.acme.com` or your receiving subdomain | `inbound-smtp.eu-west-1.amazonaws.com`, priority `10` |

The `feedback-smtp...amazonses.com` and `inbound-smtp...amazonaws.com` hosts belong to Delivrie's mail infrastructure. Use the exact values from your dashboard; the DKIM key is unique to your domain. **Copy records as text** in the domain's menu gives you all of them at once.

## Entering records at your DNS provider

Most providers add your root domain to the name automatically. If your DNS zone is `acme.com`, enter only the part before it:

| Full name | What to type in the Name / Host field |
| --- | --- |
| `<selector>._domainkey.mail.acme.com` | `<selector>._domainkey.mail` |
| `send.mail.acme.com` | `send.mail` |
| `_dmarc.mail.acme.com` | `_dmarc.mail` |

Provider notes:

- **Cloudflare:** set every record to **DNS only** (grey cloud). MX and TXT records can't be proxied anyway.
- **GoDaddy, Namecheap, Hostinger:** use the short names above. Namecheap lists MX records under **Mail Settings → Custom MX**.
- **Route 53, Google Cloud DNS:** enter the full name, and wrap TXT values in double quotes.
- **Vercel DNS:** enter the short name; Vercel adds the domain.

## Verify

Click **Verify DNS records** (or `POST /domains/:id/verify`). Each record shows its own status. Most providers update within minutes; some take up to 72 hours. Delivrie also re-checks pending domains in the background and sends a `domain.updated` webhook when the status changes.

Statuses: `not_started` (records not found yet), `pending` (some found), `verified` (ready to send), `failed` or `temporary_failure` (a record was found but is wrong; fix it and verify again).

Stuck? See [Why isn't my domain verifying?](/docs/domain-not-verifying)

## Settings

Change these on the domain's page or with `PATCH /domains/:id`:

| Setting | What it does |
| --- | --- |
| `open_tracking` | Adds an invisible image to count opens. Off by default |
| `click_tracking` | Rewrites links to count clicks. Off by default |
| `tls` | `opportunistic` (default) uses TLS when the receiving server supports it; `enforced` only delivers over TLS |
| `return_path` | The bounce subdomain label, default `send`. Changing it gives you new SPF records to add |

> **Note:** Open tracking is approximate. Apple Mail and some corporate filters load images automatically, which counts as an open even if nobody read the email.

## Several domains, several teams

Each domain belongs to one team. To use the same domain in another team, delete it from the first, or start a **claim** from the other team's Domains page, which proves ownership with a DNS record and moves it.


---

# Why isn't my domain verifying?

Fix a Delivrie domain stuck on pending or failed: doubled record names, split DKIM values, duplicate SPF records, Cloudflare proxying, propagation, and how to check DNS yourself.

Work through these in order. Most stuck domains have one of the first three problems.

## 1. The record name is doubled

Many DNS providers add your domain to the end of the name. If you type the full name, you get `<selector>._domainkey.mail.acme.com.acme.com`.

Fix: type only the part before your root domain, like `<selector>._domainkey.mail`. See [Entering records at your DNS provider](/docs/domains).

## 2. The DKIM value was changed

The DKIM `TXT` value is long. Some providers split it or add quotes or spaces.

Fix: paste the whole value, starting with `p=`, as a single string. If your provider needs long values split, split it into quoted chunks with no spaces inside the key.

## 3. Two SPF records on the same name

A name can only have one SPF (`v=spf1`) record. If `send.mail.acme.com` already has one, from Resend or another provider, the check fails.

Fix: delete the old record, or set a different return path in the domain's settings (for example `bounces`) and add the new SPF records there.

## 4. Cloudflare is proxying

Records set to **Proxied** (orange cloud) don't resolve as written.

Fix: switch each Delivrie record to **DNS only** (grey cloud).

## 5. DNS hasn't updated yet

Changes usually show up within minutes, but some providers take hours, and up to 72 hours in rare cases.

Fix: wait, then click **Verify DNS records**. Delivrie also keeps checking pending domains in the background, and sends a `domain.updated` webhook when the status changes.

## Check DNS yourself

Look the records up from your computer:

```bash
dig +short TXT <selector>._domainkey.mail.acme.com
dig +short MX send.mail.acme.com
dig +short TXT send.mail.acme.com
```

Or use a web tool such as [Google's dig](https://toolbox.googleapps.com/apps/dig/). If the answer is empty, the record isn't live yet or the name is wrong. If it shows a different value, fix the value.

Still stuck after checking all of these? Use the chat button in the dashboard, and include the domain name. We'll look at your DNS with you.


---

# DMARC

Set up DMARC for your sending domain, roll it out safely from p=none to p=reject, and meet Gmail and Yahoo's bulk sender requirements.

DMARC tells mailbox providers what to do with mail that claims to be from your domain but fails SPF and DKIM checks, and where to send reports about it. Gmail, Yahoo and Microsoft require it for bulk senders, and it helps everyone else reach the inbox.

## Add the record

Add a `TXT` record at `_dmarc` on your sending domain (for `mail.acme.com`, the name is `_dmarc.mail.acme.com`):

```text
v=DMARC1; p=none; rua=mailto:dmarc-reports@acme.com
```

| Tag | Meaning |
| --- | --- |
| `p` | Policy: `none` (monitor only), `quarantine` (send failures to spam) or `reject` (block failures) |
| `rua` | Where providers send daily aggregate reports |
| `pct` | Optional: apply the policy to this percentage of failing mail, for gradual rollout |

If your root domain (`acme.com`) already has a DMARC record, it covers subdomains too, unless the subdomain has its own.

## Roll it out

1. Start with `p=none` and collect reports for two to four weeks. A free report reader (Postmark's DMARC tool, dmarcian, EasyDMARC) turns the XML into something readable.
2. Check that everything sending as your domain passes: Delivrie, your workspace email, your CRM, your helpdesk. Set up DKIM for any that fail.
3. Move to `p=quarantine`, optionally with `pct=25` at first.
4. Finish at `p=reject`.

Mail sent through Delivrie from a verified domain passes DMARC: it's DKIM-signed with your domain, and the return path on your domain passes SPF.

## Gmail and Yahoo requirements

If you send more than 5,000 emails a day to Gmail or Yahoo addresses, they require:

- SPF and DKIM (Delivrie sets both up when you verify the domain)
- a DMARC record, at least `p=none`
- one-click unsubscribe on marketing email (Delivrie adds it to [broadcasts](/docs/broadcasts) automatically)
- a spam complaint rate under 0.3%; aim for under 0.1%

See the [Deliverability guide](/docs/deliverability) for the rest.


---

# Deliverability guide

How to keep Delivrie email out of spam: authentication, warming up a new domain, bounce and complaint thresholds, content, list hygiene and what to do when mail goes to spam.

Deliverability is whether your email reaches the inbox rather than the spam folder. Mailbox providers decide based on your domain's authentication, your sending history and how recipients react.

## The basics

1. **Authenticate.** Verify your domain so mail is DKIM-signed and passes SPF, and add [DMARC](/docs/dmarc).
2. **Send from a subdomain** like `mail.acme.com`, so app email and team email don't share a reputation.
3. **Only email people who asked for it.** Never buy or scrape lists.
4. **Make unsubscribing easy.** Broadcasts get a one-click unsubscribe header automatically; include a visible link too.
5. **Send what people expect,** when they expect it. Password resets and receipts rarely go to spam; surprise newsletters do.

## Stay under these limits

| Metric | Keep it under | What happens above it |
| --- | --- | --- |
| Bounce rate | 4% | Providers start blocking you, and Delivrie pauses your sending |
| Complaint rate | 0.08% (and never above 0.3%) | Gmail and Yahoo filter or reject your mail, and Delivrie pauses your sending |

### Automatic pause

Delivrie checks every account once an hour. If, over the last 7 days, more than 4% of your emails bounced (once you've sent at least 100) or more than 0.08% were marked as spam (once you've sent at least 1,000), sending is paused for the whole account. Sends then fail with `403 sending_paused`, and your team admins get an email explaining why. Emails to the [test addresses](/docs/test-mode) don't count.

To resume, find the cause (usually an old or imported list, or a sign-up form without validation), remove the bad addresses, and email support@delivrie.io with what you changed. This protects your domain's reputation as well as everyone else's.

Watch both in [Metrics](https://delivrie.io/metrics) or with `GET /metrics`.

## Warm up a new domain

A new domain has no reputation. Start with your most-engaged recipients and grow over a few weeks:

| Week | Emails a day |
| --- | --- |
| 1 | Up to a few hundred |
| 2 | 1,000 to 2,000 |
| 3 | 5,000 |
| 4 onward | Double while bounces and complaints stay low |

Transactional email (sign-ins, receipts) warms a domain naturally, because people open it.

## Keep your list clean

- Confirm addresses at sign-up (double opt-in for newsletters).
- Delivrie adds hard bounces and complaints to your [suppression list](/docs/suppressions) automatically. Don't remove addresses from it unless you're sure they're valid.
- Remove contacts who haven't opened anything in six months, or ask them to re-confirm.
- Use [test addresses](/docs/test-mode) for testing, never made-up addresses at real domains.

## Content

- Send a plain-text part (Delivrie generates one from your HTML).
- Keep a sensible balance of text and images; never send a single image as the whole email.
- Use your real domain in links. Link shorteners and mismatched domains look like phishing.
- Avoid misleading subject lines, all caps and lots of exclamation marks.
- Keep the HTML under about 100 KB; Gmail clips larger messages.

## If mail goes to spam

1. Check the email's events in [Emails](https://delivrie.io/emails). `delivered` means the provider accepted it; where it filed it is the provider's choice.
2. Check that SPF, DKIM and DMARC pass: in Gmail, open the message, choose **Show original** and look for `PASS` on all three.
3. Look at recent bounce and complaint rates in [Metrics](https://delivrie.io/metrics).
4. Register your domain with [Google Postmaster Tools](https://postmaster.google.com) to see your reputation at Gmail.
5. If you changed something recently (a new domain, a bigger list, new content), go back to sending only to engaged recipients for a week or two.


---

# Suppression list

How Delivrie's suppression list protects your reputation: which addresses are added automatically, and how to add, list and remove addresses with the dashboard or API.

Your team's suppression list holds addresses Delivrie won't send to. Sends to a suppressed address are skipped automatically, so one bad address can't keep hurting your reputation.

## What gets added automatically

| Event | Added? |
| --- | --- |
| Hard (permanent) bounce: the address doesn't exist | Yes, reason `bounce` |
| Spam complaint | Yes, reason `complaint`. The contact is also unsubscribed from broadcasts |
| Soft (transient) bounce: mailbox full, server busy | No |
| Bounces and complaints from [test addresses](/docs/test-mode) | No |

## What happens when you send to one

Suppressed addresses are removed from `to`, `cc` and `bcc` when the email is sent, and the rest of the recipients get it as normal. If every recipient is suppressed, the email's status becomes `suppressed` and nothing is sent. The API still returns `200` with an id, so check the status or watch your webhooks if this matters to you.

## Manage the list

In the dashboard, open [Suppressions](https://delivrie.io/suppressions). With the API:

```bash
# Add one or several
curl -X POST https://delivrie.io/api/suppressions \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "email": ["old@example.com", "left@example.com"] }'

# List (up to 1,000, with the reason)
curl https://delivrie.io/api/suppressions -H "Authorization: Bearer $DELIVRIE_API_KEY"

# Remove
curl -X DELETE https://delivrie.io/api/suppressions/old@example.com -H "Authorization: Bearer $DELIVRIE_API_KEY"
```

> **Warning:** Only remove an address if you know it now works, for example the person fixed a typo or asked to receive email again. Sending to addresses that bounced or complained again damages your reputation quickly.

## Importing from another provider

Moving from another provider? Import its bounce and complaint lists with `POST /suppressions` before your first send, so you don't repeat their mistakes.


---

# Webhooks

Get Delivrie events (sent, delivered, bounced, complained, opened, clicked, received, contact and domain changes) pushed to your server, with payload examples, signature verification in every language, retries and replays.

Webhooks push events to your server as they happen, so you don't have to poll. Use them to mark bounced addresses, record deliveries, react to replies and keep your own history.

## Add an endpoint

In [Webhooks](https://delivrie.io/webhooks), click **Add endpoint**, enter an `https://` URL and choose events. Or with the API:

```bash
curl -X POST https://delivrie.io/api/webhooks \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "endpoint": "https://acme.com/webhooks/delivrie", "events": ["email.delivered", "email.bounced", "email.complained"] }'
```

The response includes `signing_secret` (starts with `whsec_`). It's shown once: store it as `DELIVRIE_WEBHOOK_SECRET`. Use `["*"]` to receive every event.

## Events

| Event | When |
| --- | --- |
| `email.sent` | Delivrie's mail servers accepted the email |
| `email.delivered` | The recipient's server accepted it |
| `email.delivery_delayed` | Delivery is temporarily failing and being retried |
| `email.bounced` | The recipient's server rejected it |
| `email.complained` | The recipient marked it as spam |
| `email.opened` | Opened (open tracking must be on for the domain) |
| `email.clicked` | A link was clicked (click tracking must be on) |
| `email.failed` | It couldn't be sent; `failed.reason` says why |
| `email.received` | Mail arrived at one of your [receiving](/docs/receiving) addresses |
| `contact.created`, `contact.updated`, `contact.deleted` | A contact changed |
| `domain.created`, `domain.updated` | A domain was added or its verification status changed |

## Payloads

Every request is a `POST` with a JSON body of `{ type, created_at, data }`.

```json email.delivered
{
  "type": "email.delivered",
  "created_at": "2026-11-14T09:12:06.511Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@mail.acme.com>",
    "to": ["ada@example.com"],
    "subject": "Your order is confirmed",
    "created_at": "2026-11-14T09:12:04.120Z",
    "tags": { "category": "receipt" }
  }
}
```

```json email.bounced
{
  "type": "email.bounced",
  "created_at": "2026-11-14T09:12:07.002Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@mail.acme.com>",
    "to": ["nobody@example.com"],
    "subject": "Your order is confirmed",
    "created_at": "2026-11-14T09:12:04.120Z",
    "bounce": {
      "type": "Permanent",
      "sub_type": "General",
      "message": "smtp; 550 5.1.1 user unknown",
      "recipients": [{ "emailAddress": "nobody@example.com" }]
    }
  }
}
```

```json email.clicked
{
  "type": "email.clicked",
  "created_at": "2026-11-14T09:30:12.000Z",
  "data": {
    "email_id": "4ef9a417-...",
    "from": "Acme <orders@mail.acme.com>",
    "to": ["ada@example.com"],
    "subject": "Your order is confirmed",
    "created_at": "2026-11-14T09:12:04.120Z",
    "click": { "link": "https://acme.com/orders/1042", "user_agent": "Mozilla/5.0 ...", "ip": "102.89.0.1" }
  }
}
```

```json contact.created
{
  "type": "contact.created",
  "created_at": "2026-11-14T08:00:00.000Z",
  "data": { "id": "c_12...", "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace", "unsubscribed": false, "created_at": "2026-11-14T08:00:00.000Z" }
}
```

```json domain.updated
{
  "type": "domain.updated",
  "created_at": "2026-11-14T08:05:00.000Z",
  "data": { "id": "d91e...", "name": "mail.acme.com", "status": "verified", "region": "eu-west-1" }
}
```

All email events share `email_id`, `from`, `to`, `subject` and `created_at`, plus `tags` (as an object) when the email had tags and `broadcast_id` for broadcast emails. `email.bounced` adds `bounce`, `email.clicked` adds `click`, `email.failed` adds `failed: { reason }`. The `email.received` payload is shown in [Receiving email](/docs/receiving).

## Verify signatures

Every request is signed with the [Standard Webhooks](https://www.standardwebhooks.com) scheme, using three headers:

| Header | Contains |
| --- | --- |
| `webhook-id` | A unique event id, like `evt_8c1...`. The same for retries of one event |
| `webhook-timestamp` | Unix time in seconds when this attempt was sent |
| `webhook-signature` | `v1,<base64 signature>` (several, space-separated, during secret rotation) |

The signature is HMAC-SHA256 of `${webhook-id}.${webhook-timestamp}.${raw body}`, keyed with the base64-decoded part of your secret after `whsec_`. Always verify against the **raw** body, before any JSON parsing, and reject timestamps more than five minutes old.

```ts Node.js
import { verifyWebhook } from "delivrie";

// Next.js route handler, Hono, Workers... (Express: use express.raw and pass req.body)
export async function POST(req: Request) {
  try {
    const event = await verifyWebhook({
      payload: await req.text(),
      headers: req.headers,
      secret: process.env.DELIVRIE_WEBHOOK_SECRET!,
    });
    await handle(event);
    return new Response("ok");
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
}
```

```python Python
import base64, hashlib, hmac, json, time

def verify_webhook(payload: bytes, headers: dict, secret: str) -> dict:
    msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        raise ValueError("timestamp too old")
    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.".encode() + payload, hashlib.sha256).digest()).decode()
    if not any(s.startswith("v1,") and hmac.compare_digest(s[3:], expected) for s in headers["webhook-signature"].split()):
        raise ValueError("invalid signature")
    return json.loads(payload)
```

```php PHP
function verify_webhook(string $payload, array $h, string $secret): array {
    if (abs(time() - (int) $h['webhook-timestamp']) > 300) throw new Exception('timestamp too old');
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "{$h['webhook-id']}.{$h['webhook-timestamp']}.$payload", $key, true));
    foreach (explode(' ', $h['webhook-signature']) as $sig) {
        if (str_starts_with($sig, 'v1,') && hash_equals($expected, substr($sig, 3))) return json_decode($payload, true);
    }
    throw new Exception('invalid signature');
}
```

Ruby, Go and Rust versions are in their guides: [Ruby](/docs/ruby), [Go](/docs/go), [Rust](/docs/rust). Standard Webhooks libraries (`standardwebhooks` on npm and PyPI, and others) also work with your `whsec_` secret.

## Respond quickly

Return any `2xx` status within 15 seconds. Do slow work (database writes, calling other APIs) in a background job after responding. Redirects aren't followed and count as failures.

## Retries

Failed deliveries (non-`2xx`, timeout, connection error) are retried with increasing gaps: after about 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, then every 10 hours, for up to 72 hours.

- Events can arrive more than once and out of order. Use `webhook-id` to skip duplicates, and `created_at` to order them.
- See every attempt, with the status code and response, on the endpoint's page in [Webhooks](https://delivrie.io/webhooks) or with `GET /webhooks/:id/events`.
- Resend any attempt with **Replay** or `POST /webhook-deliveries/:id/replay`.
- Check your endpoint with **Send test event** or `POST /webhooks/:id/test`.

## Test locally

Expose your local server with a tunnel such as `ngrok http 3000` or `cloudflared tunnel --url http://localhost:3000`, add the tunnel URL as an endpoint, then send to a [test address](/docs/test-mode) to trigger real events.


---

# Broadcasts

Send newsletters and announcements to a segment of contacts with Delivrie broadcasts: personalisation, topics, unsubscribe links, test sends and scheduling, from the dashboard or the API.

A broadcast sends one email to every subscribed contact in a [segment](/docs/contacts): newsletters, product announcements, policy updates. Each recipient gets their own copy with their name filled in and their own unsubscribe link.

## From the dashboard

1. Open [Broadcasts](https://delivrie.io/broadcasts) and click **New broadcast**.
2. Choose a verified sender, a segment and, optionally, a [topic](/docs/contacts) so people can opt out of just this kind of email.
3. Write it in the editor. Use `{{first_name}}` or any contact property.
4. **Send test** to up to five inboxes and check it on your phone.
5. **Send now** or **Schedule**.

## With the API

```bash
# 1. Create a draft
curl -X POST https://delivrie.io/api/broadcasts \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "November newsletter",
    "from": "Acme <news@mail.acme.com>",
    "subject": "What we shipped in November",
    "segment_id": "SEGMENT_ID",
    "preview_text": "Three new features and a discount",
    "html": "<p>Hi {{first_name|there}},</p><p>...</p><p><a href=\"{{{unsubscribe_url}}}\">Unsubscribe</a></p>"
  }'

# 2. Send it now, or schedule it with an ISO 8601 time
curl -X POST https://delivrie.io/api/broadcasts/BROADCAST_ID/send \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-20T08:00:00Z" }'
```

The send response includes `recipients`, the number of contacts it will go to. Cancel a scheduled broadcast with `POST /broadcasts/:id/cancel` (it goes back to draft), and check how many contacts it will reach with `GET /broadcasts/:id/recipients`.

## Who receives it

Every contact in the segment, except contacts who:

- are unsubscribed,
- are on your [suppression list](/docs/suppressions), or
- opted out of the broadcast's topic.

## Personalisation

| Variable | Inserts |
| --- | --- |
| `{{first_name}}`, `{{last_name}}`, `{{email}}` | The contact's details (escaped). `first_name` falls back to "there" when empty |
| `{{plan}}`, `{{city}}`, ... | Any [contact property](/docs/contacts), with the fallback you set for that property |
| `{{first_name\|friend}}` | A fallback just for this email |
| `{{{unsubscribe_url}}}` | The recipient's unsubscribe page |

## Unsubscribing

Every broadcast email gets `List-Unsubscribe` and one-click unsubscribe headers, so Gmail and Apple Mail show their own **Unsubscribe** button. Include a visible link too, with `{{{unsubscribe_url}}}`. The page it opens lets people unsubscribe from everything or from one topic, and you can brand it in Settings.

## Broadcasts vs. API sends

Use broadcasts for the same message to many people. For one-to-one messages triggered by something a user did (receipts, password resets, alerts), use [`POST /emails`](/docs/send-email) or an [automation](/docs/automations).


---

# Contacts, segments and topics

Store your audience in Delivrie: create and import contacts, custom properties, segments for broadcasts and automations, and topics for granular unsubscribes.

Contacts are the people you send broadcasts and automations to. They belong to your team, and each email address appears once.

## Create or update a contact

`POST /contacts` creates a contact, or updates it if the email already exists, so it's safe to call on every sign-up:

```bash
curl -X POST https://delivrie.io/api/contacts \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "properties": { "plan": "pro", "city": "London" },
    "segments": ["SEGMENT_ID"]
  }'
```

```ts Node.js
await delivrie.contacts.create({ email: "ada@example.com", first_name: "Ada", properties: { plan: "pro" } });
```

Get, update or delete a contact by id **or** email address:

```bash
curl https://delivrie.io/api/contacts/ada@example.com -H "Authorization: Bearer $DELIVRIE_API_KEY"

curl -X PATCH https://delivrie.io/api/contacts/ada@example.com \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "properties": { "plan": "scale" }, "unsubscribed": false }'
```

`properties` in an update are merged into the existing ones; other properties are kept.

## Import

Upload a CSV in [Contacts → Import](https://delivrie.io/contacts/import). Map columns to email, first name, last name and properties, and choose a segment to add everyone to. Only import people who agreed to hear from you.

## Properties

Properties hold anything you want to personalise or filter by: plan, city, signup date. Define them, with a type and fallback value, in [Contacts → Properties](https://delivrie.io/contacts/properties). `GET /contact-properties` lists them. Use them in broadcasts as `{{plan}}`.

## Segments

Segments are named groups of contacts. Broadcasts go to a segment, and automations can start when someone joins one.

| Request | What it does |
| --- | --- |
| `POST /segments` with `{ "name": "Beta users" }` | Create a segment |
| `GET /segments` | List segments |
| `POST /segments/:id/contacts` with `{ "contacts": ["ada@example.com", { "email": "sam@example.com", "first_name": "Sam" }] }` | Add contacts, creating any that don't exist |
| `DELETE /segments/:id` | Delete the segment (the contacts stay) |

## Topics

Topics let people opt out of one kind of email (say, product updates) without leaving everything. Create them in [Contacts → Topics](https://delivrie.io/contacts/topics) with a default of opt-in or opt-out, then pick a topic when you create a broadcast. The unsubscribe page shows each topic as its own switch. `GET /topics` lists them.

## Unsubscribed contacts

A contact with `unsubscribed: true` gets no broadcasts. It happens when they click unsubscribe, when they mark a broadcast as spam, or when you set it. Transactional emails sent with `POST /emails` aren't affected; they're for messages the person needs, like receipts.


---

# Automations and events

Send emails automatically when something happens: record events with POST /events, build automations with waits, conditions and branches, and create simple flows with the API.

Automations send emails on their own when something happens: a welcome series after sign-up, a nudge three days after a trial starts, a receipt when an order is paid. Your app sends an **event**; any live automation listening for it starts a **run** for that contact.

## 1. Send events from your app

```bash cURL
curl -X POST https://delivrie.io/api/events \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "event": "user.signed_up", "email": "ada@example.com", "data": { "plan": "free", "first_name": "Ada" } }'
```

```ts Node.js
await delivrie.events.send({ event: "user.signed_up", email: "ada@example.com", data: { plan: "free", first_name: "Ada" } });
```

```python Python
requests.post("https://delivrie.io/api/events", headers=auth, json={
    "event": "user.signed_up", "email": "ada@example.com", "data": {"plan": "free"},
})
```

| Field | Notes |
| --- | --- |
| `event` | Lowercase letters, numbers, dots, dashes and underscores, like `order.paid` |
| `email` | The contact it's about. The contact is created if it doesn't exist |
| `data` | Optional JSON, up to 32 KB. Use it in conditions and templates |

The response says how many automations started: `{ "object": "event", "id": "...", "event": "user.signed_up", "runs": 1 }`. Sending access keys can send events. See recent events in [Events](https://delivrie.io/events), or with `GET /events` (event names) and `GET /events?name=user.signed_up` (recent events with that name).

## 2. Build an automation

In [Automations](https://delivrie.io/automations), create one and pick a trigger:

- **An event**, like `user.signed_up`
- **A contact joining a segment**

Then add steps:

| Step | Does |
| --- | --- |
| Send email | Sends a published [template](/docs/templates) |
| Wait | Pauses for minutes, hours, days or weeks |
| Condition | Branches on event data or contact properties |

Choose whether a contact can go through it once or every time the trigger happens, then **Publish**. Use **Test** to run it for one address without affecting stats.

## Create one with the API

The API creates straight-line automations (send and wait steps). Build branches in the dashboard.

```bash
curl -X POST https://delivrie.io/api/automations \
  -H "Authorization: Bearer $DELIVRIE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome series",
    "trigger": { "event": "user.signed_up" },
    "steps": [
      { "type": "send", "template_id": "welcome" },
      { "type": "wait", "amount": 2, "unit": "days" },
      { "type": "send", "template_id": "getting-started-tips" }
    ],
    "reentry": "once",
    "publish": true
  }'
```

`template_id` takes a template id or alias, and a send step can override `from` and `subject`. Up to 30 steps. Use `{ "segment_id": "..." }` as the trigger to start when someone joins a segment.

Manage automations with `GET /automations`, `GET /automations/:id` (with run counts), `GET /automations/:id/runs`, and `POST /automations/:id/publish`, `/pause` and `/resume`.

## Runs

Each contact going through an automation is a run: `running`, `completed`, `failed` or `canceled`. Open an automation to see every run and each step's timing. If a step fails (for example, the template's sender domain isn't verified), fix the cause, then retry or skip the step from the run.

## Event data in templates

Templates sent by an automation can use the contact's details and the triggering event's data. For the event above, `{{first_name}}` and `{{plan}}` both work, and so does the longer form `{{data.plan}}`, including nested fields like `{{data.order.total}}`. Add a fallback with `{{plan|free}}`. In automations, every variable is HTML-escaped.


---

# Troubleshooting and FAQ

Answers to the most common Delivrie questions: emails not arriving, going to spam, API errors, webhooks not firing, SMTP connection problems, limits and billing.

## Sending

**My request returns 200 but the email never arrives.**
Open the email in [Emails](https://delivrie.io/emails) (or `GET /emails/:id`) and check its status:
- `suppressed`: every recipient is on your [suppression list](/docs/suppressions).
- `bounced`: the event says why; usually the address doesn't exist.
- `failed`: the `error` field says why, often that the sending domain stopped being verified.
- `delivered`: the recipient's server accepted it. Ask them to check spam and any filters; see the [Deliverability guide](/docs/deliverability).
- `queued` or `sent` for more than a few minutes: check [status](https://delivrie.io/status), then contact us.

**I get "The from domain ... is not verified".**
The domain in `from` must be verified in this team. Check for typos (`mail.acme.com` vs `acme.com`), check the key belongs to the right team, and see [Why isn't my domain verifying?](/docs/domain-not-verifying) While testing, use `onboarding@delivrie.io`.

**I get "... can only send to members of your team".**
You're sending from `onboarding@delivrie.io`, which can only email your teammates and the [test addresses](/docs/test-mode). Verify your own domain to email anyone.

**Can I send from Gmail, Yahoo or Outlook addresses?**
No. You can only send from domains you own and verify. Those providers' DMARC policies would send such mail to spam anyway.

**Emails go to spam.**
Follow [If mail goes to spam](/docs/deliverability). Most often it's a new domain with no history, missing DMARC, or content that looks promotional.

**How do I send to many people at once?**
For different content per person, use [batch sending](/docs/send-email) (100 per request). For the same message to a list, use [broadcasts](/docs/broadcasts). Don't put many recipients in one email's `to`: they'd all see each other.

**Is there a request rate limit?**
There's no fixed per-second limit today. Plan limits are on emails per day and month: see [Plans and limits](/docs/limits). For large sends, use batches or broadcasts rather than thousands of parallel requests.

## API and code

**401 errors.**
`missing_api_key`: the `Authorization` header is missing, often because the environment variable isn't set where the code runs. `invalid_api_key`: the key was deleted, mistyped, or has extra spaces or quotes around it.

**403 restricted_api_key.**
A sending access key can only send. Use a full access key for other endpoints, or check the key's domain restriction.

**CORS errors in the browser.**
Don't call the API from the browser; your key would be public. See [CORS and browser apps](/docs/cors).

**"Request body must be valid JSON".**
Send `Content-Type: application/json` and a JSON body. In cURL, check your quotes; in code, use `JSON.stringify` or your client's JSON option.

**Where can I see exactly what I sent?**
[Logs](https://delivrie.io/logs) has every API request with its request and response bodies, including failures.

## Webhooks

**My endpoint isn't receiving events.**
Check the endpoint is subscribed to those events and enabled, uses `https://`, is publicly reachable (not `localhost`), and returns `2xx` within 15 seconds without redirecting. The endpoint's page in [Webhooks](https://delivrie.io/webhooks) shows each attempt with its status code and response. Use **Send test event** to try it.

**Signature verification fails.**
You're almost certainly verifying a parsed and re-serialised body. Verify the raw body, exactly as received, and use the right endpoint's `whsec_` secret. See [Verify signatures](/docs/webhooks).

**I get the same event twice.**
Retries can deliver an event more than once. Skip events whose `webhook-id` you've already handled.

## SMTP

**Connection times out.** Your host probably blocks port 587 or 465. Use `2587` or `2465`. See [SMTP](/docs/smtp).

**535 authentication failed.** The username must be `delivrie` and the password a valid API key.

## Account and billing

**What happens when I reach my limit?** See [When you reach a limit](/docs/limits).

**Can I change plans any time?** Yes, in [Billing](https://delivrie.io/billing). You can pay in naira or US dollars.

**How long are emails and logs kept?** Email content, sent and received, and API request logs: 30 days on every plan. Recipients, status and events stay after content is deleted. Use [webhooks](/docs/webhooks) to keep your own records.

**Can several people use one account?** Yes: invite teammates in Settings. Free includes one member; Starter and Pro five; Scale unlimited.

## Still stuck?

- Ask in the chat in the bottom corner of the dashboard. Replies arrive there and by email.
- Email [support@delivrie.io](mailto:support@delivrie.io) with the email id or request id from [Logs](https://delivrie.io/logs), so we can find it quickly.
- Check [status](https://delivrie.io/status) for anything affecting everyone.


---

# API reference

Base URL `https://delivrie.io/api`. Authenticate with `Authorization: Bearer dlv_your_key`.


---

# Send email

`POST https://delivrie.io/api/emails`

Send a transactional email. Returns the email id immediately; delivery events arrive through webhooks and the Logs page.

Access: Sending or full access. MCP tool: `send_email`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer token. Any API key works, including sending-only keys. |
| `Idempotency-Key` | string | No | Unique key for this request. Retrying with the same key returns the original email instead of sending again. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | Yes | Sender address on a verified domain. Use "Name <email@domain>" to set a display name. |
| `to` | string \| string[] | Yes | Recipient address or up to 50 addresses. |
| `subject` | string | Yes | Email subject line. Optional when you send a template. |
| `html` | string | No | HTML body. Provide html, text or template. |
| `text` | string | No | Plain-text body. Generated from html when omitted. Default: `auto`. |
| `cc` | string \| string[] | No | Carbon-copy recipients. |
| `bcc` | string \| string[] | No | Blind carbon-copy recipients. |
| `reply_to` | string \| string[] | No | Where replies go. |
| `template` | object | No | Send a published template: { "id": "alias-or-id", "variables": { … } }. |
| `scheduled_at` | string | No | ISO 8601 date or a phrase like "in 1 hour" or "tomorrow at 9am" (UTC). Up to 30 days ahead. |
| `tags` | object[] | No | Name/value pairs attached to the email and its webhook events. Letters, numbers, _ and - only. |
| `headers` | object | No | Custom email headers. |
| `attachments` | object[] | No | { filename, content } with base64 content. Up to 40 MB per email. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/emails' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <orders@acme.com>",
    "to": [
      "ada@example.com"
    ],
    "subject": "Your order is confirmed",
    "html": "<p>Thanks for your order!</p>",
    "tags": [
      {
        "name": "category",
        "value": "receipt"
      }
    ]
  }'
```

## Response

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

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 401 | `invalid_api_key` | The key doesn't exist or was deleted. |
| 403 | `restricted_api_key` | This sending key is limited to a different domain. |
| 422 | `validation_error` | A required field is missing or malformed, or the from domain isn't verified on this team. The message says which. |
| 429 | `daily_quota_exceeded` | Free plan limit of 133 emails a day reached. |
| 429 | `monthly_quota_exceeded` | Free plan monthly limit reached and no credits left. |
| 429 | `spending_cap_reached` | This send would take overage past your spending cap. |


---

# Send batch

`POST https://delivrie.io/api/emails/batch`

Send up to 100 emails in one request, each with its own recipients and content. Batch emails can't have attachments or scheduled_at.

Access: Sending or full access. MCP tool: `send_batch`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer token. |
| `Idempotency-Key` | string | No | Makes the whole batch safe to retry. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[ ]` | object[] | Yes | An array of up to 100 email objects with the same fields as Send email. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/emails/batch' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "from": "Acme <orders@acme.com>",
      "to": [
        "ada@example.com"
      ],
      "subject": "Receipt",
      "html": "<p>Order 1</p>"
    },
    {
      "from": "Acme <orders@acme.com>",
      "to": [
        "sam@example.com"
      ],
      "subject": "Receipt",
      "html": "<p>Order 2</p>"
    }
  ]'
```

## Response

```json
{
  "data": [
    {
      "id": "4ef9a417-…"
    },
    {
      "id": "9a1c22b0-…"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 422 | `validation_error` | More than 100 emails, or an email uses attachments or scheduled_at. |


---

# Retrieve email

`GET https://delivrie.io/api/emails/:id`

Get one email with its status and every delivery event.

Access: Needs a full access key.. MCP tool: `get_email`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The email id. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/emails/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "email",
  "id": "4ef9a417-…",
  "from": "Acme <orders@acme.com>",
  "to": [
    "ada@example.com"
  ],
  "subject": "Your order is confirmed",
  "last_event": "delivered",
  "created_at": "2026-11-12T09:12:04Z",
  "events": [
    {
      "type": "sent"
    },
    {
      "type": "delivered"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Update email

`PATCH https://delivrie.io/api/emails/:id`

Reschedule an email that hasn't been sent yet.

Access: Sending or full access.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The email id. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `scheduled_at` | string | Yes | New send time: ISO 8601 or a phrase like "in 2 hours". |

## Example request

```bash
curl -X PATCH 'https://delivrie.io/api/emails/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "scheduled_at": "tomorrow at 9am"
  }'
```

## Response

```json
{
  "object": "email",
  "id": "4ef9a417-…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 422 | `validation_error` | Only scheduled emails can be updated. |


---

# Cancel email

`POST https://delivrie.io/api/emails/:id/cancel`

Cancel a scheduled email before it sends.

Access: Sending or full access. MCP tool: `cancel_email`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The email id. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/emails/4ef9a417/cancel' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "email",
  "id": "4ef9a417-…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List emails

`GET https://delivrie.io/api/emails`

List sent emails, newest first.

Access: Needs a full access key.. MCP tool: `list_emails`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Results per page, 1 to 100. Default: `50`. |
| `offset` | number | No | How many results to skip. Default: `0`. |
| `direction` | string | No | outbound or inbound. Default: `outbound`. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/emails' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "4ef9a417-…",
      "subject": "Your order is confirmed",
      "last_event": "delivered"
    }
  ],
  "has_more": false
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List received emails

`GET https://delivrie.io/api/emails/received`

Emails that arrived on your receiving domains, newest first. Fetch one with Retrieve email for its HTML and text.

Access: Needs a full access key.. MCP tool: `list_received_emails`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Results, 1 to 100. Default: `50`. |
| `to` | string | No | Only mail sent to this address. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/emails/received' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "a5c3e1f0-…",
      "from": "Ada <ada@example.com>",
      "to": [
        "support@in.acme.com"
      ],
      "subject": "Re: Your order",
      "created_at": "2026-11-14T10:22:30Z",
      "attachments": [
        {
          "filename": "photo.jpg",
          "content_type": "image/jpeg",
          "size": 248213
        }
      ]
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Forward email

`POST https://delivrie.io/api/emails/:id/forward`

Forward a sent or received email to other addresses, with an optional note above it.

Access: Sending or full access. MCP tool: `forward_email`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The email id. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `to` | string \| string[] | Yes | Where to forward it. |
| `from` | string | Yes | Sender on a verified domain. |
| `note` | string | No | A message shown above the forwarded email. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/emails/4ef9a417/forward' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "ops@acme.com",
    "from": "Acme <support@mail.acme.com>",
    "note": "Can you look at this?"
  }'
```

## Response

```json
{
  "id": "9b2e…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Send event

`POST https://delivrie.io/api/events`

Record a custom event for a contact. Live automations listening for the event start a run right away. The contact is created if it doesn’t exist.

Access: Any API key.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `event` | string | Yes | Lowercase name with dots for namespaces, like user.created. |
| `email` | string | Yes | The contact the event is about. |
| `data` | object | No | Any JSON up to 32 KB. Use it in automation filters, conditions and templates as {{{data.field}}}. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/events' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "user.created",
    "email": "ada@example.com",
    "data": {
      "country": "NG",
      "plan": "free"
    }
  }'
```

## Response

```json
{
  "object": "event",
  "id": "8d1c…",
  "event": "user.created",
  "runs": 1
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 422 | `validation_error` | The event name or email is invalid, or data is over 32 KB. |


---

# List events

`GET https://delivrie.io/api/events`

Without name: every event name your team has sent, with when it was first and last seen. With name: the most recent events with that name.

Access: Needs a full access key.. MCP tool: `list_events`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | An event name, like user.created. |
| `limit` | number | No | Results, 1 to 100. Default: `50`. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/events' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "name": "user.created",
      "first_seen_at": "2026-11-01T09:00:00Z",
      "last_seen_at": "2026-11-14T10:00:00Z"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List automations

`GET https://delivrie.io/api/automations`

Automations with their trigger, status (draft, live or paused) and step count.

Access: Needs a full access key.. MCP tool: `list_automations`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/automations' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "object": "automation",
      "id": "au_3…",
      "name": "Welcome series",
      "status": "live",
      "trigger": {
        "type": "event",
        "event": "user.created"
      },
      "steps": 3
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Retrieve automation

`GET https://delivrie.io/api/automations/:id`

One automation with its steps and run counts.

Access: Needs a full access key.. MCP tool: `get_automation`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The automation id. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/automations/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "automation",
  "id": "au_3…",
  "name": "Welcome series",
  "status": "live",
  "runs": {
    "running": 12,
    "completed": 340,
    "failed": 1,
    "canceled": 0
  }
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Create automation

`POST https://delivrie.io/api/automations`

Create a straight-line automation: a trigger and up to 30 send and wait steps. Build branches and conditions in the dashboard.

Access: Needs a full access key.. MCP tool: `create_automation`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Name. |
| `trigger` | object | Yes | { "event": "user.created" } or { "segment_id": "…" }. |
| `steps` | object[] | Yes | { "type": "send", "template_id": "alias" } or { "type": "wait", "amount": 2, "unit": "days" }. Units: minutes, hours, days, weeks. |
| `reentry` | string | No | once or always. Default: `once`. |
| `publish` | boolean | No | Publish right away. Default: `false`. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/automations' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Welcome series",
    "trigger": {
      "event": "user.created"
    },
    "steps": [
      {
        "type": "send",
        "template_id": "welcome"
      },
      {
        "type": "wait",
        "amount": 2,
        "unit": "days"
      },
      {
        "type": "send",
        "template_id": "tips"
      }
    ],
    "publish": true
  }'
```

## Response

```json
{
  "object": "automation",
  "id": "au_3…",
  "status": "live",
  "url": "https://delivrie.io/automations/au_3…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List runs

`GET https://delivrie.io/api/automations/:id/runs`

Runs, newest first, with their status, current step and log.

Access: Needs a full access key.. MCP tool: `list_automation_runs`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The automation id. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | No | running, completed, failed or canceled. |
| `limit` | number | No | Results, 1 to 100. Default: `50`. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/automations/4ef9a417/runs' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "run_9…",
      "email": "ada@example.com",
      "status": "completed",
      "started_at": "2026-11-14T09:00:00Z"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Publish automation

`POST https://delivrie.io/api/automations/:id/publish`

Make the current version live. Pause with /pause and continue with /resume.

Access: Needs a full access key.. MCP tool: `publish_automation`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The automation id. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/automations/4ef9a417/publish' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "automation",
  "id": "au_3…",
  "status": "live"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List threads

`GET https://delivrie.io/api/inbox/threads`

Conversations from received email, newest first.

Access: Needs a full access key.. MCP tool: `list_inbox_threads`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | No | open, archived or all. Default: `open`. |
| `needs_reply` | boolean | No | Only threads whose latest message is from the contact. |
| `unread` | boolean | No | Only unread threads. |
| `mailbox` | string | No | Only one receiving address. |
| `label` | string | No | Only threads with this label. |
| `q` | string | No | Search subject, contact and snippet. |
| `limit` | number | No | Results, 1 to 100. Default: `50`. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/inbox/threads' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "object": "inbox_thread",
      "id": "th_4…",
      "mailbox": "support@in.acme.com",
      "contact": "ada@example.com",
      "subject": "Refund",
      "snippet": "Hi, I'd like…",
      "unread": true,
      "needs_reply": true,
      "labels": []
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Retrieve thread

`GET https://delivrie.io/api/inbox/threads/:id`

A thread with up to 100 messages as text.

Access: Needs a full access key.. MCP tool: `get_inbox_thread`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The thread id. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/inbox/threads/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "inbox_thread",
  "id": "th_4…",
  "subject": "Refund",
  "messages": [
    {
      "id": "a5c3…",
      "direction": "inbound",
      "from": "ada@example.com",
      "text": "Hi, I'd like a refund…",
      "created_at": "2026-11-14T10:22:30Z"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Reply to thread

`POST https://delivrie.io/api/inbox/threads/:id/reply`

Reply in the thread. Threading headers and the Re: subject are set for you.

Access: Sending or full access. MCP tool: `reply_to_thread`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The thread id. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | No | Plain-text reply, wrapped in simple HTML for you. Provide text or html. |
| `html` | string | No | HTML reply. |
| `from` | string | No | Sender. Defaults to the thread's mailbox address. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/inbox/threads/4ef9a417/reply' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Thanks Ada, your refund is on its way."
  }'
```

## Response

```json
{
  "object": "email",
  "id": "7d1f…",
  "thread_id": "th_4…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Update thread

`PATCH https://delivrie.io/api/inbox/threads/:id`

Archive or reopen, mark read or unread, or set labels.

Access: Sending or full access. MCP tool: `update_thread`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The thread id. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | No | open or archived. |
| `unread` | boolean | No | Read state. |
| `labels` | string[] | No | Label names. New labels are created. |

## Example request

```bash
curl -X PATCH 'https://delivrie.io/api/inbox/threads/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "archived",
    "labels": [
      "refunds"
    ]
  }'
```

## Response

```json
{
  "object": "inbox_thread",
  "id": "th_4…",
  "status": "archived",
  "labels": [
    "refunds"
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Create domain

`POST https://delivrie.io/api/domains`

Add a sending domain. The response includes the DNS records to add at your DNS provider.

Access: Needs a full access key.. MCP tool: `create_domain`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | The domain or subdomain, for example mail.acme.com. |
| `region` | string | No | Sending region. Default: `eu-west-1`. |
| `return_path` | string | No | Subdomain used for bounces and SPF. Default: `send`. |
| `click_tracking` | boolean | No | Rewrite links to track clicks. Default: `false`. |
| `open_tracking` | boolean | No | Add a tracking pixel. Default: `false`. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/domains' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "mail.acme.com",
    "region": "eu-west-1"
  }'
```

## Response

```json
{
  "object": "domain",
  "id": "d91e…",
  "name": "mail.acme.com",
  "status": "pending",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "delivrie._domainkey.mail",
      "status": "pending"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 403 | `plan_limit_reached` | Your plan's domain limit is reached. |
| 422 | `validation_error` | The domain name isn't valid or is already added. |


---

# Retrieve domain

`GET https://delivrie.io/api/domains/:id`

Get a domain with its DNS records and their status.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The domain id. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/domains/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "domain",
  "id": "d91e…",
  "name": "mail.acme.com",
  "status": "verified"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Verify domain

`POST https://delivrie.io/api/domains/:id/verify`

Check the DNS records again. Verification usually completes within minutes of the records going live.

Access: Needs a full access key.. MCP tool: `verify_domain`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The domain id. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/domains/4ef9a417/verify' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "domain",
  "id": "d91e…",
  "status": "verified"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Update domain

`PATCH https://delivrie.io/api/domains/:id`

Change tracking, TLS, the return path or receiving settings.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The domain id. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `click_tracking` | boolean | No | Track link clicks. |
| `open_tracking` | boolean | No | Track opens. |
| `tls` | string | No | opportunistic or enforced. |
| `return_path` | string | No | Bounce subdomain label. |
| `receiving_enabled` | boolean | No | Receive email on this domain. |
| `receiving_subdomain` | string | No | Receive on a subdomain, like in. Empty for the domain itself. |
| `receiving_mode` | string | No | all or specific. |
| `receiving_addresses` | string[] | No | Addresses that accept mail when receiving_mode is specific. |

## Example request

```bash
curl -X PATCH 'https://delivrie.io/api/domains/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "open_tracking": true
  }'
```

## Response

```json
{
  "object": "domain",
  "id": "d91e…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List domains

`GET https://delivrie.io/api/domains`

List the team's domains.

Access: Needs a full access key.. MCP tool: `list_domains`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/domains' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "d91e…",
      "name": "mail.acme.com",
      "status": "verified"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Delete domain

`DELETE https://delivrie.io/api/domains/:id`

Remove a domain. Emails can no longer be sent from it.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The domain id. |

## Example request

```bash
curl -X DELETE 'https://delivrie.io/api/domains/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "domain",
  "id": "d91e…",
  "deleted": true
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Create API key

`POST https://delivrie.io/api/api-keys`

Create a key. The token is returned once, so store it somewhere safe.

Access: Needs a full access key.. MCP tool: `create_api_key`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | A name to recognise the key. |
| `permission` | string | No | full_access or sending_access. Default: `full_access`. |
| `domain_id` | string | No | Limit a sending key to one domain. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/api-keys' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Production",
    "permission": "sending_access"
  }'
```

## Response

```json
{
  "id": "k_31…",
  "token": "dlv_••••••••"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List API keys

`GET https://delivrie.io/api/api-keys`

List keys. Tokens are never shown again.

Access: Needs a full access key.. MCP tool: `list_api_keys`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/api-keys' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "k_31…",
      "name": "Production",
      "prefix": "dlv_a1b2",
      "permission": "sending"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Delete API key

`DELETE https://delivrie.io/api/api-keys/:id`

Revoke a key immediately.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The API key id. |

## Example request

```bash
curl -X DELETE 'https://delivrie.io/api/api-keys/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "api_key",
  "id": "k_31…",
  "deleted": true
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Create webhook

`POST https://delivrie.io/api/webhooks`

Send events to an HTTPS endpoint. Each payload is signed; failed deliveries are retried with backoff.

Access: Needs a full access key.. MCP tool: `create_webhook`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `endpoint` | string | Yes | An https:// URL. |
| `events` | string[] | Yes | Events to send, for example email.delivered and email.bounced. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/webhooks' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "endpoint": "https://acme.com/hooks/delivrie",
    "events": [
      "email.delivered",
      "email.bounced",
      "email.complained"
    ]
  }'
```

## Response

```json
{
  "object": "webhook",
  "id": "w_8c…",
  "signing_secret": "whsec_••••"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 403 | `plan_limit_reached` | Your plan's webhook limit is reached. |


---

# List webhooks

`GET https://delivrie.io/api/webhooks`

List webhook endpoints.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/webhooks' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "w_8c…",
      "endpoint": "https://acme.com/hooks/delivrie",
      "status": "enabled"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List deliveries

`GET https://delivrie.io/api/webhooks/:id/events`

The last 100 delivery attempts for an endpoint, with status codes.

Access: Needs a full access key.. MCP tool: `list_webhook_events`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook id. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/webhooks/4ef9a417/events' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "event_type": "email.delivered",
      "status_code": 200,
      "attempts": 1,
      "delivered": true
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Send test event

`POST https://delivrie.io/api/webhooks/:id/test`

Send a sample event to the endpoint and return the delivery attempt.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The webhook id. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/webhooks/4ef9a417/test' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "id": "wd_5…",
  "event_type": "email.delivered",
  "status_code": 200,
  "attempts": 1,
  "delivered": true
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Replay delivery

`POST https://delivrie.io/api/webhook-deliveries/:id/replay`

Send a past delivery again and return the new attempt.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The delivery id. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/webhook-deliveries/4ef9a417/replay' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "id": "wd_5…",
  "status_code": 200,
  "attempts": 2,
  "delivered": true
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Create contact

`POST https://delivrie.io/api/contacts`

Create a contact, or update it if the email already exists.

Access: Needs a full access key.. MCP tool: `create_contact`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | Contact email. |
| `first_name` | string | No | First name. |
| `last_name` | string | No | Last name. |
| `properties` | object | No | Custom properties. |
| `segments` | string[] | No | Segment ids to add the contact to. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/contacts' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "properties": {
      "plan": "pro"
    }
  }'
```

## Response

```json
{
  "object": "contact",
  "id": "c_12…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List contacts

`GET https://delivrie.io/api/contacts`

List contacts, newest first.

Access: Needs a full access key.. MCP tool: `list_contacts`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Results per page, 1 to 100. Default: `50`. |
| `offset` | number | No | How many results to skip. Default: `0`. |
| `created_after` | string | No | ISO date, or today. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/contacts' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "c_12…",
      "email": "ada@example.com"
    }
  ],
  "has_more": false
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Retrieve contact

`GET https://delivrie.io/api/contacts/:id`

Get a contact by id or email.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Contact id or email address. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/contacts/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "contact",
  "id": "c_12…",
  "email": "ada@example.com",
  "unsubscribed": false
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Update contact

`PATCH https://delivrie.io/api/contacts/:id`

Update names, properties or the unsubscribed flag.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Contact id or email address. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `first_name` | string | No | First name. |
| `last_name` | string | No | Last name. |
| `unsubscribed` | boolean | No | Stop broadcasts to this contact. |
| `properties` | object | No | Merged into existing properties. |

## Example request

```bash
curl -X PATCH 'https://delivrie.io/api/contacts/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "unsubscribed": true
  }'
```

## Response

```json
{
  "object": "contact",
  "id": "c_12…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Delete contact

`DELETE https://delivrie.io/api/contacts/:id`

Delete a contact.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Contact id or email address. |

## Example request

```bash
curl -X DELETE 'https://delivrie.io/api/contacts/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "contact",
  "id": "c_12…",
  "deleted": true
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Add to segment

`POST https://delivrie.io/api/segments/:id/contacts`

Add contacts to a segment, creating any that don't exist.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The segment id. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `contacts` | string[] \| object[] | Yes | Emails or contact objects. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/segments/4ef9a417/contacts' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "contacts": [
      "ada@example.com",
      "sam@example.com"
    ]
  }'
```

## Response

```json
{
  "object": "segment",
  "id": "s_4…",
  "added": 2
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Create segment

`POST https://delivrie.io/api/segments`

Create a segment to group contacts for broadcasts and automations.

Access: Needs a full access key.. MCP tool: `create_segment`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Segment name. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/segments' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Beta users"
  }'
```

## Response

```json
{
  "object": "segment",
  "id": "s_4…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List segments

`GET https://delivrie.io/api/segments`

List segments.

Access: Needs a full access key.. MCP tool: `list_segments`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/segments' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "s_4…",
      "name": "Beta users"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Delete segment

`DELETE https://delivrie.io/api/segments/:id`

Delete a segment. Its contacts are kept.

Access: Needs a full access key.. MCP tool: `delete_segment`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The segment id. |

## Example request

```bash
curl -X DELETE 'https://delivrie.io/api/segments/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "segment",
  "id": "s_4…",
  "deleted": true
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List topics

`GET https://delivrie.io/api/topics`

Topics people can opt out of on the unsubscribe page.

Access: Needs a full access key.. MCP tool: `list_topics`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/topics' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "tp_1…",
      "name": "Product updates",
      "default_subscription": "opt_in"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List contact properties

`GET https://delivrie.io/api/contact-properties`

Custom contact properties with their type and fallback.

Access: Needs a full access key.. MCP tool: `list_contact_properties`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/contact-properties' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "key": "plan",
      "type": "string",
      "fallback": "free"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Create broadcast

`POST https://delivrie.io/api/broadcasts`

Create a broadcast draft. Nothing sends until you call Send broadcast.

Access: Needs a full access key.. MCP tool: `create_broadcast`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | Yes | Sender on a verified domain. |
| `subject` | string | Yes | Subject line. |
| `segment_id` | string | Yes | Who receives it. |
| `html` | string | No | HTML body. Include an unsubscribe link with {{{unsubscribe_url}}}. |
| `topic_id` | string | No | Topic people can opt out of. |
| `name` | string | No | Internal name. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/broadcasts' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <news@acme.com>",
    "subject": "March at Acme",
    "segment_id": "s_4…",
    "html": "<p>Hi {{{first_name|there}}}</p>"
  }'
```

## Response

```json
{
  "object": "broadcast",
  "id": "b_7…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Send broadcast

`POST https://delivrie.io/api/broadcasts/:id/send`

Send now, or schedule with scheduled_at.

Access: Needs a full access key.. MCP tool: `send_broadcast`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The broadcast id. |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `scheduled_at` | string | No | ISO 8601 date to schedule. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/broadcasts/4ef9a417/send' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "scheduled_at": "2026-11-20T08:00:00Z"
  }'
```

## Response

```json
{
  "object": "broadcast",
  "id": "b_7…",
  "status": "scheduled",
  "recipients": 3240
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Cancel broadcast

`POST https://delivrie.io/api/broadcasts/:id/cancel`

Move a scheduled broadcast back to draft.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The broadcast id. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/broadcasts/4ef9a417/cancel' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "broadcast",
  "id": "b_7…",
  "status": "draft"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List broadcasts

`GET https://delivrie.io/api/broadcasts`

List broadcasts.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/broadcasts' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "b_7…",
      "name": "March at Acme",
      "status": "sent"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Retrieve broadcast

`GET https://delivrie.io/api/broadcasts/:id`

One broadcast with its status and delivery stats.

Access: Needs a full access key.. MCP tool: `get_broadcast`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The broadcast id. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/broadcasts/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "broadcast",
  "id": "b_7…",
  "name": "March at Acme",
  "status": "sent",
  "recipients": 3240
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Count recipients

`GET https://delivrie.io/api/broadcasts/:id/recipients`

How many contacts a broadcast will reach: everyone in the segment, how many opted out of its topic, and how many remain after unsubscribes and suppressions.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The broadcast id. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/broadcasts/4ef9a417/recipients' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "total": 3400,
  "topic_opt_out": 120,
  "recipients": 3240
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Delete broadcast

`DELETE https://delivrie.io/api/broadcasts/:id`

Delete a draft, scheduled or sent broadcast. A broadcast that's sending can't be deleted.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The broadcast id. |

## Example request

```bash
curl -X DELETE 'https://delivrie.io/api/broadcasts/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "broadcast",
  "id": "b_7…",
  "deleted": true
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Create template

`POST https://delivrie.io/api/templates`

Create a template. Publish it before sending it from the API.

Access: Needs a full access key.. MCP tool: `create_template`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Template name. |
| `alias` | string | No | Stable name to send by, like order-confirmation. |
| `subject` | string | No | Subject with {{{variables}}}. |
| `html` | string | No | HTML body. |
| `from` | string | No | Default sender. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/templates' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Order confirmation",
    "alias": "order-confirmation",
    "subject": "Order {{{order_id}}} confirmed",
    "html": "<p>Hi {{{first_name}}}</p>"
  }'
```

## Response

```json
{
  "object": "template",
  "id": "t_2…"
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Publish template

`POST https://delivrie.io/api/templates/:id/publish`

Make the current draft the live version. Every publish is kept in version history.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Template id or alias. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/templates/4ef9a417/publish' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "template",
  "id": "t_2…",
  "version": 3,
  "warnings": []
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Retrieve template

`GET https://delivrie.io/api/templates/:id`

One template by id or alias, with its current draft and published version.

Access: Needs a full access key.. MCP tool: `get_template`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Template id or alias. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/templates/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "template",
  "id": "t_2…",
  "name": "Order confirmation",
  "alias": "order-confirmation",
  "status": "published",
  "published_version": 3
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List templates

`GET https://delivrie.io/api/templates`

List templates.

Access: Needs a full access key.. MCP tool: `list_templates`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/templates' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "t_2…",
      "name": "Order confirmation",
      "alias": "order-confirmation",
      "status": "published"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Add suppression

`POST https://delivrie.io/api/suppressions`

Stop sending to one or more addresses.

Access: Needs a full access key.. MCP tool: `add_suppression`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string \| string[] | Yes | Address or addresses. |

## Example request

```bash
curl -X POST 'https://delivrie.io/api/suppressions' \
  -H 'Authorization: Bearer dlv_live_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "old@example.com"
  }'
```

## Response

```json
{
  "object": "suppression",
  "added": 1
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List suppressions

`GET https://delivrie.io/api/suppressions`

Up to 1,000 suppressed addresses with the reason.

Access: Needs a full access key.. MCP tool: `list_suppressions`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/suppressions' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "email": "old@example.com",
      "reason": "bounce"
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Remove suppression

`DELETE https://delivrie.io/api/suppressions/:email`

Allow sending to an address again.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | The suppressed address. |

## Example request

```bash
curl -X DELETE 'https://delivrie.io/api/suppressions/old@example.com' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "deleted": true
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Get usage

`GET https://delivrie.io/api/usage`

Your plan, emails sent this month and today, the allowance and daily limit, and pay-as-you-go credits.

Access: Any API key. MCP tool: `get_usage`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/usage' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "usage",
  "plan": "free",
  "emails_this_month": 1840,
  "monthly_allowance": 4000,
  "emails_today": 37,
  "daily_limit": 133,
  "credits_emails": 0,
  "overage_after_allowance": false
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Get metrics

`GET https://delivrie.io/api/metrics`

Daily totals and rates for delivery, opens, clicks, bounces and complaints.

Access: Needs a full access key.. MCP tool: `get_metrics`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `days` | number | No | Days to include, up to 90. Default: `15`. |
| `domain_id` | string | No | Only one domain. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/metrics' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "totals": {
    "sent": 17402,
    "delivered": 17247,
    "bounced": 104,
    "complained": 3
  },
  "rates": {
    "delivery": 0.991,
    "bounce": 0.006,
    "complaint": 0.0002
  }
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# List logs

`GET https://delivrie.io/api/logs`

Every API request, newest first.

Access: Needs a full access key..

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Results per page, 1 to 100. Default: `50`. |
| `offset` | number | No | How many results to skip. Default: `0`. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/logs' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "object": "list",
  "data": [
    {
      "id": "l_1…",
      "method": "POST",
      "endpoint": "/emails",
      "status": 200
    }
  ]
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Retrieve log

`GET https://delivrie.io/api/logs/:id`

One request with its request and response bodies.

Access: Needs a full access key.. MCP tool: `get_log`.

## Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | string | Yes | Bearer dlv_your_key |

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The log id. |

## Example request

```bash
curl -X GET 'https://delivrie.io/api/logs/4ef9a417' \
  -H 'Authorization: Bearer dlv_live_••••'
```

## Response

```json
{
  "id": "l_1…",
  "method": "POST",
  "endpoint": "/emails",
  "status": 200,
  "request_body": {},
  "response_body": {}
}
```

## Errors

| Status | Name | When |
| --- | --- | --- |
| 401 | `missing_api_key` | No Authorization header was sent. |
| 404 | `not_found` | Nothing with that id on this team. |


---

# Delivrie MCP server

Connect AI assistants to Delivrie with the remote MCP server at `https://delivrie.io/api/mcp` (streamable HTTP).
Clients that support OAuth open a Delivrie page where you pick the team and approve scopes (`send`, `read`, `manage`); revoke access under Settings → Connected apps.
Clients without OAuth can send an API key as `Authorization: Bearer dlv_your_key`.

## Install

### Claude (Claude Code, Desktop & claude.ai)

Remote · OAuth. terminal:

```bash
# Claude Code: opens a Delivrie page to approve access
claude mcp add --transport http delivrie https://delivrie.io/api/mcp

# Claude Desktop & claude.ai: Settings → Connectors → Add custom connector
# URL https://delivrie.io/api/mcp
```

### Cursor (Agent mode & Composer)

Remote · OAuth. ~/.cursor/mcp.json:

```json
{
  "mcpServers": {
    "delivrie": { "url": "https://delivrie.io/api/mcp" }
  }
}
```

### Codex (OpenAI Codex CLI & IDE)

Local bridge. ~/.codex/config.toml:

```toml
[mcp_servers.delivrie]
command = "npx"
args = ["-y", "mcp-remote", "https://delivrie.io/api/mcp"]
# mcp-remote opens the Delivrie approval page on first run
```

### v0 (v0 by Vercel)

Remote · API key. v0 → Settings → MCP connections:

```text
# Add a custom MCP connection
Name     Delivrie
URL      https://delivrie.io/api/mcp
Header   Authorization: Bearer dlv_live_••••
```

### Antigravity (Google Antigravity agents)

Remote · OAuth. Settings → Customizations → Open MCP Config, then Refresh and Authenticate:

```json
{
  "mcpServers": {
    "delivrie": { "serverUrl": "https://delivrie.io/api/mcp" }
  }
}
```

### VS Code (GitHub Copilot agent mode)

Remote · OAuth. terminal:

```bash
code --add-mcp '{"name":"delivrie","type":"http","url":"https://delivrie.io/api/mcp"}'
```

## Tools (64)

| Tool | What it does | Scope |
| --- | --- | --- |
| `send_email` | Send one email from a verified domain | send |
| `send_batch` | Send up to 100 emails in one call | send |
| `list_emails` | Recent sent emails with their latest status (delivered, opened, bounced…) | read |
| `get_email` | One email (sent or received) with its content and every delivery event | read |
| `reschedule_email` | Change when a scheduled email goes out | send |
| `cancel_email` | Cancel an email that is scheduled and not yet sent | send |
| `list_received_emails` | Emails that arrived on your receiving domains, newest first | read |
| `forward_email` | Forward an email (usually a received one) to other people, with an optional note | send |
| `list_inbox_threads` | Conversations in the Inbox | read |
| `get_inbox_thread` | A conversation with every message as plain text, oldest first | read |
| `reply_to_thread` | Reply in an Inbox conversation | send |
| `update_thread` | Archive or reopen a thread, mark it read or unread, or set its labels (labels are created if they don't exist) | send |
| `list_inbox_labels` | Labels you can put on inbox threads | read |
| `list_domains` | Sending domains with status, region, tracking and receiving settings | read |
| `get_domain` | A domain and the DNS records to add, with each record's status | read |
| `create_domain` | Add a sending domain and get its DNS records | manage |
| `verify_domain` | Check DNS now and update the domain's verification status | read |
| `update_domain` | Change tracking, TLS or receiving | manage |
| `delete_domain` | Remove a domain | manage |
| `claim_domain` | Start claiming a domain another Delivrie team added | manage |
| `verify_domain_claim` | Check the claim TXT record and move the domain to this team when it's found | manage |
| `list_contacts` | Contacts, newest first | read |
| `get_contact` | A contact by id or email | read |
| `create_contact` | Create or update a contact by email, optionally adding it to segments | manage |
| `update_contact` | Change a contact's name, properties or subscription | manage |
| `delete_contact` | Delete a contact | manage |
| `list_contact_properties` | Custom contact properties and their fallbacks | read |
| `list_segments` | Segments used to target broadcasts and automations | read |
| `create_segment` | Create a segment | manage |
| `add_contacts_to_segment` | Add contacts (by email) to a segment, creating them if needed | manage |
| `delete_segment` | Delete a segment (contacts stay) | manage |
| `list_topics` | Topics people can opt out of on the unsubscribe page | read |
| `list_broadcasts` | Broadcasts with status and schedule | read |
| `get_broadcast` | A broadcast with delivery stats | read |
| `create_broadcast` | Create a broadcast draft for a segment | manage |
| `send_broadcast` | Send a broadcast now, or schedule it with scheduled_at | manage |
| `cancel_broadcast` | Cancel a scheduled broadcast (it goes back to draft) | manage |
| `list_templates` | Templates with alias and published version | read |
| `get_template` | A template by id or alias, with its content and variables | read |
| `create_template` | Create a template | manage |
| `publish_template` | Publish the current draft so API sends and automations use it | manage |
| `list_automations` | Automations with trigger and status (draft, live, paused) | read |
| `get_automation` | An automation's trigger, steps and run counts | read |
| `create_automation` | Create a simple automation: a trigger (an event name or a segment) and a list of send/wait steps | manage |
| `publish_automation` | Publish (or republish) an automation so it starts running | manage |
| `pause_automation` | Pause a live automation | manage |
| `resume_automation` | Resume a paused automation | manage |
| `list_automation_runs` | Recent runs of an automation, with each step's log | read |
| `send_event` | Record an event for a contact (e.g | send |
| `list_events` | Without a name: every event your app has sent, with its fields | read |
| `list_webhooks` | Webhook endpoints and their events | read |
| `create_webhook` | Create a webhook endpoint | manage |
| `list_webhook_events` | Recent delivery attempts for a webhook with status codes | read |
| `test_webhook` | Send a test event to a webhook and return the response | manage |
| `replay_webhook_delivery` | Send a past webhook delivery again | manage |
| `list_suppressions` | Addresses Delivrie won't send to (bounces, complaints, manual) | read |
| `add_suppression` | Stop sending to one or more addresses | manage |
| `remove_suppression` | Allow sending to an address again | manage |
| `get_metrics` | Sent, delivered, opened, clicked, bounced and complained totals and rates | read |
| `list_logs` | Recent API requests with status codes | read |
| `get_log` | One API request with its request and response bodies | read |
| `get_usage` | Plan, emails sent this month and today, the allowance, and pay-as-you-go credits | read |
| `list_api_keys` | API keys (tokens are never shown) | read |
| `create_api_key` | Create an API key | manage |