# ZapSMTP

> Email API and SMTP relay: send, receive and track email.

- Base URL: `https://zapsmtp.xyz/v1`. Authenticate with `Authorization: Bearer <API key>`; JSON in and out.
- Test keys (`zap_test_…`) run the whole pipeline without delivering anything; send to `delivered@simulator.zapsmtp.xyz` (and the other [simulator addresses](https://www.zapsmtp.xyz/docs/testing.md)) to see each outcome.
- SDKs for Node.js, Python, PHP (and Laravel), Go, Ruby (and Rails), Java and .NET: https://www.zapsmtp.xyz/docs/sdks.md
- Keep API keys on the server. Sends take an `Idempotency-Key`; retry 429 and 5xx answers with backoff, honouring `Retry-After`.
- Errors: `{"statusCode", "name", "message", "error": {"code", "message", "type"}}`. OpenAPI 3.1: https://www.zapsmtp.xyz/openapi.json
- Every page below is Markdown; all of them in one file: https://www.zapsmtp.xyz/llms-full.txt


---

# Documentation

Source: https://www.zapsmtp.xyz/docs/

One HTTP request or an SMTP connection. Every example on these pages runs for real: paste a test key above and press **Try it**.

1. **Create an account and a test key.** [Sign up](https://zapsmtp.xyz/signup), open *API keys* and create a key in *test* mode. Test keys (`zap_test_…`) go through validation, logging, events and webhooks, but nothing is delivered and nothing counts against your plan.
2. **Send to the simulator.** Addresses at `simulator.zapsmtp.xyz` act out delivery scenarios: `delivered@`, `bounced@`, `complained@` and [more](https://www.zapsmtp.xyz/docs/testing/).
3. **Verify your domain and switch to a live key.** Add your domain, publish the DNS records it gives you and [verify it](https://www.zapsmtp.xyz/docs/domains/verify-domain/). Live keys send only from verified domains.

> Base URL `https://zapsmtp.xyz/v1`. Authenticate with `Authorization: Bearer <key>`. Requests and responses are JSON.

## Send your first email

`POST /v1/emails`

Send an email (or schedule it with scheduled_at).

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Hello from ZapSMTP",
  "html": "<p>It works.</p>"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Check what happened

`GET /v1/emails/{id}`

Retrieve one email with per-recipient status and its event timeline.

Requires a full-access key.

Only data inside the plan's log retention is visible. metadata may be null.

### Path parameters

- `id` (string, required): Email id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found (events can take a few seconds to appear)

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "from": "Acme <hello@acme.com>",
  "subject": "Your receipt",
  "created_at": "2026-10-21T15:04:10.902Z",
  "recipients": [
    {
      "email": "jane@example.org",
      "status": "delivered",
      "updated_at": "2026-10-21T15:04:12.381Z",
      "response": "250 2.0.0 OK 1761059052 x7si123"
    }
  ],
  "events": [
    {
      "type": "Reception",
      "status": "queued",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:10.902Z",
      "attempts": 0
    },
    {
      "type": "Delivery",
      "status": "delivered",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:12.381Z",
      "response_code": 250,
      "response": "250 2.0.0 OK 1761059052 x7si123",
      "attempts": 1,
      "mx": "gmail-smtp-in.l.google.com.",
      "peer_addr": "142.250.153.27",
      "tls": "TLSv1.3 TLS_AES_256_GCM_SHA384",
      "egress_source": "ip-1"
    }
  ],
  "stream": "transactional",
  "test": false,
  "metadata": {
    "order_id": "A-1042"
  }
}
```

## API reference

Billing, account settings and [team management](https://www.zapsmtp.xyz/docs/teams/) belong to the dashboard and are not in this reference. Team and client-account endpoints (accounts, members, invites) refuse API keys with `403 session_required`.

- [Emails](https://www.zapsmtp.xyz/docs/emails/): Send, schedule, batch and inspect email through the ZapSMTP API.
- [Domains](https://www.zapsmtp.xyz/docs/domains/): Add and verify sending domains; tracking, reply tracking, brand and reputation.
- [Webhooks](https://www.zapsmtp.xyz/docs/webhooks/): Receive signed delivery events, inspect attempts, replay and rotate secrets.
- [Click actions](https://www.zapsmtp.xyz/docs/actions/): Named buttons and links: tell clicks apart, describe them and see their activity.
- [Templates](https://www.zapsmtp.xyz/docs/templates/): Store email templates with Mustache variables and render previews.
- [Variables](https://www.zapsmtp.xyz/docs/variables/): The variable catalogue and the account’s global variables ({{global.key}}).
- [Modules, images & timers](https://www.zapsmtp.xyz/docs/template-library/): Saved modules, template images and countdown timers for the visual template editor.
- [Received emails](https://www.zapsmtp.xyz/docs/receiving/): Read inbound email: bodies, headers, authentication results and attachments.
- [Inbound setup](https://www.zapsmtp.xyz/docs/inbound/): Inbound addresses on managed or own domains, routing rules and stats.
- [Suppressions](https://www.zapsmtp.xyz/docs/suppressions/): Addresses ZapSMTP will not send to: hard bounces, complaints, unsubscribes.
- [Statistics](https://www.zapsmtp.xyz/docs/stats/): Delivery totals, time series, provider / bounce breakdowns and metrics by domain, stream or tag.
- [API keys & SMTP credentials](https://www.zapsmtp.xyz/docs/keys/): Create and revoke API keys and per-application SMTP credentials.
- [Logs & usage](https://www.zapsmtp.xyz/docs/logs/): Every API request with its bodies, and this month’s usage against your plan.
- [Simulator & dedicated IPs](https://www.zapsmtp.xyz/docs/platform/): Simulator addresses for testing and your dedicated sending IPs.

## Guides

- [SDKs and OpenAPI](https://www.zapsmtp.xyz/docs/sdks/): Libraries for Node.js, Python, PHP, Laravel, Go, Ruby, Java and .NET, and the OpenAPI description.
- [AI tools](https://www.zapsmtp.xyz/docs/ai-tools/): MCP server, Agent Skills, llms.txt and the CLI for coding assistants.
- [Sending email](https://www.zapsmtp.xyz/docs/sending/): Recipients, attachments, inline images, headers, tags, idempotency, scheduling, batches and retries.
- [Domains & DNS setup](https://www.zapsmtp.xyz/docs/domain-setup/): DKIM, SPF and DMARC step by step at Cloudflare, GoDaddy, Route 53 and more; troubleshooting.
- [Templates and variables](https://www.zapsmtp.xyz/docs/templating/): The template language with worked examples, typed variables with defaults, global values, and sending by id or alias.
- [Receiving email](https://www.zapsmtp.xyz/docs/inbound-guide/): Addresses, routes, the inbound webhook, attachments, conversations and replies.
- [Tracking and analytics](https://www.zapsmtp.xyz/docs/analytics/): Statuses, opens and clicks, filtering emails, metrics by domain, tag and provider, alerts.
- [Deliverability guide](https://www.zapsmtp.xyz/docs/deliverability/): Gmail and Yahoo sender rules, alignment, warm-up, unsubscribe, content and a launch checklist.
- [Recipes](https://www.zapsmtp.xyz/docs/recipes/): Ten end-to-end examples: password reset, receipts, welcome series, newsletters, support inbox.
- [Migrating to ZapSMTP](https://www.zapsmtp.xyz/docs/migration/): From Resend, SendGrid, Mailgun, Postmark or Amazon SES, with field maps and a rollout plan.
- [Dashboard tour](https://www.zapsmtp.xyz/docs/dashboard/): Sending health, email timelines, domains, keys, webhooks and inbound, screen by screen.
- [Email template editor](https://www.zapsmtp.xyz/docs/template-editor/): Gallery, visual editor, HTML with live preview, versions and sending by template id.
- [Errors, limits & paging](https://www.zapsmtp.xyz/docs/conventions/): Error shape and codes, rate limits, quotas, idempotency, pagination.
- [Testing & simulator](https://www.zapsmtp.xyz/docs/testing/): Test keys, simulator scenarios, bounce classification, spam checks.
- [SMTP relay](https://www.zapsmtp.xyz/docs/smtp/): Connect any mailer: hosts, ports, credentials and client examples.
- [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/): Event types, payloads, retries and signature verification.
- [Click actions](https://www.zapsmtp.xyz/docs/click-actions/): Name buttons and links, receive each click with its action, and route actions to their own endpoints.
- [Teams & client accounts](https://www.zapsmtp.xyz/docs/teams/): One login for many accounts: client accounts, invites and roles.

---

# Dashboard tour

Source: https://www.zapsmtp.xyz/docs/dashboard/

Everything the API does, you can see and do in the dashboard: how your mail lands, what happened to each message, and the settings behind it. The screenshots show a fictional store, Halden Outfitters, after a week of sending. [Create an account](https://zapsmtp.xyz/signup) to follow along.

## Sending health

*Overview* answers one question: is my mail getting through? Sent, delivery, bounce and complaint rates for the last 24 hours, 7 or 30 days, each marked against the thresholds mailbox providers use (bounces under 2%, complaints under 0.08%). Below them: activity over time, opens and clicks, the top links, results per sending domain, stream, tag and mailbox provider, and why mail bounced.

![The Overview page: sent, delivery rate 99.3%, bounce rate 0.52%, complaint rate 0.022%, and a week of email activity](https://www.zapsmtp.xyz/docs/img/overview-light.webp)

Overview: rates against provider thresholds and a week of activity.

## Every email, every event

*Emails* lists every message sent through the API or SMTP, with its current status. Filter by status (delivered, bounced, opened, clicked, complained, scheduled and more), stream and time range, or search by recipient, subject or id.

![The Emails list with recipients, subjects, statuses such as Delivered, Opened, Clicked and Bounced, and send times](https://www.zapsmtp.xyz/docs/img/emails-light.webp)

Open a message to see its timeline: when ZapSMTP accepted it, the receiving server's exact reply with its MX, IP and TLS version, opens and clicks, and for a bounce, why it failed and whether the address was suppressed. The message itself, its metadata and a spam check are on the same page.

![An email's page: recipients, metadata, a rendered preview and an event timeline from acceptance to delivery, open and click](https://www.zapsmtp.xyz/docs/img/email-detail-light.webp)

An email's timeline: the receiving server's exact reply for every attempt.

## Domains

Add the domain you send from and publish the records shown: a DKIM key we generate for it, plus SPF and DMARC. ZapSMTP checks DNS every minute until the domain verifies, then keeps watching it, along with the domain's reputation on public blocklists. The same page sets open and click tracking, TLS for outgoing mail and your brand in the inbox (BIMI).

![A verified domain with its DKIM, SPF and DMARC records, each marked Found, and a copy button for each value](https://www.zapsmtp.xyz/docs/img/domain-light.webp)

## API keys

Create a key per application or environment. A key can be limited to sending, to one domain and to one stream (transactional or broadcast); a test key goes through validation, logging and webhooks without delivering anything. A key is shown once, when you create it.

![API keys for the storefront, the order service, a newsletter tool, admin scripts and CI tests, with their permissions and last use](https://www.zapsmtp.xyz/docs/img/api-keys-light.webp)

## Webhooks

Point an endpoint at your server and pick the events it receives. Each endpoint shows its signing secret with verification code, a test button that sends a sample event, and the last 100 deliveries with your server's answer, so a failing endpoint is obvious and any delivery can be replayed. See [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/) for payloads.

![A webhook endpoint with its signing secret, a send-test-event form and recent deliveries with HTTP status codes and timings](https://www.zapsmtp.xyz/docs/img/webhook-light.webp)

## Inbound email

*Inbound* receives mail for your domains or a free ZapSMTP address, parses it to JSON and passes it to your webhook, with spam scores and SPF, DKIM and DMARC results. Replies and follow-ups are grouped into conversations, so a support inbox is a few API calls away.

![Inbound messages from customers, each received and routed to a webhook, and one rejected as spam](https://www.zapsmtp.xyz/docs/img/inbound-light.webp)

![A conversation about a tent pole replacement: two customer messages and one reply, with participants and the ticket id](https://www.zapsmtp.xyz/docs/img/thread-light.webp)

A conversation: messages in both directions, with your own metadata such as a ticket id.

## Suppressions

Hard bounces, spam complaints and unsubscribes are added automatically, so you never mail an address that hurts your reputation. An unsubscribe stops broadcast mail only; the other reasons stop every stream. Search the list, see what caused each entry, add addresses or remove one when a customer asks.

![The suppression list with hard bounces, an unsubscribe and a complaint, each with its source](https://www.zapsmtp.xyz/docs/img/suppressions-light.webp)

## On your phone

The whole dashboard works on a phone: lists become cards, and the template editor edits in the mobile view with its panels as sheets.

![The Emails list on a phone, each message a card with its status](https://www.zapsmtp.xyz/docs/img/phone-emails-light.webp)

![The visual template editor on a phone](https://www.zapsmtp.xyz/docs/img/phone-editor-light.webp)

---

# SDKs and OpenAPI

Source: https://www.zapsmtp.xyz/docs/sdks/

Official libraries for seven languages, Laravel and Rails. Every one covers the whole API and behaves the same way: it retries safely, walks every page of a list, raises typed errors and verifies webhook signatures.

> The packages are being published to their registries. Until they are, every example in the [API reference](https://www.zapsmtp.xyz/docs/) calls the HTTP API directly, and the [OpenAPI description](https://www.zapsmtp.xyz/openapi.json) is available now.

## Libraries

### Node.js

`npm install zapsmtp`

TypeScript types for every request and response; ESM and CommonJS; no dependencies.

Node.js 18+, Bun, Deno

### Python

`pip install zapsmtp`

Sync and async clients, typed models, httpx underneath.

Python 3.9+

### PHP

`composer require zapsmtp/zapsmtp-php`

PSR-18 HTTP client, Guzzle by default; typed models with array access.

PHP 8.1+

### Laravel

`composer require zapsmtp/zapsmtp-laravel`

A mail transport for your Mailables, a facade for the API and verified webhook events.

Laravel 10, 11, 12

### Go

`go get github.com/zapsmtp/zapsmtp-go`

Standard library only; context on every call; range over every page.

Go 1.23+

### Ruby

`gem install zapsmtp`

Standard library only; an ActionMailer delivery method for Rails.

Ruby 3.0+

### Java

`implementation("com.zapsmtp:zapsmtp-java:1.0.0")`

Builders for every request, immutable models, java.net.http underneath.

Java 11+

### .NET

`dotnet add package ZapSMTP`

Async API with cancellation, dependency injection, IAsyncEnumerable paging.

.NET 8, .NET Standard 2.0

## Send your first email

Create a test key in the dashboard (`zap_test_…`) and put it in `ZAP_API_KEY`. Test keys deliver nothing, and the simulator address acts out a delivery.

**Send an email**

Node.js:

```javascript
import { ZapSMTP } from 'zapsmtp';

const zap = new ZapSMTP(); // reads ZAP_API_KEY

const { id } = await zap.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'delivered@simulator.zapsmtp.xyz',
  subject: 'Hello from ZapSMTP',
  html: '<p>It works.</p>',
});
console.log(id);
```

Python:

```python
from zapsmtp import ZapSMTP

zap = ZapSMTP()  # reads ZAP_API_KEY

email = zap.emails.send(
    from_="Acme <hello@acme.com>",  # from is a Python keyword
    to="delivered@simulator.zapsmtp.xyz",
    subject="Hello from ZapSMTP",
    html="<p>It works.</p>",
)
print(email.id)
```

PHP:

```php
<?php
require 'vendor/autoload.php';

$zap = new \ZapSMTP\Client(); // reads ZAP_API_KEY

$email = $zap->emails->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'delivered@simulator.zapsmtp.xyz',
    'subject' => 'Hello from ZapSMTP',
    'html' => '<p>It works.</p>',
]);
echo $email->id;
```

Go:

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/zapsmtp/zapsmtp-go"
)

func main() {
	client := zapsmtp.NewClient("") // "" reads ZAP_API_KEY
	email, err := client.Emails.Send(context.Background(), &zapsmtp.SendEmailParams{
		From:    zapsmtp.String("Acme <hello@acme.com>"),
		To:      []string{"delivered@simulator.zapsmtp.xyz"},
		Subject: zapsmtp.String("Hello from ZapSMTP"),
		HTML:    zapsmtp.String("<p>It works.</p>"),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(email.ID)
}
```

Ruby:

```ruby
require "zapsmtp"

zap = ZapSMTP::Client.new # reads ZAP_API_KEY

email = zap.emails.send(
  from: "Acme <hello@acme.com>",
  to: "delivered@simulator.zapsmtp.xyz",
  subject: "Hello from ZapSMTP",
  html: "<p>It works.</p>"
)
puts email.id
```

Java:

```java
import com.zapsmtp.ZapSMTP;
import com.zapsmtp.params.SendEmailParams;

ZapSMTP zap = ZapSMTP.fromEnv(); // reads ZAP_API_KEY

var email = zap.emails().send(SendEmailParams.builder()
    .from("Acme <hello@acme.com>")
    .to("delivered@simulator.zapsmtp.xyz")
    .subject("Hello from ZapSMTP")
    .html("<p>It works.</p>")
    .build());
System.out.println(email.getId());
```

.NET:

```csharp
using ZapSMTP;

var zap = new ZapSMTPClient(); // reads ZAP_API_KEY

var email = await zap.Emails.SendAsync(new SendEmailParams
{
    From = "Acme <hello@acme.com>",
    To = new[] { "delivered@simulator.zapsmtp.xyz" },
    Subject = "Hello from ZapSMTP",
    Html = "<p>It works.</p>",
});
Console.WriteLine(email.Id);
```

## What every SDK does

- **The whole API.** Every endpoint in the reference, with types for its parameters and response. The libraries are generated from the same description as these pages, so a new endpoint reaches every language at once.
- **Safe retries.** Rate limits (`429`), server errors and lost connections are retried twice by default, waiting as `Retry-After` says or backing off exponentially. Sends always carry an `Idempotency-Key`, so a retried send never goes out twice; pass your own key to tie a send to your order or event.
- **Every page.** List methods return one page; each SDK can also iterate every item of every page.
- **Typed errors.** Authentication, permission, not found, conflict, validation, rate limit, server and connection errors are separate classes carrying the status, the error `code` and the request id. See [Errors, limits & paging](https://www.zapsmtp.xyz/docs/conventions/).
- **Webhook verification.** One call checks the `Zap-Signature` header in constant time, rejects signatures older than five minutes and accepts both secrets during a rotation.
- **Configuration.** The key comes from `ZAP_API_KEY` and the base URL from `ZAP_BASE_URL` when not passed in code. Timeouts, retries and extra headers can be set per client or per request.

## Verify a webhook

Pass the body exactly as it arrived, before parsing it. The call returns the event or throws. The payloads are described in [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/).

**Verify the signature**

Node.js:

```javascript
import { verifyWebhook } from 'zapsmtp';

// the raw body, before any JSON parsing
const event = verifyWebhook(rawBody, req.headers, process.env.ZAP_WEBHOOK_SECRET);
```

Python:

```python
from zapsmtp import verify_webhook

event = verify_webhook(request.get_data(), request.headers, os.environ["ZAP_WEBHOOK_SECRET"])
```

PHP:

```php
$event = \ZapSMTP\Webhook::verify(
    file_get_contents('php://input'),
    getallheaders(),
    getenv('ZAP_WEBHOOK_SECRET'),
);
```

Go:

```go
body, _ := io.ReadAll(r.Body)
event, err := zapsmtp.VerifyWebhook(body, r.Header.Get("Zap-Signature"), os.Getenv("ZAP_WEBHOOK_SECRET"))
```

Ruby:

```ruby
event = ZapSMTP::Webhook.verify(request.raw_post, request.headers, ENV.fetch("ZAP_WEBHOOK_SECRET"))
```

Java:

```java
WebhookEvent event = Webhooks.verify(rawBody, headers, System.getenv("ZAP_WEBHOOK_SECRET"));
```

.NET:

```csharp
var body = await new StreamReader(Request.Body).ReadToEndAsync();
var evt = Webhooks.Verify(body, Request.Headers["Zap-Signature"].ToString(), secret);
```

## Laravel and Rails

**Laravel.** Set `MAIL_MAILER=zapsmtp` and your Mailables go through the API: attachments, inline images, tags and metadata included. The package also gives a `ZapSMTP` facade for the whole API and a webhook route that checks signatures and fires Laravel events.

**Rails.** Set `config.action_mailer.delivery_method = :zapsmtp` and Action Mailer sends through the API. Pass tags, metadata or a template with `mail(zapsmtp: { tags: [...] })`. The gem includes a Rack middleware that verifies webhooks.

## OpenAPI

The whole API as an [OpenAPI 3.1 description](https://www.zapsmtp.xyz/openapi.json): every operation with its parameters, request and response schemas and documented errors. Import it into Postman or Insomnia, or generate a client for a language without an SDK (Rust, Elixir, Dart, Swift) with [OpenAPI Generator](https://openapi-generator.tech). Each operation's `x-sdk-method` names the SDK method that calls it.

## Other clients

Any SMTP library works too: [SMTP relay](https://www.zapsmtp.xyz/docs/smtp/). Moving from another provider: [Migrating to ZapSMTP](https://www.zapsmtp.xyz/docs/migration/).

---

# AI tools

Source: https://www.zapsmtp.xyz/docs/ai-tools/

Your coding assistant can work with ZapSMTP directly: send and inspect email through the MCP server, learn the API from Agent Skills and `llms.txt`, or drive everything from the command line.

> The MCP server, the CLI and the skills are being published. [llms.txt](https://www.zapsmtp.xyz/llms.txt) and the Markdown pages are available now.

- [MCP server](#mcp): Every API operation as a tool for Claude, Cursor, VS Code, Codex and any MCP client.
- [Agent Skills](#skills): Instructions that teach coding agents to send, verify webhooks, use templates and migrate correctly.
- [llms.txt](#llms): The docs for language models: an index, every page as Markdown and all of it in one file.
- [CLI](#cli): The whole API from your terminal or a script, with tables for people and JSON for tools.

## MCP server

`zapsmtp-mcp` gives an assistant one tool per API operation, generated from the same description as these pages, plus `send_test_email` (any delivery outcome on the simulator) and `verify_webhook_signature`. Create a key in the dashboard (a `zap_test_…` key delivers nothing) and add the server to your client:

**Add the MCP server**

Claude Code:

```
claude mcp add zapsmtp -e ZAP_API_KEY=zap_... -- npx -y zapsmtp-mcp
```

Claude Desktop:

```
// Settings → Developer → Edit Config (claude_desktop_config.json)
{
  "mcpServers": {
    "zapsmtp": {
      "command": "npx",
      "args": ["-y", "zapsmtp-mcp"],
      "env": { "ZAP_API_KEY": "zap_..." }
    }
  }
}
```

Cursor:

```
// ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project)
{
  "mcpServers": {
    "zapsmtp": {
      "command": "npx",
      "args": ["-y", "zapsmtp-mcp"],
      "env": { "ZAP_API_KEY": "zap_..." }
    }
  }
}
```

VS Code:

```
// .vscode/mcp.json: VS Code asks for the key once and keeps it
{
  "inputs": [
    { "type": "promptString", "id": "zapsmtp-key", "description": "ZapSMTP API key", "password": true }
  ],
  "servers": {
    "zapsmtp": {
      "command": "npx",
      "args": ["-y", "zapsmtp-mcp"],
      "env": { "ZAP_API_KEY": "${input:zapsmtp-key}" }
    }
  }
}
```

- **Choose what it can do.** `--toolsets emails,templates,simulator` keeps only those groups; `--read-only` keeps only reads. Tools carry read-only and destructive hints for clients that ask before acting.
- **Keep sends in bounds.** `--sender` sets the default From, and `--allowed-recipient-domains` refuses mail to any other domain. Sends carry an idempotency key, so a retried tool call never sends twice.
- **Serve a team.** `--http` runs Streamable HTTP at `/mcp`, where every client brings its own `Authorization: Bearer` key and the server holds none.
- **The docs come along.** `llms.txt` and every guide are bundled as MCP resources; nothing is fetched at runtime.

## Agent Skills

Skills are folders an agent loads when a task needs them. The `zapsmtp` skill routes to six others: sending email, webhooks, templates, receiving email, email best practices, and migrating from Resend, SendGrid, Mailgun, Postmark or Amazon SES. Every code sample in them is checked against the API before release.

**Install the skills**

Claude Code:

```
# in a checkout of the skills repository
DEST=.claude/skills            # or ~/.claude/skills for every project
mkdir -p "$DEST/zapsmtp"
cp -R SKILL.md LICENSE references "$DEST/zapsmtp/"
for s in zapsmtp-*/; do cp -R "$s" "$DEST/"; done
```

Cursor, Copilot, Codex:

```
# .agents/skills is read by Cursor, GitHub Copilot and OpenAI Codex alike
DEST=.agents/skills
mkdir -p "$DEST/zapsmtp"
cp -R SKILL.md LICENSE references "$DEST/zapsmtp/"
for s in zapsmtp-*/; do cp -R "$s" "$DEST/"; done
```

For a tool without skills support, put the relevant `SKILL.md` in its instruction file, such as `AGENTS.md` or `.github/copilot-instructions.md`.

## llms.txt and Markdown pages

- [`/llms.txt`](https://www.zapsmtp.xyz/llms.txt): what ZapSMTP is, how to authenticate and test, then every docs page with a one-line description ([llmstxt.org](https://llmstxt.org)).
- [`/llms-full.txt`](https://www.zapsmtp.xyz/llms-full.txt): every page in one file, for tools that load the whole context at once.
- Every docs page as Markdown: add `.md` to its path, for example [`/docs/sending.md`](https://www.zapsmtp.xyz/docs/sending.md) or [`/docs/emails/send-email.md`](https://www.zapsmtp.xyz/docs/emails/send-email.md).
- [`/openapi.json`](https://www.zapsmtp.xyz/openapi.json): the whole API in OpenAPI 3.1 with request and response schemas.

All of them are rebuilt with the docs, so they never fall behind the pages you read here.

## CLI

`zapsmtp` has a command for every API operation, with typed flags and `--help` for each. It prints tables in a terminal and JSON when piped, walks every page with `--all`, and exits non-zero on an API error with its code and request id.

**Use the CLI**

```
npm install -g zapsmtp-cli
zapsmtp login                       # checks the key, keeps it readable by you only
zapsmtp test                        # an email to the simulator, then its events
zapsmtp send --from "Acme <hello@acme.com>" --to jane@example.org \
  --subject "Your receipt" --html-file receipt.html --attach ./invoice.pdf
zapsmtp emails list --status bounced --all --json | jq '.[].to'
zapsmtp domains verify <domain-id>
```

---

# Recipes

Source: https://www.zapsmtp.xyz/docs/recipes/

Complete, end-to-end solutions to the jobs most apps need email for. Each recipe gives the API calls (sends, previews and reads run here with a test key; creating templates, domains, webhooks, inbound domains, API keys and thread metadata needs a full-access live key, since test keys get `403 test_key_restricted`) and the application code in Node.js, Python and Go or PHP. Keys always come from environment variables and every call runs on your server.

**On this page**

- Setup: one helper per language
- 1. Password reset with a template and an idempotency key
- 2. Order confirmation with line items and a PDF invoice
- 3. Welcome series: send now, day 2 and day 7, cancel on churn
- 4. Weekly newsletter: broadcast stream, one-click unsubscribe, batching
- 5. Bounces and complaints: webhooks, user flags, Slack alerts
- 6. Support inbox: receive, open a ticket, reply in the thread
- 7. Magic-link sign-in and CI tests with simulator addresses
- 8. Sending for many client domains (agencies)
- 9. Retries with exponential backoff and Retry-After
- 10. Next.js, Express, Django and Laravel

## Setup: one helper per language

The recipes share two small functions: `zap()` sends one API request and throws an error carrying the HTTP status, the error `code` (for example `rate_limit_exceeded`) and `Retry-After`; `verifyZapSignature()` checks a webhook’s `Zap-Signature` header as described in [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/#signatures). Save the file for your language next to your code.

**Environment**

- **`ZAP_API_KEY`**: A live key (`zap_…`) in production, a test key (`zap_test_…`) in development and CI. Test keys run the whole pipeline, accept any From domain and never deliver, but they can only send, preview templates, reply to received mail and read: one-time setup (templates, domains, webhooks, inbound domains, API keys, thread metadata, suppressions) needs a full-access live key. See [API keys](https://www.zapsmtp.xyz/docs/conventions/#keys).
- **`ZAP_WEBHOOK_SECRET`**: The `whsec_…` secret of your webhook endpoint, only where you receive webhooks.

**zap helper**

Node.js:

```javascript
// zap.mjs: Node.js 18+ (built-in fetch). Server-side only.
import crypto from 'node:crypto';

const API = 'https://zapsmtp.xyz/v1';

export class ZapError extends Error {
  constructor(status, body, headers) {
    super(`${status} ${body?.name ?? 'error'}: ${body?.message ?? ''}`);
    this.status = status;
    this.code = body?.name;
    this.retryAfter = Number(headers.get('Retry-After')) || 0; // seconds
    this.requestId = headers.get('X-Request-Id');
  }
}

export async function zap(method, path, body, headers = {}) {
  const res = await fetch(API + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.ZAP_API_KEY}`,
      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
      ...headers,
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const text = await res.text();
  let data = null;
  try { data = text ? JSON.parse(text) : null; } catch {}
  if (!res.ok) throw new ZapError(res.status, data, res.headers);
  return data;
}

// Webhooks: HMAC-SHA256 of "<t>.<raw body>", keyed with the whole whsec_ secret.
export function verifyZapSignature(rawBody, header, secret = process.env.ZAP_WEBHOOK_SECRET) {
  const parts = String(header ?? '').split(',').map((p) => p.split('='));
  const t = parts.find(([k]) => k === 't')?.[1] ?? '';
  if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  return parts.some(([k, v]) => k === 'v1' && v?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
}
```

Python:

```python
# zap.py: pip install requests. Server-side only.
import hashlib, hmac, os, time
import requests

API = "https://zapsmtp.xyz/v1"

class ZapError(Exception):
    def __init__(self, status, body, headers):
        body = body or {}
        super().__init__(f"{status} {body.get('name')}: {body.get('message')}")
        self.status, self.code = status, body.get("name")
        self.retry_after = float(headers.get("Retry-After") or 0)  # seconds
        self.request_id = headers.get("X-Request-Id")

def zap(method, path, body=None, headers=None):
    res = requests.request(method, API + path, json=body, timeout=30, headers={
        "Authorization": f"Bearer {os.environ['ZAP_API_KEY']}", **(headers or {})})
    try:
        data = res.json() if res.content else None
    except ValueError:
        data = None
    if not res.ok:
        raise ZapError(res.status_code, data, res.headers)
    return data

def verify_zap_signature(raw_body: bytes, header: str, secret: str | None = None) -> bool:
    secret = secret or os.environ["ZAP_WEBHOOK_SECRET"]
    parts = [p.split("=", 1) for p in (header or "").split(",") if "=" in p]
    t = next((v for k, v in parts if k == "t"), "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)
```

Go:

```go
// Package zap: a minimal ZapSMTP client. Server-side only.
package zap

import (
	"bytes"
	"context"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const API = "https://zapsmtp.xyz/v1"

type Error struct {
	Status     int
	Code       string
	Message    string
	RetryAfter time.Duration
}

func (e *Error) Error() string { return fmt.Sprintf("%d %s: %s", e.Status, e.Code, e.Message) }

// Do sends one request; out (may be nil) receives the JSON answer.
func Do(ctx context.Context, method, path string, body any, headers map[string]string, out any) error {
	var rd io.Reader
	if body != nil {
		b, err := json.Marshal(body)
		if err != nil {
			return err
		}
		rd = bytes.NewReader(b)
	}
	req, err := http.NewRequestWithContext(ctx, method, API+path, rd)
	if err != nil {
		return err
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("ZAP_API_KEY"))
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	for k, v := range headers {
		req.Header.Set(k, v)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	data, _ := io.ReadAll(res.Body)
	if res.StatusCode >= 300 {
		var e struct{ Name, Message string }
		json.Unmarshal(data, &e)
		secs, _ := strconv.Atoi(res.Header.Get("Retry-After"))
		return &Error{res.StatusCode, e.Name, e.Message, time.Duration(secs) * time.Second}
	}
	if out != nil && len(data) > 0 {
		return json.Unmarshal(data, out)
	}
	return nil
}

// VerifySignature checks Zap-Signature: HMAC-SHA256 of "<t>.<raw body>".
func VerifySignature(body []byte, header, secret string) bool {
	var t string
	var sigs []string
	for _, part := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(part, "=")
		switch k {
		case "t":
			t = v
		case "v1":
			sigs = append(sigs, v)
		}
	}
	ts, err := strconv.ParseInt(t, 10, 64)
	if err != nil || time.Since(time.Unix(ts, 0)).Abs() > 5*time.Minute {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(t + "."))
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))
	for _, s := range sigs {
		if hmac.Equal([]byte(s), []byte(expected)) {
			return true
		}
	}
	return false
}
```

PHP:

```php
<?php
// zap.php: PHP 8.1+ with ext-curl. Server-side only.
const ZAP_API = 'https://zapsmtp.xyz/v1';

final class ZapError extends RuntimeException
{
    public function __construct(public int $status, public string $zapCode, string $message, public float $retryAfter = 0)
    {
        parent::__construct("$status $zapCode: $message");
    }
}

function zap(string $method, string $path, ?array $body = null, array $headers = []): ?array
{
    $h = ['Authorization: Bearer ' . getenv('ZAP_API_KEY')];
    if ($body !== null) $h[] = 'Content-Type: application/json';
    foreach ($headers as $k => $v) $h[] = "$k: $v";
    $retryAfter = 0;
    $ch = curl_init(ZAP_API . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $h,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$retryAfter) {
            if (stripos($line, 'Retry-After:') === 0) $retryAfter = (float) trim(substr($line, 12));
            return strlen($line);
        },
    ]);
    if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    $raw = curl_exec($ch);
    if ($raw === false) throw new ZapError(0, 'network_error', curl_error($ch));
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $data = $raw === '' ? null : json_decode($raw, true);
    if ($status >= 300) throw new ZapError($status, $data['name'] ?? '', $data['message'] ?? '', $retryAfter);
    return $data;
}

function verify_zap_signature(string $body, string $header, ?string $secret = null): bool
{
    $secret ??= getenv('ZAP_WEBHOOK_SECRET');
    $t = '';
    $sigs = [];
    foreach (explode(',', $header) as $part) {
        [$k, $v] = array_pad(explode('=', $part, 2), 2, '');
        if ($k === 't') $t = $v;
        if ($k === 'v1') $sigs[] = $v;
    }
    if (!ctype_digit($t) || abs(time() - (int) $t) > 300) return false;
    $expected = hash_hmac('sha256', $t . '.' . $body, $secret);
    foreach ($sigs as $s) if (hash_equals($expected, $s)) return true;
    return false;
}
```

## 1. Password reset with a template and an idempotency key

**What you build:** a “forgot password” flow that emails a single-use, 30-minute link and can be retried safely after a timeout without sending two emails.

1. Create and publish a `password-reset` template once. Sends always use the published version.
2. Per request, generate a random token, store only its hash with an expiry, and send the template with `Idempotency-Key: password-reset-<token id>`.
3. Turn off open and click tracking for this email so the link is not rewritten.

## Create the reset template

`POST /v1/templates`

Once, at deploy time. `publish: true` makes it usable for sending right away.

Requires a full-access live key; test keys get 403 test_key_restricted.

Syntax: {{var}} escaped, {{{var}}} raw, {{#list}}…{{/list}} sections, {{^x}}…{{/x}} inverted sections. Exact ordering of variable_names is determined by the parser; the example order is illustrative.

Body: html and text both empty → 422 missing_required_field; template syntax errors → 422 template_render_error "<field>: <error>"; a tag that is not a variable name ({{first name}}, {{#each items}}, {{> footer}}) → 422 template_render_error "html: line L, column C: {{…}} is not a variable name: …"

`variable_schema` in the response is the saved list after discovery. A send is checked against the published copy, `published.variable_schema`.

### Body parameters

- `name` (string, required): Limits: trimmed, 1-200 characters → 422 missing_required_field "name is required (max 200 chars)"
- `alias` (string): Stable handle usable instead of the id (template.id in sends, /templates/{alias}). Limits: ^[a-z0-9][a-z0-9_-]{0,62}$ → 422 invalid_parameter; duplicate → 409 conflict
- `subject` (string): Mustache source.
- `html` (string): At least one of html and text is required. Mustache source; {{var}} is HTML-escaped, {{{var}}} raw.
- `text` (string)
- `from` (string): Default From used when a send omits from.
- `variables` (object): Sample variables used by previews. Never used for sending; a variable first found in the source takes its sample as `example`.
- `variable_schema` (object[]): Declares the template’s variables (see [Variable schema](https://www.zapsmtp.xyz/docs/templating/#schema)). Replaces the declared list when given. On every save, names the source uses that the list lacks are added (their sample value as example): a section {{#x}} as optional `any`, a dotted {{x.y}} as a required `object`, any other name as a required `any`, never stricter than sends were before, and declared names the source no longer uses are kept with `unused: true`. Limits: at most 200 entries, no duplicates, defaults and examples of their type → 422 invalid_parameter "variable_schema: <reason>"
  - `name` (string, required): Variable name: letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved.
  - `type` (string, required): What a send must pass. One of `string`, `number`, `boolean`, `url`, `date`, `list`, `object`, `any`.
  - `required` (boolean): A send without a value (or with `null`) and without a default is refused with `template_variables_missing`. Default `false`.
  - `default` (any): Used when a send gives no value; must be of `type`.
  - `example` (any): Used by previews; must be of `type`.
  - `description` (string): For your team; at most 500 bytes.
- `design` (object | null): The visual editor’s document (a JSON object with a numeric `version`), stored with the template. `null` makes it a code template. Changing `html` without sending `design` drops the design (it no longer describes the HTML). Limits: max 1 MB → 422 invalid_parameter "design is larger than 1 MB"; not an object with a numeric version → 422 invalid_parameter
- `publish` (boolean): Publish the result in the same call. Without it the template stays a draft and is not used for sending until [published](https://www.zapsmtp.xyz/docs/templates/publish-template/). Default `false`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): a template with this alias already exists
- `payload_too_large` (HTTP 413): request body too large (over 4 MB)
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422)
- `template_render_error` (HTTP 422): template syntax error: "<field>: <error>"
- `template_render_error` (HTTP 422): a tag that is not a variable name, e.g. {{first name}}, {{#each items}}, {{> footer}}: "html: line L, column C: {{…}} is not a variable name: letters, digits, _ and - (no spaces), parts joined with dots"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Password reset",
  "alias": "password-reset",
  "from": "Acme <security@acme.com>",
  "subject": "Reset your Acme password",
  "html": "<p>Hi {{first_name}},</p><p><a href=\"{{reset_url}}\">Choose a new password</a>. The link works once, for {{expires_minutes}} minutes.</p><p>Did not ask for this? Ignore this email; your password stays the same.</p>",
  "text": "Hi {{first_name}},\n\nChoose a new password: {{reset_url}}\nThe link works once, for {{expires_minutes}} minutes.\n\nDid not ask for this? Ignore this email.",
  "publish": true
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "name": "Receipt",
  "alias": "receipt",
  "subject": "Your receipt for {{order_id}}",
  "html": "<p>Hi {{name}}, thanks for order {{order_id}}.</p>",
  "text": "Hi {{name}}, thanks for order {{order_id}}.",
  "from": "Acme <billing@acme.com>",
  "variables": {
    "name": "Jane",
    "order_id": "A-1042"
  },
  "variable_schema": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "example": "A-1042",
      "description": "Order number shown to the customer"
    },
    {
      "name": "name",
      "type": "string",
      "required": false,
      "default": "there",
      "example": "Jane"
    }
  ],
  "design": null,
  "created_at": "2026-10-21T16:10:00Z",
  "updated_at": "2026-10-21T16:10:00Z",
  "object": "template",
  "variable_names": [
    "order_id",
    "name"
  ],
  "status": "draft",
  "has_unpublished_changes": false,
  "published_at": null,
  "published": null
}
```

## Send the reset email

`POST /v1/emails`

One call per reset request. The `Idempotency-Key` is tied to the reset token, so a retry after a timeout returns the first answer instead of sending a second email.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: password-reset-5b1e0c9a-2f7d-4c3e-9a10-6d8e7f2a1b34' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <security@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "template": {
    "id": "password-reset",
    "variables": {
      "first_name": "Ann",
      "reset_url": "https://acme.com/reset?id=5b1e0c9a&token=Xk2…",
      "expires_minutes": 30
    }
  },
  "tracking": {
    "opens": false,
    "clicks": false
  },
  "tags": [
    {
      "name": "category",
      "value": "password-reset"
    }
  ]
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

**Send a password reset**

Node.js:

```javascript
import crypto from 'node:crypto';
import { zap } from './zap.mjs';

// db is your own data layer.
export async function sendPasswordReset(email) {
  const user = await db.users.findByEmail(email);
  if (!user) return; // answer the caller the same way: never reveal who has an account

  const tokenId = crypto.randomUUID();
  const token = crypto.randomBytes(32).toString('base64url');
  await db.passwordResets.insert({
    id: tokenId,
    userId: user.id,
    tokenHash: crypto.createHash('sha256').update(token).digest('hex'), // store only the hash
    expiresAt: new Date(Date.now() + 30 * 60_000),
  });

  return zap('POST', '/emails', {
    from: 'Acme <security@acme.com>',
    to: [user.email],
    template: {
      id: 'password-reset',
      variables: {
        first_name: user.firstName,
        reset_url: `https://acme.com/reset?id=${tokenId}&token=${token}`,
        expires_minutes: 30,
      },
    },
    tracking: { opens: false, clicks: false }, // keep the link exactly as generated
    tags: [{ name: 'category', value: 'password-reset' }],
    metadata: { user_id: String(user.id) },
  }, { 'Idempotency-Key': `password-reset-${tokenId}` });
}
```

Python:

```python
import hashlib, secrets, uuid
from datetime import datetime, timedelta, timezone
from zap import zap

def send_password_reset(email: str):
    user = db.users.find_by_email(email)  # db is your own data layer
    if user is None:
        return  # same answer either way: never reveal who has an account

    token_id = str(uuid.uuid4())
    token = secrets.token_urlsafe(32)
    db.password_resets.insert(
        id=token_id, user_id=user.id,
        token_hash=hashlib.sha256(token.encode()).hexdigest(),
        expires_at=datetime.now(timezone.utc) + timedelta(minutes=30),
    )
    return zap("POST", "/emails", {
        "from": "Acme <security@acme.com>",
        "to": [user.email],
        "template": {"id": "password-reset", "variables": {
            "first_name": user.first_name,
            "reset_url": f"https://acme.com/reset?id={token_id}&token={token}",
            "expires_minutes": 30,
        }},
        "tracking": {"opens": False, "clicks": False},
        "tags": [{"name": "category", "value": "password-reset"}],
        "metadata": {"user_id": str(user.id)},
    }, headers={"Idempotency-Key": f"password-reset-{token_id}"})
```

Go:

```go
func SendPasswordReset(ctx context.Context, u User) error {
	tokenID := uuid.NewString() // github.com/google/uuid
	raw := make([]byte, 32)
	rand.Read(raw) // crypto/rand
	token := base64.RawURLEncoding.EncodeToString(raw)
	sum := sha256.Sum256([]byte(token))
	if err := db.SavePasswordReset(ctx, tokenID, u.ID, hex.EncodeToString(sum[:]), time.Now().Add(30*time.Minute)); err != nil {
		return err
	}
	body := map[string]any{
		"from": "Acme <security@acme.com>",
		"to":   []string{u.Email},
		"template": map[string]any{
			"id": "password-reset",
			"variables": map[string]any{
				"first_name":      u.FirstName,
				"reset_url":       "https://acme.com/reset?id=" + tokenID + "&token=" + token,
				"expires_minutes": 30,
			},
		},
		"tracking": map[string]bool{"opens": false, "clicks": false},
		"tags":     []map[string]string{{"name": "category", "value": "password-reset"}},
	}
	return zap.Do(ctx, "POST", "/emails", body, map[string]string{"Idempotency-Key": "password-reset-" + tokenID}, nil)
}
```

> The same key with a different body answers `409 idempotency_key_reused`; a key whose first attempt got a 429 or 5xx is released and can be retried. Keys are kept for 24 hours. The email log stores the sent content for your plan’s retention, so keep reset links short-lived and single-use.

## 2. Order confirmation with line items and a PDF invoice

**What you build:** a receipt whose table repeats over the order’s items, with the invoice attached as a PDF.

1. Create a template with a section, `{{#items}}…{{/items}}`, that repeats per item. Optional blocks such as a gift note use a section too and render only when the value is present.
2. Format money as strings in your code: templates are logic-less and print numbers as they are.
3. Preview with real data, then send with the PDF base64-encoded in `attachments[].content` and the order id as the idempotency key.

## Create the order template

`POST /v1/templates`

`{{#items}}…{{/items}}` repeats once per line item; inside it, names resolve against the item first. `{{#gift_note}}` renders only when the value is present and not empty.

Requires a full-access live key; test keys get 403 test_key_restricted.

Syntax: {{var}} escaped, {{{var}}} raw, {{#list}}…{{/list}} sections, {{^x}}…{{/x}} inverted sections. Exact ordering of variable_names is determined by the parser; the example order is illustrative.

Body: html and text both empty → 422 missing_required_field; template syntax errors → 422 template_render_error "<field>: <error>"; a tag that is not a variable name ({{first name}}, {{#each items}}, {{> footer}}) → 422 template_render_error "html: line L, column C: {{…}} is not a variable name: …"

`variable_schema` in the response is the saved list after discovery. A send is checked against the published copy, `published.variable_schema`.

### Body parameters

- `name` (string, required): Limits: trimmed, 1-200 characters → 422 missing_required_field "name is required (max 200 chars)"
- `alias` (string): Stable handle usable instead of the id (template.id in sends, /templates/{alias}). Limits: ^[a-z0-9][a-z0-9_-]{0,62}$ → 422 invalid_parameter; duplicate → 409 conflict
- `subject` (string): Mustache source.
- `html` (string): At least one of html and text is required. Mustache source; {{var}} is HTML-escaped, {{{var}}} raw.
- `text` (string)
- `from` (string): Default From used when a send omits from.
- `variables` (object): Sample variables used by previews. Never used for sending; a variable first found in the source takes its sample as `example`.
- `variable_schema` (object[]): Declares the template’s variables (see [Variable schema](https://www.zapsmtp.xyz/docs/templating/#schema)). Replaces the declared list when given. On every save, names the source uses that the list lacks are added (their sample value as example): a section {{#x}} as optional `any`, a dotted {{x.y}} as a required `object`, any other name as a required `any`, never stricter than sends were before, and declared names the source no longer uses are kept with `unused: true`. Limits: at most 200 entries, no duplicates, defaults and examples of their type → 422 invalid_parameter "variable_schema: <reason>"
  - `name` (string, required): Variable name: letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved.
  - `type` (string, required): What a send must pass. One of `string`, `number`, `boolean`, `url`, `date`, `list`, `object`, `any`.
  - `required` (boolean): A send without a value (or with `null`) and without a default is refused with `template_variables_missing`. Default `false`.
  - `default` (any): Used when a send gives no value; must be of `type`.
  - `example` (any): Used by previews; must be of `type`.
  - `description` (string): For your team; at most 500 bytes.
- `design` (object | null): The visual editor’s document (a JSON object with a numeric `version`), stored with the template. `null` makes it a code template. Changing `html` without sending `design` drops the design (it no longer describes the HTML). Limits: max 1 MB → 422 invalid_parameter "design is larger than 1 MB"; not an object with a numeric version → 422 invalid_parameter
- `publish` (boolean): Publish the result in the same call. Without it the template stays a draft and is not used for sending until [published](https://www.zapsmtp.xyz/docs/templates/publish-template/). Default `false`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): a template with this alias already exists
- `payload_too_large` (HTTP 413): request body too large (over 4 MB)
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422)
- `template_render_error` (HTTP 422): template syntax error: "<field>: <error>"
- `template_render_error` (HTTP 422): a tag that is not a variable name, e.g. {{first name}}, {{#each items}}, {{> footer}}: "html: line L, column C: {{…}} is not a variable name: letters, digits, _ and - (no spaces), parts joined with dots"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Order confirmation",
  "alias": "order-confirmation",
  "from": "Acme Shop <orders@acme.com>",
  "subject": "Order {{order_id}} confirmed",
  "html": "<h1>Thanks, {{customer.first_name}}!</h1><p>Order {{order_id}}</p><table>{{#items}}<tr><td>{{name}} × {{quantity}}</td><td align=\"right\">{{price}}</td></tr>{{/items}}</table><p>Total: <strong>{{total}}</strong></p>{{#gift_note}}<p>Gift note: {{gift_note}}</p>{{/gift_note}}<p>Your invoice is attached.</p>",
  "text": "Thanks, {{customer.first_name}}!\nOrder {{order_id}}\n{{#items}}- {{name}} x {{quantity}}: {{price}}\n{{/items}}Total: {{total}}",
  "publish": true
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "name": "Receipt",
  "alias": "receipt",
  "subject": "Your receipt for {{order_id}}",
  "html": "<p>Hi {{name}}, thanks for order {{order_id}}.</p>",
  "text": "Hi {{name}}, thanks for order {{order_id}}.",
  "from": "Acme <billing@acme.com>",
  "variables": {
    "name": "Jane",
    "order_id": "A-1042"
  },
  "variable_schema": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "example": "A-1042",
      "description": "Order number shown to the customer"
    },
    {
      "name": "name",
      "type": "string",
      "required": false,
      "default": "there",
      "example": "Jane"
    }
  ],
  "design": null,
  "created_at": "2026-10-21T16:10:00Z",
  "updated_at": "2026-10-21T16:10:00Z",
  "object": "template",
  "variable_names": [
    "order_id",
    "name"
  ],
  "status": "draft",
  "has_unpublished_changes": false,
  "published_at": null,
  "published": null
}
```

## Preview it with real data

`POST /v1/templates/{id}/render`

Renders the template without sending. A variable the template needs but the data lacks is reported here; a send would fail with `422 template_variables_missing` for a required variable (`template_render_error` only for a template published before variable schemas, or a field missing inside an object).

Requires a full-access key.

Missing variables do not fail the preview; they are listed in missing_variables.

### Path parameters

- `id` (string, required): Template id or alias

### Body parameters

- `variables` (object): Variables to render with; when omitted the template's stored sample variables are used.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): template not found
- `template_render_error` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/order-confirmation/render' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "variables": {
    "customer": {
      "first_name": "Ann"
    },
    "order_id": "A-1042",
    "items": [
      {
        "name": "Desk lamp",
        "quantity": 1,
        "price": "$49.00"
      },
      {
        "name": "LED bulb",
        "quantity": 2,
        "price": "$24.00"
      }
    ],
    "total": "$73.00"
  }
}'
```

**Response `200 OK`**

```json
{
  "subject": "Your receipt for A-1042",
  "html": "<p>Hi Jane, thanks for order A-1042.</p>",
  "text": "Hi Jane, thanks for order A-1042.",
  "missing_variables": [],
  "variable_names": [
    "order_id",
    "name"
  ],
  "design": null
}
```

## Send it with the invoice

`POST /v1/emails`

Attachments are base64 in `content` (or an HTTPS URL in `path` that ZapSMTP downloads). The whole JSON request is capped at 40 MB, base64 included (base64 adds about a third), so the files themselves can total only about 30 MB; a batch shares one 40 MB request. Larger requests get `413 payload_too_large`.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: order-A-1042-confirmation' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "template": {
    "id": "order-confirmation",
    "variables": {
      "customer": {
        "first_name": "Ann"
      },
      "order_id": "A-1042",
      "items": [
        {
          "name": "Desk lamp",
          "quantity": 1,
          "price": "$49.00"
        },
        {
          "name": "LED bulb",
          "quantity": 2,
          "price": "$24.00"
        }
      ],
      "total": "$73.00"
    }
  },
  "attachments": [
    {
      "filename": "invoice-A-1042.pdf",
      "content": "JVBERi0xLjQKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKMiAwIG9iago8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PgplbmRvYmoKMyAwIG9iago8PC9UeXBlL1BhZ2UvUGFyZW50IDIgMCBSL01lZGlhQm94WzAgMCAyMDAgMTAwXS9SZXNvdXJjZXM8PD4+L0NvbnRlbnRzIDQgMCBSPj4KZW5kb2JqCjQgMCBvYmoKPDwvTGVuZ3RoIDA+PgpzdHJlYW0KCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDUKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTQgMDAwMDAgbiAKMDAwMDAwMDEwNSAwMDAwMCBuIAowMDAwMDAwMTk5IDAwMDAwIG4gCnRyYWlsZXIKPDwvU2l6ZSA1L1Jvb3QgMSAwIFI+PgpzdGFydHhyZWYKMjQ2CiUlRU9GCg==",
      "content_type": "application/pdf"
    }
  ],
  "tags": [
    {
      "name": "category",
      "value": "order"
    }
  ],
  "metadata": {
    "order_id": "A-1042"
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

**Send an order confirmation**

Node.js:

```javascript
import { readFile } from 'node:fs/promises';
import { zap } from './zap.mjs';

const money = (cents, currency) =>
  new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(cents / 100);

export async function sendOrderConfirmation(order) {
  const pdf = await readFile(order.invoicePath); // or render it in memory
  return zap('POST', '/emails', {
    to: [order.customer.email],
    template: {
      id: 'order-confirmation', // its from and subject are used
      variables: {
        customer: { first_name: order.customer.firstName },
        order_id: order.id,
        items: order.items.map((i) => ({
          name: i.name, quantity: i.quantity, price: money(i.totalCents, order.currency),
        })),
        total: money(order.totalCents, order.currency),
        ...(order.giftNote && { gift_note: order.giftNote }),
      },
    },
    attachments: [{
      filename: `invoice-${order.id}.pdf`,
      content: pdf.toString('base64'),
      content_type: 'application/pdf',
    }],
    tags: [{ name: 'category', value: 'order' }],
    metadata: { order_id: order.id },
  }, { 'Idempotency-Key': `order-${order.id}-confirmation` });
}
```

Python:

```python
import base64
from babel.numbers import format_currency  # pip install babel, or format money your way
from zap import zap

def send_order_confirmation(order):
    with open(order.invoice_path, "rb") as f:
        pdf = base64.b64encode(f.read()).decode()
    variables = {
        "customer": {"first_name": order.customer.first_name},
        "order_id": order.id,
        "items": [{"name": i.name, "quantity": i.quantity,
                   "price": format_currency(i.total_cents / 100, order.currency, locale="en_US")}
                  for i in order.items],
        "total": format_currency(order.total_cents / 100, order.currency, locale="en_US"),
    }
    if order.gift_note:
        variables["gift_note"] = order.gift_note
    return zap("POST", "/emails", {
        "to": [order.customer.email],
        "template": {"id": "order-confirmation", "variables": variables},
        "attachments": [{"filename": f"invoice-{order.id}.pdf", "content": pdf,
                         "content_type": "application/pdf"}],
        "tags": [{"name": "category", "value": "order"}],
        "metadata": {"order_id": order.id},
    }, headers={"Idempotency-Key": f"order-{order.id}-confirmation"})
```

PHP:

```php
<?php
require_once 'zap.php';

function send_order_confirmation(array $order): array
{
    $fmt = new NumberFormatter('en_US', NumberFormatter::CURRENCY); // ext-intl
    $money = fn (int $cents) => $fmt->formatCurrency($cents / 100, $order['currency']);
    $variables = [
        'customer' => ['first_name' => $order['customer']['first_name']],
        'order_id' => $order['id'],
        'items' => array_map(fn ($i) => [
            'name' => $i['name'], 'quantity' => $i['quantity'], 'price' => $money($i['total_cents']),
        ], $order['items']),
        'total' => $money($order['total_cents']),
    ];
    if (!empty($order['gift_note'])) $variables['gift_note'] = $order['gift_note'];

    return zap('POST', '/emails', [
        'to' => [$order['customer']['email']],
        'template' => ['id' => 'order-confirmation', 'variables' => $variables],
        'attachments' => [[
            'filename' => "invoice-{$order['id']}.pdf",
            'content' => base64_encode(file_get_contents($order['invoice_path'])),
            'content_type' => 'application/pdf',
        ]],
        'tags' => [['name' => 'category', 'value' => 'order']],
        'metadata' => ['order_id' => $order['id']],
    ], ['Idempotency-Key' => "order-{$order['id']}-confirmation"]);
}
```

> A required variable the data does not contain fails the send with `422 template_variables_missing` and names it (a field missing inside an object, or any variable of a template published before variable schemas, fails with `422 template_render_error`). A section whose value is missing simply renders nothing. `from` and `subject` come from the template unless you pass them.

## 3. Welcome series: send now, day 2 and day 7, cancel on churn

**What you build:** three onboarding emails queued at signup, and a function that removes the unsent ones when the user unsubscribes or leaves.

1. At signup, send one batch: the first email without `scheduled_at`, the others with `"in 2 days"` and `"in 7 days"`.
2. Store the returned ids on the user.
3. On unsubscribe or churn, cancel each id; treat `409 not_cancellable` as done.

## Queue the whole series in one call

`POST /v1/emails/batch`

Each email in a batch can carry its own `scheduled_at`. In the default strict mode an email that fails validation stops the whole batch before anything is sent. Sending and scheduling then run per email, so a send-time failure (such as `rate_limit_exceeded`) affects only that email and is reported in `errors[]`: handle it.

Requires a full-access or sending-access key. Test keys follow the same rules as for sending.

Per-email error codes use the same classification as POST /emails (domain_not_verified, restricted_api_key, rate_limit_exceeded, monthly_quota_exceeded, etc. appear inside errors[] rather than as the HTTP status). Emails are sent concurrently (up to 16 at a time); each email may have its own scheduled_at.

Body: length 1-100 else 422 invalid_parameter "batch must contain 1 to 100 emails"

An item of `data` carries `reply_to` when reply tracking is on for that email.

### Headers

- `x-batch-validation` (string): strict (default) | permissive (case-insensitive). strict: if any email fails validation nothing is sent and 422 is returned. permissive: valid emails are sent; invalid ones are reported in errors.
- `Idempotency-Key` (string): optional, 1-256 bytes

### Body parameters

- `[ ]` (object[], required): 1–100 emails. Each item takes the fields of [Send an email](https://www.zapsmtp.xyz/docs/emails/send-email/).

### Errors

- `validation_error` (HTTP 400): invalid JSON or x-batch-validation not strict/permissive
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413)
- `invalid_parameter` (HTTP 422): batch size outside 1-100
- `validation_error` (HTTP 422): strict mode, any email invalid
- `service_unavailable` (HTTP 503): too many large bodies in flight

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: welcome-user-8812' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered@simulator.zapsmtp.xyz"
    ],
    "template": {
      "id": "welcome",
      "variables": {
        "first_name": "Ann"
      }
    },
    "tags": [
      {
        "name": "series",
        "value": "welcome"
      }
    ],
    "metadata": {
      "user_id": "8812"
    }
  },
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered@simulator.zapsmtp.xyz"
    ],
    "template": {
      "id": "welcome-day-2",
      "variables": {
        "first_name": "Ann"
      }
    },
    "scheduled_at": "in 2 days",
    "tags": [
      {
        "name": "series",
        "value": "welcome"
      }
    ],
    "metadata": {
      "user_id": "8812"
    }
  },
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered@simulator.zapsmtp.xyz"
    ],
    "template": {
      "id": "welcome-day-7",
      "variables": {
        "first_name": "Ann"
      }
    },
    "scheduled_at": "in 7 days",
    "tags": [
      {
        "name": "series",
        "value": "welcome"
      }
    ],
    "metadata": {
      "user_id": "8812"
    }
  }
]'
```

**Response `200 OK`**

```json
{
  "data": [
    {
      "index": 0,
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    },
    {
      "index": 2,
      "id": "019a1f2e-7c3c-7a10-8b21-4d5e6f7a8b9c",
      "suppressed": [
        "old@example.org"
      ]
    }
  ],
  "errors": [
    {
      "index": 1,
      "code": "missing_required_field",
      "message": "subject is required"
    }
  ]
}
```

## Cancel a pending step

`POST /v1/emails/{id}/cancel`

Call it for every stored id when the user unsubscribes, churns or deletes the account. `409 not_cancellable` means the email already went out (or the id is unknown): nothing left to stop.

Requires a full-access or sending-access key.

### Path parameters

- `id` (string, required): Scheduled email id

### Errors

- `restricted_api_key` (HTTP 403): this API key cannot manage this email (another domain or stream, or live mail with a test key)
- `not_cancellable` (HTTP 409): unknown id, already dispatched or already canceled

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/cancel' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f40-2b3c-7d4e-8f5a-6b7c8d9e0f12",
  "status": "canceled"
}
```

**Start and stop a welcome series**

Node.js:

```javascript
import { zap } from './zap.mjs';

const STEPS = [
  { template: 'welcome' },                                 // now
  { template: 'welcome-day-2', scheduled_at: 'in 2 days' },
  { template: 'welcome-day-7', scheduled_at: 'in 7 days' }, // 7 days is the scheduling limit
];

export async function startWelcomeSeries(user) {
  const emails = STEPS.map(({ template, scheduled_at }) => ({
    from: 'Acme <hello@acme.com>',
    to: [user.email],
    template: { id: template, variables: { first_name: user.firstName } },
    ...(scheduled_at && { scheduled_at }),
    tags: [{ name: 'series', value: 'welcome' }],
    metadata: { user_id: String(user.id) },
  }));
  const res = await zap('POST', '/emails/batch', emails, { 'Idempotency-Key': `welcome-${user.id}` });
  const ids = res.data.map((d) => d.id);
  // send-time failures (e.g. rate_limit_exceeded) come back per email: send those one by one
  for (const e of res.errors ?? []) {
    const one = await zap('POST', '/emails', emails[e.index], { 'Idempotency-Key': `welcome-${user.id}-${e.index}` });
    ids.push(one.id);
  }
  await db.users.update(user.id, { welcomeEmailIds: ids });
}

// On unsubscribe, churn or account deletion.
export async function stopWelcomeSeries(user) {
  for (const id of user.welcomeEmailIds ?? []) {
    try {
      await zap('POST', `/emails/${id}/cancel`);
    } catch (err) {
      if (err.code !== 'not_cancellable') throw err; // already sent: nothing to stop
    }
  }
  await db.users.update(user.id, { welcomeEmailIds: [] });
}
```

Python:

```python
from zap import zap, ZapError

STEPS = [("welcome", None), ("welcome-day-2", "in 2 days"), ("welcome-day-7", "in 7 days")]

def start_welcome_series(user):
    emails = []
    for template, when in STEPS:
        email = {
            "from": "Acme <hello@acme.com>",
            "to": [user.email],
            "template": {"id": template, "variables": {"first_name": user.first_name}},
            "tags": [{"name": "series", "value": "welcome"}],
            "metadata": {"user_id": str(user.id)},
        }
        if when:
            email["scheduled_at"] = when
        emails.append(email)
    res = zap("POST", "/emails/batch", emails, headers={"Idempotency-Key": f"welcome-{user.id}"})
    ids = [d["id"] for d in res["data"]]
    for e in res.get("errors", []):  # send-time failures, e.g. rate_limit_exceeded
        one = zap("POST", "/emails", emails[e["index"]],
                  headers={"Idempotency-Key": f"welcome-{user.id}-{e['index']}"})
        ids.append(one["id"])
    db.users.update(user.id, welcome_email_ids=ids)

def stop_welcome_series(user):
    for email_id in user.welcome_email_ids or []:
        try:
            zap("POST", f"/emails/{email_id}/cancel")
        except ZapError as e:
            if e.code != "not_cancellable":  # already sent: nothing to stop
                raise
    db.users.update(user.id, welcome_email_ids=[])
```

Go:

```go
type batchResult struct {
	Data   []struct{ ID string }
	Errors []struct {
		Index int
		Code  string
	}
}

func StartWelcomeSeries(ctx context.Context, u User) error {
	steps := []struct{ template, when string }{
		{"welcome", ""}, {"welcome-day-2", "in 2 days"}, {"welcome-day-7", "in 7 days"},
	}
	emails := make([]map[string]any, 0, len(steps))
	for _, s := range steps {
		e := map[string]any{
			"from":     "Acme <hello@acme.com>",
			"to":       []string{u.Email},
			"template": map[string]any{"id": s.template, "variables": map[string]any{"first_name": u.FirstName}},
			"tags":     []map[string]string{{"name": "series", "value": "welcome"}},
			"metadata": map[string]string{"user_id": u.ID},
		}
		if s.when != "" {
			e["scheduled_at"] = s.when
		}
		emails = append(emails, e)
	}
	var res batchResult
	if err := zap.Do(ctx, "POST", "/emails/batch", emails, map[string]string{"Idempotency-Key": "welcome-" + u.ID}, &res); err != nil {
		return err
	}
	ids := make([]string, 0, len(steps))
	for _, d := range res.Data {
		ids = append(ids, d.ID)
	}
	for _, e := range res.Errors { // send-time failures: retry one by one
		var one struct{ ID string }
		key := fmt.Sprintf("welcome-%s-%d", u.ID, e.Index)
		if err := zap.Do(ctx, "POST", "/emails", emails[e.Index], map[string]string{"Idempotency-Key": key}, &one); err != nil {
			return err
		}
		ids = append(ids, one.ID)
	}
	return db.SaveWelcomeEmailIDs(ctx, u.ID, ids)
}

func StopWelcomeSeries(ctx context.Context, u User) error {
	for _, id := range u.WelcomeEmailIDs {
		err := zap.Do(ctx, "POST", "/emails/"+id+"/cancel", nil, nil, nil)
		var zerr *zap.Error
		if err != nil && !(errors.As(err, &zerr) && zerr.Code == "not_cancellable") {
			return err
		}
	}
	return db.SaveWelcomeEmailIDs(ctx, u.ID, nil)
}
```

> Emails can be scheduled at most 7 days ahead and an account can hold 10,000 waiting emails. For longer or larger sequences, keep the schedule in your own job queue and send each step when it is due. When the time comes, the key and the account are checked again: a key revoked in the meantime fails the email. Keys restricted to a domain or a stream can only cancel the emails they scheduled themselves. To move a step instead of canceling it, use [PATCH /emails/{id}](https://www.zapsmtp.xyz/docs/emails/reschedule-email/).

## 4. Weekly newsletter: broadcast stream, one-click unsubscribe, batching

**What you build:** a weekly issue sent to every subscriber from a separate IP pool, with a working unsubscribe link and header, paced to your rate limit and safe to restart.

1. Put `{{{zap:unsubscribe_url}}}` in the template’s footer.
2. Send each subscriber their own email with `stream: "broadcast"`. Broadcast emails to a single recipient also get RFC 8058 `List-Unsubscribe` and `List-Unsubscribe-Post` headers, so mail apps show their own unsubscribe button.
3. Batch 100 emails per request with `x-batch-validation: permissive`. Resend the items that failed with `rate_limit_exceeded` after a pause; stop on `monthly_quota_exceeded` or `daily_quota_exceeded`.
4. Before each issue, pull new suppressions and drop those addresses from your list.

## A newsletter template with an unsubscribe link

`POST /v1/templates`

`{{{zap:unsubscribe_url}}}` becomes each recipient’s signed one-click unsubscribe link at send time. It is never reported as a missing variable.

Requires a full-access live key; test keys get 403 test_key_restricted.

Syntax: {{var}} escaped, {{{var}}} raw, {{#list}}…{{/list}} sections, {{^x}}…{{/x}} inverted sections. Exact ordering of variable_names is determined by the parser; the example order is illustrative.

Body: html and text both empty → 422 missing_required_field; template syntax errors → 422 template_render_error "<field>: <error>"; a tag that is not a variable name ({{first name}}, {{#each items}}, {{> footer}}) → 422 template_render_error "html: line L, column C: {{…}} is not a variable name: …"

`variable_schema` in the response is the saved list after discovery. A send is checked against the published copy, `published.variable_schema`.

### Body parameters

- `name` (string, required): Limits: trimmed, 1-200 characters → 422 missing_required_field "name is required (max 200 chars)"
- `alias` (string): Stable handle usable instead of the id (template.id in sends, /templates/{alias}). Limits: ^[a-z0-9][a-z0-9_-]{0,62}$ → 422 invalid_parameter; duplicate → 409 conflict
- `subject` (string): Mustache source.
- `html` (string): At least one of html and text is required. Mustache source; {{var}} is HTML-escaped, {{{var}}} raw.
- `text` (string)
- `from` (string): Default From used when a send omits from.
- `variables` (object): Sample variables used by previews. Never used for sending; a variable first found in the source takes its sample as `example`.
- `variable_schema` (object[]): Declares the template’s variables (see [Variable schema](https://www.zapsmtp.xyz/docs/templating/#schema)). Replaces the declared list when given. On every save, names the source uses that the list lacks are added (their sample value as example): a section {{#x}} as optional `any`, a dotted {{x.y}} as a required `object`, any other name as a required `any`, never stricter than sends were before, and declared names the source no longer uses are kept with `unused: true`. Limits: at most 200 entries, no duplicates, defaults and examples of their type → 422 invalid_parameter "variable_schema: <reason>"
  - `name` (string, required): Variable name: letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved.
  - `type` (string, required): What a send must pass. One of `string`, `number`, `boolean`, `url`, `date`, `list`, `object`, `any`.
  - `required` (boolean): A send without a value (or with `null`) and without a default is refused with `template_variables_missing`. Default `false`.
  - `default` (any): Used when a send gives no value; must be of `type`.
  - `example` (any): Used by previews; must be of `type`.
  - `description` (string): For your team; at most 500 bytes.
- `design` (object | null): The visual editor’s document (a JSON object with a numeric `version`), stored with the template. `null` makes it a code template. Changing `html` without sending `design` drops the design (it no longer describes the HTML). Limits: max 1 MB → 422 invalid_parameter "design is larger than 1 MB"; not an object with a numeric version → 422 invalid_parameter
- `publish` (boolean): Publish the result in the same call. Without it the template stays a draft and is not used for sending until [published](https://www.zapsmtp.xyz/docs/templates/publish-template/). Default `false`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): a template with this alias already exists
- `payload_too_large` (HTTP 413): request body too large (over 4 MB)
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422)
- `template_render_error` (HTTP 422): template syntax error: "<field>: <error>"
- `template_render_error` (HTTP 422): a tag that is not a variable name, e.g. {{first name}}, {{#each items}}, {{> footer}}: "html: line L, column C: {{…}} is not a variable name: letters, digits, _ and - (no spaces), parts joined with dots"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Acme Weekly",
  "alias": "weekly-newsletter",
  "from": "Acme Weekly <news@acme.com>",
  "subject": "{{title}}",
  "html": "<h1>{{title}}</h1>{{{body_html}}}<hr><p style=\"font-size:12px;color:#6b7280\">Hi {{first_name}}, you get Acme Weekly because you subscribed at acme.com. <a href=\"{{{zap:unsubscribe_url}}}\">Unsubscribe</a></p>",
  "text": "{{title}}\n\n{{body_text}}\n\nUnsubscribe: {{{zap:unsubscribe_url}}}",
  "publish": true
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "name": "Receipt",
  "alias": "receipt",
  "subject": "Your receipt for {{order_id}}",
  "html": "<p>Hi {{name}}, thanks for order {{order_id}}.</p>",
  "text": "Hi {{name}}, thanks for order {{order_id}}.",
  "from": "Acme <billing@acme.com>",
  "variables": {
    "name": "Jane",
    "order_id": "A-1042"
  },
  "variable_schema": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "example": "A-1042",
      "description": "Order number shown to the customer"
    },
    {
      "name": "name",
      "type": "string",
      "required": false,
      "default": "there",
      "example": "Jane"
    }
  ],
  "design": null,
  "created_at": "2026-10-21T16:10:00Z",
  "updated_at": "2026-10-21T16:10:00Z",
  "object": "template",
  "variable_names": [
    "order_id",
    "name"
  ],
  "status": "draft",
  "has_unpublished_changes": false,
  "published_at": null,
  "published": null
}
```

## Send one chunk on the broadcast stream

`POST /v1/emails/batch`

One recipient per email, up to 100 emails per request. `permissive` sends the valid emails and reports the rest in `errors[]`, together with send-time failures such as `rate_limit_exceeded`.

Requires a full-access or sending-access key. Test keys follow the same rules as for sending.

Per-email error codes use the same classification as POST /emails (domain_not_verified, restricted_api_key, rate_limit_exceeded, monthly_quota_exceeded, etc. appear inside errors[] rather than as the HTTP status). Emails are sent concurrently (up to 16 at a time); each email may have its own scheduled_at.

Body: length 1-100 else 422 invalid_parameter "batch must contain 1 to 100 emails"

An item of `data` carries `reply_to` when reply tracking is on for that email.

### Headers

- `x-batch-validation` (string): strict (default) | permissive (case-insensitive). strict: if any email fails validation nothing is sent and 422 is returned. permissive: valid emails are sent; invalid ones are reported in errors.
- `Idempotency-Key` (string): optional, 1-256 bytes

### Body parameters

- `[ ]` (object[], required): 1–100 emails. Each item takes the fields of [Send an email](https://www.zapsmtp.xyz/docs/emails/send-email/).

### Errors

- `validation_error` (HTTP 400): invalid JSON or x-batch-validation not strict/permissive
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413)
- `invalid_parameter` (HTTP 422): batch size outside 1-100
- `validation_error` (HTTP 422): strict mode, any email invalid
- `service_unavailable` (HTTP 503): too many large bodies in flight

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'x-batch-validation: permissive' \
  -H 'Idempotency-Key: newsletter-2026-43-chunk-0-attempt-0' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "to": [
      "delivered+ann@simulator.zapsmtp.xyz"
    ],
    "stream": "broadcast",
    "template": {
      "id": "weekly-newsletter",
      "variables": {
        "first_name": "Ann",
        "title": "Acme Weekly #43",
        "body_html": "<p>This week: faster exports.</p>",
        "body_text": "This week: faster exports."
      }
    },
    "tags": [
      {
        "name": "issue",
        "value": "2026-43"
      }
    ]
  },
  {
    "to": [
      "suppressed@simulator.zapsmtp.xyz"
    ],
    "stream": "broadcast",
    "template": {
      "id": "weekly-newsletter",
      "variables": {
        "first_name": "Bob",
        "title": "Acme Weekly #43",
        "body_html": "<p>This week: faster exports.</p>",
        "body_text": "This week: faster exports."
      }
    },
    "tags": [
      {
        "name": "issue",
        "value": "2026-43"
      }
    ]
  }
]'
```

**Response `200 OK`**

```json
{
  "data": [
    {
      "index": 0,
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    },
    {
      "index": 2,
      "id": "019a1f2e-7c3c-7a10-8b21-4d5e6f7a8b9c",
      "suppressed": [
        "old@example.org"
      ]
    }
  ],
  "errors": [
    {
      "index": 1,
      "code": "missing_required_field",
      "message": "subject is required"
    }
  ]
}
```

## Sync unsubscribes back to your list

`GET /v1/suppressions`

Newest first. `reason` is `unsubscribe`, `complaint`, `hard_bounce` or `manual`. Requires a full-access key.

Requires a full-access key.

`reason` is `hard_bounce`, `complaint`, `unsubscribe` or `manual`; `source_id` is the email that caused it (`null` when added by hand). Pass `next_cursor` as `after` for the next page.

`unsubscribe` stops only broadcast email (`stream: broadcast`); transactional email to the address still goes out. Every other reason stops all email to it.

### Query parameters

- `limit` (integer): 1-1000; out-of-range falls back to 100. Default `100`.
- `after` (string): Opaque cursor from next_cursor. Limits: 422 invalid_parameter "invalid after cursor"
- `before` (string): Legacy: RFC 3339 timestamp; returns entries created before it. Ignored when after is set. Limits: 422 invalid_parameter "before must be RFC3339"

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422)

```bash
curl 'https://zapsmtp.xyz/v1/suppressions?limit=1000' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "email": "old@example.org",
      "reason": "hard_bounce",
      "source_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "created_at": "2026-10-21T15:04:13Z"
    },
    {
      "email": "angry@example.net",
      "reason": "complaint",
      "source_id": "019a1f2a-1b2c-7d3e-8f4a-5b6c7d8e9f00",
      "created_at": "2026-10-21T11:20:40Z"
    }
  ],
  "next_cursor": "MTc2MTA0NzI0MDAwMDAwMDAwMHxhbmdyeUBleGFtcGxlLm5ldA"
}
```

**Send an issue**

Node.js:

```javascript
import { zap } from './zap.mjs';

const CHUNK = 100; // emails per batch request (the maximum)
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function sendIssue(issue, subscribers) { // subscribers: [{ email, firstName }]
  for (let start = 0; start < subscribers.length; start += CHUNK) {
    let pending = subscribers.slice(start, start + CHUNK).map((s) => ({
      to: [s.email], // one recipient per email: per-recipient unsubscribe link and header
      stream: 'broadcast',
      template: {
        id: 'weekly-newsletter',
        variables: { first_name: s.firstName, title: issue.title, body_html: issue.html, body_text: issue.text },
      },
      tags: [{ name: 'issue', value: issue.slug }],
    }));
    for (let attempt = 0; pending.length > 0; attempt++) {
      // a restarted job replays the same keys: no subscriber gets the issue twice
      const res = await zap('POST', '/emails/batch', pending, {
        'x-batch-validation': 'permissive',
        'Idempotency-Key': `newsletter-${issue.slug}-${start}-${attempt}`,
      });
      const retry = [];
      for (const e of res.errors ?? []) {
        if (e.code === 'rate_limit_exceeded') retry.push(pending[e.index]);
        else if (e.code.endsWith('quota_exceeded')) throw new Error(`stopped at ${start}: ${e.code}`);
        else console.warn('skipped', pending[e.index].to[0], e.code, e.message);
      }
      for (const d of res.data ?? []) {
        if (d.suppressed) await db.subscribers.markSuppressed(d.suppressed);
      }
      pending = retry;
      if (pending.length) await sleep(1000 * Math.min(30, 2 ** attempt)); // the budget refills every second
    }
  }
}

// Run before each issue, with the time of the previous sync.
export async function syncSuppressions(since) {
  let after;
  for (;;) {
    const q = new URLSearchParams({ limit: '1000', ...(after && { after }) });
    const page = await zap('GET', '/suppressions?' + q);
    for (const s of page.data) {
      if (new Date(s.created_at) < since) return;
      await db.subscribers.markSuppressed([s.email], s.reason);
    }
    if (!page.has_more) return;
    after = page.next_cursor;
  }
}
```

Python:

```python
import time
from datetime import datetime
from zap import zap

CHUNK = 100

def send_issue(issue, subscribers):
    for start in range(0, len(subscribers), CHUNK):
        pending = [{
            "to": [s.email],
            "stream": "broadcast",
            "template": {"id": "weekly-newsletter", "variables": {
                "first_name": s.first_name, "title": issue.title,
                "body_html": issue.html, "body_text": issue.text}},
            "tags": [{"name": "issue", "value": issue.slug}],
        } for s in subscribers[start:start + CHUNK]]
        attempt = 0
        while pending:
            res = zap("POST", "/emails/batch", pending, headers={
                "x-batch-validation": "permissive",
                "Idempotency-Key": f"newsletter-{issue.slug}-{start}-{attempt}"})
            retry = []
            for e in res.get("errors", []):
                if e["code"] == "rate_limit_exceeded":
                    retry.append(pending[e["index"]])
                elif e["code"].endswith("quota_exceeded"):
                    raise RuntimeError(f"stopped at {start}: {e['code']}")
                else:
                    print("skipped", pending[e["index"]]["to"][0], e["code"], e["message"])
            for d in res.get("data", []):
                if d.get("suppressed"):
                    db.subscribers.mark_suppressed(d["suppressed"])
            pending = retry
            if pending:
                time.sleep(min(30, 2 ** attempt))
            attempt += 1

def sync_suppressions(since: datetime):
    after = None
    while True:
        page = zap("GET", "/suppressions?limit=1000" + (f"&after={after}" if after else ""))
        for s in page["data"]:
            if datetime.fromisoformat(s["created_at"].replace("Z", "+00:00")) < since:
                return
            db.subscribers.mark_suppressed([s["email"]], s["reason"])
        if not page["has_more"]:
            return
        after = page["next_cursor"]
```

Go:

```go
func SendIssue(ctx context.Context, issue Issue, subs []Subscriber) error {
	const chunk = 100
	for start := 0; start < len(subs); start += chunk {
		var pending []map[string]any
		for _, s := range subs[start:min(start+chunk, len(subs))] {
			pending = append(pending, map[string]any{
				"to":     []string{s.Email},
				"stream": "broadcast",
				"template": map[string]any{"id": "weekly-newsletter", "variables": map[string]any{
					"first_name": s.FirstName, "title": issue.Title, "body_html": issue.HTML, "body_text": issue.Text}},
				"tags": []map[string]string{{"name": "issue", "value": issue.Slug}},
			})
		}
		for attempt := 0; len(pending) > 0; attempt++ {
			var res struct {
				Data []struct {
					ID         string
					Suppressed []string
				}
				Errors []struct {
					Index         int
					Code, Message string
				}
			}
			headers := map[string]string{
				"x-batch-validation": "permissive",
				"Idempotency-Key":    fmt.Sprintf("newsletter-%s-%d-%d", issue.Slug, start, attempt),
			}
			if err := zap.Do(ctx, "POST", "/emails/batch", pending, headers, &res); err != nil {
				return err
			}
			var retry []map[string]any
			for _, e := range res.Errors {
				switch {
				case e.Code == "rate_limit_exceeded":
					retry = append(retry, pending[e.Index])
				case strings.HasSuffix(e.Code, "quota_exceeded"):
					return fmt.Errorf("stopped at %d: %s", start, e.Code)
				default:
					log.Printf("skipped %v: %s %s", pending[e.Index]["to"], e.Code, e.Message)
				}
			}
			for _, d := range res.Data {
				if len(d.Suppressed) > 0 {
					db.MarkSuppressed(ctx, d.Suppressed)
				}
			}
			pending = retry
			if len(pending) > 0 {
				time.Sleep(time.Duration(min(30, 1<<attempt)) * time.Second)
			}
		}
	}
	return nil
}
```

> Your per-second budget counts recipients and is reported on send responses in `RateLimit-Limit` and `RateLimit-Remaining` (when your account has one); it refills every second. Unsubscribes go on the account’s suppression list with reason `unsubscribe` and stop broadcast mail only: someone who unsubscribes from the newsletter still gets receipts and password resets. Complaints and hard bounces stop every stream. Unsubscribes are not per list: if you need opt-outs per list, set your own `List-Unsubscribe` and `List-Unsubscribe-Post` headers pointing at your endpoint (ZapSMTP then leaves them as they are), do not use `zap:unsubscribe_url`, and keep the preference in your database.

## 5. Bounces and complaints: webhooks, user flags, Slack alerts

**What you build:** a webhook endpoint that flags bad addresses and complainers in your user table, and a scheduled check that posts to Slack when bounce or complaint rates climb.

1. Create a webhook for `email.bounced`, `email.complained` and `email.suppressed`.
2. Verify every request, skip `Zap-Event-Id`s you have handled, then act: `bounce.suppressed: true` means the address is dead; a complaint means stop marketing to it.
3. Every 15 minutes, read `GET /metrics` for the last 6 hours by stream and alert above your thresholds.

## Subscribe to the events that matter

`POST /v1/webhooks`

The response carries the `whsec_…` signing secret: put it in `ZAP_WEBHOOK_SECRET`.

Requires a full-access live key; test keys get 403 test_key_restricted.

The secret is also readable later via GET /webhooks/{id}.

To send clicks of one button to this endpoint: `{"events": ["email.clicked"], "filter": {"actions": ["confirm_order"]}}`. Endpoints always return `filter`, with an empty list when there is none.

### Body parameters

- `url` (string, required): Absolute https:// URL. Limits: 422 invalid_parameter "url must be an absolute https:// URL"
- `events` (string[]): Limits: unknown type → 422 invalid_parameter "unknown event type <x>; allowed: ..." One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `all event types`.
- `include_content` (boolean): `email.received` carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (`truncated: true`). Default `false`.
- `batch` (boolean): Send events up to 100 per request (or every second) as a JSON array, signed as one body; `Zap-Event-Id` is the batch id, each event keeps its own `id`. `email.received` with the full message still arrives alone. Default `false`.
- `filter` (object): Narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/); other event types are not affected. Empty or absent: every click. Default `{"actions": []}`.
  - `actions` (string[]): Action names (lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters). The endpoint then receives `email.clicked` only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/hooks/zapsmtp",
  "events": [
    "email.bounced",
    "email.complained",
    "email.suppressed"
  ]
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-21T15:40:00Z",
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": []
  }
}
```

**Handle bounce and complaint events**

Node.js:

```javascript
import express from 'express';
import { verifyZapSignature } from './zap.mjs';

const app = express();
// the signature covers the exact bytes: keep the raw body
app.post('/hooks/zapsmtp', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifyZapSignature(req.body, req.get('Zap-Signature'))) return res.sendStatus(400);
  const eventId = req.get('Zap-Event-Id'); // the same on every retry and replay
  if (await db.webhookEvents.seen(eventId)) return res.sendStatus(200);

  const { type, data } = JSON.parse(req.body);
  if (!data.test) { // events from test keys carry test: true
    const b = data.bounce; // { type, subType, message, suppressed }
    switch (type) {
      case 'email.bounced':
        // suppressed: a permanent mailbox or domain failure. Otherwise the problem is
        // on the sending side (SpamBlocked, PolicyRejected...) and the address is fine.
        if (b?.suppressed) await db.users.markEmailInvalid(data.to, b.subType);
        else console.warn('bounce, address kept', data.to, b?.subType, b?.message);
        break;
      case 'email.complained':
        await db.users.optOutOfMarketing(data.to);
        break;
      case 'email.suppressed': // we tried to email an address already on the list
        await db.users.markEmailInvalid(data.to, 'Suppressed');
        break;
    }
  }
  await db.webhookEvents.markSeen(eventId);
  res.sendStatus(200);
});
```

Python:

```python
import json
from flask import Flask, request
from zap import verify_zap_signature

app = Flask(__name__)

@app.post("/hooks/zapsmtp")
def zapsmtp_events():
    if not verify_zap_signature(request.get_data(), request.headers.get("Zap-Signature", "")):
        return "", 400
    event_id = request.headers["Zap-Event-Id"]  # stable across retries
    if db.webhook_events.seen(event_id):
        return "", 200
    event = json.loads(request.get_data())
    data, bounce = event["data"], event["data"].get("bounce") or {}
    if not data.get("test"):
        if event["type"] == "email.bounced":
            if bounce.get("suppressed"):
                db.users.mark_email_invalid(data["to"], bounce.get("subType"))
            else:
                app.logger.warning("bounce, address kept: %s %s", data["to"], bounce.get("subType"))
        elif event["type"] == "email.complained":
            db.users.opt_out_of_marketing(data["to"])
        elif event["type"] == "email.suppressed":
            db.users.mark_email_invalid(data["to"], "Suppressed")
    db.webhook_events.mark_seen(event_id)
    return "", 200
```

PHP:

```php
<?php
require_once 'zap.php';

$body = file_get_contents('php://input');
if (!verify_zap_signature($body, $_SERVER['HTTP_ZAP_SIGNATURE'] ?? '')) {
    http_response_code(400);
    exit;
}
$eventId = $_SERVER['HTTP_ZAP_EVENT_ID'];
if (!$db->webhookEventSeen($eventId)) {
    $event = json_decode($body, true);
    $data = $event['data'];
    $bounce = $data['bounce'] ?? [];
    if (empty($data['test'])) {
        match ($event['type']) {
            'email.bounced' => !empty($bounce['suppressed'])
                ? $db->markEmailInvalid($data['to'], $bounce['subType'])
                : error_log("bounce, address kept: {$data['to']} " . ($bounce['subType'] ?? '')),
            'email.complained' => $db->optOutOfMarketing($data['to']),
            'email.suppressed' => $db->markEmailInvalid($data['to'], 'Suppressed'),
            default => null,
        };
    }
    $db->markWebhookEventSeen($eventId);
}
http_response_code(200);
```

## Read the rates for alerting

`GET /v1/metrics`

Bounce rate is of `sent`, complaint rate of `delivered`. Test-mode mail is excluded. `dimension=stream` gives one row per stream, so a bad newsletter does not hide behind good receipts.

Requires a full-access key.

Counts are recipients, except `delayed`, `opened` and `clicked`: unique emails. Delivery and bounce rates are of `sent`; complaint, open and click rates of `delivered`. Test-mode mail is excluded. Kept for 400 days.

An out-of-band bounce (a later bounce email from the remote server) has no sending domain: it is grouped under an empty `value`.

Totals and the series count each email once whatever the dimension; with `dimension=tag` an email with several tags appears in each of its tags' groups.

### Query parameters

- `from` (string): RFC 3339 start. At most 400 days before `to`. Default `7 days ago`.
- `to` (string): RFC 3339 end (exclusive). Default `now`.
- `granularity` (string): `hour` (ranges up to 31 days) or `day` for `series`. Default `hour up to 48 hours, else day`.
- `dimension` (string): `domain`, `stream`, `tag` or `provider`: adds `groups`, one row per value, busiest first.
- `domain` (string): Only this sending (From) domain.
- `stream` (string): `transactional` or `broadcast`.
- `provider` (string): Gmail, Microsoft, Yahoo, Apple or Other.
- `tag` (string): Only emails with this tag, as `name=value`. Cannot be combined with domain, stream or provider, and groups only by `tag`.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): Bad time, range, granularity or dimension, or a tag combined with another filter.

```bash
curl 'https://zapsmtp.xyz/v1/metrics?from=2026-10-26T06%3A00%3A00Z&to=2026-10-26T12%3A00%3A00Z&dimension=stream' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "metrics",
  "from": "2026-10-18T00:00:00Z",
  "to": "2026-10-25T00:00:00Z",
  "granularity": "day",
  "dimension": "domain",
  "totals": {
    "sent": 12400,
    "delivered": 12210,
    "bounced": 95,
    "delayed": 3,
    "complained": 4,
    "opened": 4380,
    "human_opened": 2409,
    "clicked": 912,
    "suppressed": 2,
    "failed": 0,
    "delivery_rate": 0.9847,
    "bounce_rate": 0.0077,
    "complaint_rate": 0.0003,
    "open_rate": 0.3587,
    "human_open_rate": 0.1972,
    "click_rate": 0.0747
  },
  "series": [
    {
      "time": "2026-10-18T00:00:00Z",
      "sent": 1700,
      "delivered": 1676,
      "bounced": 14,
      "delayed": 3,
      "complained": 1,
      "opened": 601,
      "human_opened": 331,
      "clicked": 120,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9859,
      "bounce_rate": 0.0082,
      "complaint_rate": 0.0006,
      "open_rate": 0.3586,
      "human_open_rate": 0.1974,
      "click_rate": 0.0716
    }
  ],
  "groups": [
    {
      "value": "acme.com",
      "sent": 9800,
      "delivered": 9668,
      "bounced": 70,
      "delayed": 3,
      "complained": 3,
      "opened": 3540,
      "human_opened": 1947,
      "clicked": 760,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9865,
      "bounce_rate": 0.0071,
      "complaint_rate": 0.0003,
      "open_rate": 0.3662,
      "human_open_rate": 0.2013,
      "click_rate": 0.0786
    },
    {
      "value": "news.acme.com",
      "sent": 2600,
      "delivered": 2542,
      "bounced": 25,
      "delayed": 3,
      "complained": 1,
      "opened": 840,
      "human_opened": 462,
      "clicked": 152,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9777,
      "bounce_rate": 0.0096,
      "complaint_rate": 0.0004,
      "open_rate": 0.3304,
      "human_open_rate": 0.1817,
      "click_rate": 0.0598
    }
  ]
}
```

**Alert Slack when rates rise**

Node.js:

```javascript
// Run every 15 minutes (cron, a scheduled job). Needs a full-access key.
import { zap } from './zap.mjs';

const LIMITS = { bounce_rate: 0.04, complaint_rate: 0.001 }; // pick your own thresholds
const MIN_SENT = 200; // ignore tiny samples

export async function checkRates() {
  const to = new Date();
  const from = new Date(to.getTime() - 6 * 3600_000);
  const q = new URLSearchParams({ from: from.toISOString(), to: to.toISOString(), dimension: 'stream' });
  const m = await zap('GET', '/metrics?' + q);
  const alerts = m.groups
    .filter((g) => g.sent >= MIN_SENT)
    .flatMap((g) => Object.entries(LIMITS)
      .filter(([rate, max]) => g[rate] > max)
      .map(([rate, max]) => `${g.value}: ${rate} ${(g[rate] * 100).toFixed(2)}% (limit ${max * 100}%), ${g.sent} sent in 6 h`));
  if (alerts.length) {
    await fetch(process.env.SLACK_WEBHOOK_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: 'ZapSMTP rates over the limit:\n' + alerts.join('\n') }),
    });
  }
}
```

Python:

```python
import os
from datetime import datetime, timedelta, timezone
from urllib.parse import urlencode
import requests
from zap import zap

LIMITS = {"bounce_rate": 0.04, "complaint_rate": 0.001}
MIN_SENT = 200

def check_rates():
    to = datetime.now(timezone.utc).replace(microsecond=0)
    q = urlencode({"from": (to - timedelta(hours=6)).isoformat(), "to": to.isoformat(), "dimension": "stream"})
    m = zap("GET", "/metrics?" + q)
    alerts = [
        f"{g['value']}: {rate} {g[rate] * 100:.2f}% (limit {limit * 100}%), {g['sent']} sent in 6 h"
        for g in m["groups"] if g["sent"] >= MIN_SENT
        for rate, limit in LIMITS.items() if g[rate] > limit
    ]
    if alerts:
        requests.post(os.environ["SLACK_WEBHOOK_URL"], timeout=10,
                      json={"text": "ZapSMTP rates over the limit:\n" + "\n".join(alerts)})
```

PHP:

```php
<?php
require_once 'zap.php';

$limits = ['bounce_rate' => 0.04, 'complaint_rate' => 0.001];
$to = new DateTimeImmutable('now', new DateTimeZone('UTC'));
$q = http_build_query([
    'from' => $to->modify('-6 hours')->format(DATE_RFC3339),
    'to' => $to->format(DATE_RFC3339),
    'dimension' => 'stream',
]);
$m = zap('GET', '/metrics?' . $q);
$alerts = [];
foreach ($m['groups'] as $g) {
    if ($g['sent'] < 200) continue;
    foreach ($limits as $rate => $max) {
        if ($g[$rate] > $max) {
            $alerts[] = sprintf('%s: %s %.2f%% (limit %s%%), %d sent in 6 h', $g['value'], $rate, $g[$rate] * 100, $max * 100, $g['sent']);
        }
    }
}
if ($alerts) {
    $ch = curl_init(getenv('SLACK_WEBHOOK_URL'));
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(['text' => "ZapSMTP rates over the limit:\n" . implode("\n", $alerts)]),
        CURLOPT_RETURNTRANSFER => true,
    ]);
    curl_exec($ch);
}
```

> One event is sent per recipient, so `data.to` is a single address. ZapSMTP already suppresses hard-bounced and complaining addresses for you; the handler keeps your own records in step. Answer with a 2xx quickly. Network errors, timeouts, 5xx, 408 and 429 are retried for about 28 hours; any other 4xx ends delivery of that event at once, so do not answer 4xx for a temporary problem on your side. The 4% and 0.1% thresholds above are examples; choose your own. Details: [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/), [bounce classification](https://www.zapsmtp.xyz/docs/testing/#bounces).

## 6. Support inbox: receive, open a ticket, reply in the thread

**What you build:** customers write to `support@help.acme.com`; each new conversation becomes a ticket with an automatic acknowledgement; follow-ups attach to the same ticket; agents answer from your UI and the customer sees one email thread.

1. Add `help.acme.com` as an inbound domain and publish its MX record.
2. Create a webhook for `thread.created` and `thread.replied`.
3. On `thread.created`: create the ticket, store `thread_id` and `email_id`, tag the conversation with the ticket id and send an acknowledgement with `auto_reply: true`.
4. On `thread.replied`: add `reply_text` (the new text without the quoted history) to the ticket.
5. Agents answer with `POST /emails/receiving/{id}/reply` on the latest received email.

## Receive on a subdomain

`POST /v1/inbound/domains`

Your own domain (or its parent) must already be verified for sending. Publish the MX record from the response and call [verify](https://www.zapsmtp.xyz/docs/inbound/verify-inbound-domain/). For a quick test, `{"managed": true}` gives an instant address with no DNS.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `managed` (boolean): true: create an instant managed domain <10 random lowercase chars>.<inbound zone>; no DNS needed; name is ignored. Default `False`.
- `name` (string): Required unless managed is true. Your own domain. It (or a parent) must be verified for sending by the account. Then publish MX 10 <inbound host> and call verify. Limits: invalid → 422 invalid_parameter "invalid domain name"; ZapSMTP-owned names → 422 reserved_domain; not verified for sending → 403 domain_not_verified
- `reject_spam` (boolean): Refuse messages flagged as spam at SMTP time instead of delivering them with is_spam: true. Default `False`.
- `require_tls` (boolean): Accept encrypted mail only: senders without STARTTLS are refused with 530 5.7.0.

### Errors

- `domain_not_verified` (HTTP 403): verify <name> (or its parent domain) for sending first; inbound reuses that proof of ownership
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): this domain already receives mail on ZapSMTP
- `invalid_parameter` (HTTP 422): invalid domain name
- `reserved_domain` (HTTP 422): this domain is reserved by ZapSMTP; use a managed address or your own domain
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "help.acme.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f20-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
  "name": "k3f9x2m7q1.in.zapsmtp.xyz",
  "managed": true,
  "reject_spam": false,
  "mx_verified": true,
  "last_checked_at": "2026-10-21T15:00:00Z",
  "created_at": "2026-10-21T15:00:00Z",
  "records": [],
  "example_address": "anything@k3f9x2m7q1.in.zapsmtp.xyz"
}
```

## Subscribe to conversation events

`POST /v1/webhooks`

`thread.created` fires for a message that answers nothing (a new ticket), `thread.replied` for an answer in an existing conversation. Neither fires for bounces, out-of-office, auto-replies or auto-generated notifications. Bulk and mailing-list mail (`Precedence: bulk`, `List-Id`, `List-Unsubscribe`) is classified as automated but still produces these events: check `automated.type === "bulk"` if newsletters should not open tickets.

Requires a full-access live key; test keys get 403 test_key_restricted.

The secret is also readable later via GET /webhooks/{id}.

To send clicks of one button to this endpoint: `{"events": ["email.clicked"], "filter": {"actions": ["confirm_order"]}}`. Endpoints always return `filter`, with an empty list when there is none.

### Body parameters

- `url` (string, required): Absolute https:// URL. Limits: 422 invalid_parameter "url must be an absolute https:// URL"
- `events` (string[]): Limits: unknown type → 422 invalid_parameter "unknown event type <x>; allowed: ..." One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `all event types`.
- `include_content` (boolean): `email.received` carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (`truncated: true`). Default `false`.
- `batch` (boolean): Send events up to 100 per request (or every second) as a JSON array, signed as one body; `Zap-Event-Id` is the batch id, each event keeps its own `id`. `email.received` with the full message still arrives alone. Default `false`.
- `filter` (object): Narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/); other event types are not affected. Empty or absent: every click. Default `{"actions": []}`.
  - `actions` (string[]): Action names (lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters). The endpoint then receives `email.clicked` only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/hooks/support",
  "events": [
    "thread.created",
    "thread.replied"
  ]
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-21T15:40:00Z",
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": []
  }
}
```

## Link the conversation to the ticket

`PATCH /v1/threads/{id}`

Conversation metadata shows in the dashboard inbox and in `GET /threads`, so anyone can jump from an email to the ticket.

Requires a full-access live key; test keys get 403 test_key_restricted.

Omitted fields are kept.

### Path parameters

- `id` (string (UUID), required): Thread id

### Body parameters

- `read` (boolean): `true` sets `read_at` to now (unread again once a new email arrives); `false` clears it.
- `metadata` (object): Your own key-value pairs (a ticket id, a CRM deal), replacing the previous ones. Limits: at most 20 keys matching [A-Za-z0-9_-]{1,40}, values up to 500 bytes (UTF-8) (422 invalid_parameter).

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): thread not found
- `invalid_parameter` (HTTP 422): metadata limits

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/threads/3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket": "T-1042"
  }
}'
```

**Response `200 OK`**

```json
{
  "object": "thread",
  "id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
  "subject": "Where is my order?",
  "participants": [
    "jane@example.org",
    "support@acme.com"
  ],
  "message_count": 3,
  "inbound_count": 2,
  "outbound_count": 1,
  "has_attachments": false,
  "first_message_at": "2026-10-21T15:10:02.904Z",
  "last_message_at": "2026-10-21T16:02:13.540Z",
  "last_inbound_at": "2026-10-21T16:02:13.540Z",
  "last_message": {
    "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
    "direction": "inbound",
    "from": "jane@example.org",
    "subject": "Re: Where is my order?"
  },
  "awaiting_reply": true,
  "unread": false,
  "read_at": "2026-10-21T16:05:00.000Z",
  "metadata": {
    "ticket": "T-1042"
  }
}
```

## Acknowledge in the same thread

`POST /v1/emails/receiving/{id}/reply`

Recipients, `Re:` subject and `In-Reply-To`/`References` default from the received email. Replying from another address sets `reply_to` to the receiving one, so the customer’s answer comes back to the inbox. `auto_reply: true` marks the message as automatic (RFC 3834).

Requires a full-access key. Live keys: the From domain must be verified for sending.

Our Message-ID of the reply names its thread, so the customer's answer joins the conversation even from a mail client that keeps only `In-Reply-To`.

Every other rule of `POST /emails` applies: suppressions, quotas, tracking, test keys.

Loop protection: replies to automated email need `allow_automated`, and one conversation takes at most 20 replies an hour.

### Path parameters

- `id` (string (UUID), required): Received email id

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `text` (string): Plain-text body. Either text or html (or a template) is required.
- `html` (string): HTML body.
- `from` (string): Default: the address that received the email (e.g. `support@acme.com`), which must be on a verified sending domain. Required when the email came to a managed `*.in.zapsmtp.xyz` address (those only receive): 422 missing_required_field.
- `to` (string | string[]): Default: the email's Reply-To, else its From. Limits: 422 missing_required_field when the email has neither.
- `reply_all` (boolean): Also copy everyone on the email's To and Cc, except the receiving address, the sender you reply from and anyone already addressed. Default `false`.
- `allow_automated` (boolean): Answer an automated email anyway (see `automated` on the received email). Without it a reply to a bounce, out-of-office, auto-reply or notification is refused with 422 automated_message: two auto-responders answering each other is a mail loop. Bulk mail can be answered without it. Default `false`.
- `auto_reply` (boolean): This answer is itself automatic (an acknowledgement, a ticket receipt): adds `Auto-Submitted: auto-replied` and `X-Auto-Response-Suppress: All` (RFC 3834), so other auto-responders do not answer it. Default `false`.
- `cc` (string | string[]): Added to the Cc (reply_all adds the email's recipients after these).
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Default: the receiving address when you reply from another one, so the customer's answer comes back to the same inbox.
- `subject` (string): Default: `Re: ` + the email's subject (kept as is when it already starts with Re:).
- `headers` (object): Custom headers. `In-Reply-To` and `References` are set for you (RFC 5322 threading); a value you give wins.
- `attachments, tags, metadata, stream, tracking, template, scheduled_at`: As in [POST /emails](https://www.zapsmtp.xyz/docs/emails/send-email/).

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `missing_required_field` (HTTP 422): from (managed receiving address), to (no sender on the email), or the body
- `automated_message` (HTTP 422): the email is a bounce, out-of-office, auto-reply or notification; pass allow_automated: true
- `rate_limit_exceeded` (HTTP 429)
- `thread_reply_limit` (HTTP 429): too many replies in this conversation in the last hour (a mail loop?); at most 20 per hour; Retry-After: 3600
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/receiving/019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d/reply' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: ack-019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme Support <support@acme.com>",
  "text": "Thanks for writing. Your ticket is T-1042; a person will answer within one business day.",
  "auto_reply": true
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f41-8b2c-7e3d-9f40-5a6b7c8d9e0f",
  "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13"
}
```

**Turn conversations into tickets**

Node.js:

```javascript
import express from 'express';
import { zap, verifyZapSignature } from './zap.mjs';

const app = express();
app.post('/hooks/support', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifyZapSignature(req.body, req.get('Zap-Signature'))) return res.sendStatus(400);
  const eventId = req.get('Zap-Event-Id');
  if (await db.webhookEvents.seen(eventId)) return res.sendStatus(200);
  const { type, data } = JSON.parse(req.body);

  if (type === 'thread.created') {
    const ticket = await tickets.create({
      threadId: data.thread_id, subject: data.subject, customer: data.from,
      body: data.reply_text, lastEmailId: data.email_id,
    });
    await zap('PATCH', `/threads/${data.thread_id}`, { metadata: { ticket: ticket.id } });
    await zap('POST', `/emails/receiving/${data.email_id}/reply`, {
      from: 'Acme Support <support@acme.com>',
      text: `Thanks for writing. Your ticket is ${ticket.id}; a person will answer within one business day.`,
      auto_reply: true,
    }, { 'Idempotency-Key': `ack-${data.email_id}` });
  } else if (type === 'thread.replied') {
    const ticket = await tickets.findByThread(data.thread_id);
    await tickets.addMessage(ticket.id, { from: data.from, body: data.reply_text, emailId: data.email_id });
  }
  await db.webhookEvents.markSeen(eventId);
  res.sendStatus(200);
});

// An agent answers from your helpdesk UI.
export function answerTicket(ticket, agent, text) {
  return zap('POST', `/emails/receiving/${ticket.lastEmailId}/reply`, {
    from: `${agent.name} at Acme <support@acme.com>`,
    text,
  }, { 'Idempotency-Key': `ticket-${ticket.id}-msg-${ticket.messageCount}` });
}
```

Python:

```python
import json
from flask import Flask, request
from zap import zap, verify_zap_signature

app = Flask(__name__)

@app.post("/hooks/support")
def support_events():
    if not verify_zap_signature(request.get_data(), request.headers.get("Zap-Signature", "")):
        return "", 400
    event_id = request.headers["Zap-Event-Id"]
    if db.webhook_events.seen(event_id):
        return "", 200
    event = json.loads(request.get_data())
    data = event["data"]
    if event["type"] == "thread.created":
        ticket = tickets.create(thread_id=data["thread_id"], subject=data["subject"],
                                customer=data["from"], body=data["reply_text"],
                                last_email_id=data["email_id"])
        zap("PATCH", f"/threads/{data['thread_id']}", {"metadata": {"ticket": ticket.id}})
        zap("POST", f"/emails/receiving/{data['email_id']}/reply", {
            "from": "Acme Support <support@acme.com>",
            "text": f"Thanks for writing. Your ticket is {ticket.id}; a person will answer within one business day.",
            "auto_reply": True,
        }, headers={"Idempotency-Key": f"ack-{data['email_id']}"})
    elif event["type"] == "thread.replied":
        ticket = tickets.find_by_thread(data["thread_id"])
        tickets.add_message(ticket.id, sender=data["from"], body=data["reply_text"], email_id=data["email_id"])
    db.webhook_events.mark_seen(event_id)
    return "", 200

def answer_ticket(ticket, agent, text):
    return zap("POST", f"/emails/receiving/{ticket.last_email_id}/reply",
               {"from": f"{agent.name} at Acme <support@acme.com>", "text": text},
               headers={"Idempotency-Key": f"ticket-{ticket.id}-msg-{ticket.message_count}"})
```

Go:

```go
type threadEvent struct {
	Type string
	Data struct {
		ThreadID  string `json:"thread_id"`
		EmailID   string `json:"email_id"`
		From      string
		Subject   string
		ReplyText string `json:"reply_text"`
	}
}

func SupportHook(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	if !zap.VerifySignature(body, r.Header.Get("Zap-Signature"), os.Getenv("ZAP_WEBHOOK_SECRET")) {
		http.Error(w, "bad signature", http.StatusBadRequest)
		return
	}
	ctx, eventID := r.Context(), r.Header.Get("Zap-Event-Id")
	if db.EventSeen(ctx, eventID) {
		return // 200
	}
	var ev threadEvent
	if err := json.Unmarshal(body, &ev); err != nil {
		http.Error(w, "bad body", http.StatusBadRequest)
		return
	}
	d := ev.Data
	var err error
	switch ev.Type {
	case "thread.created":
		t, err2 := tickets.Create(ctx, d.ThreadID, d.Subject, d.From, d.ReplyText, d.EmailID)
		if err = err2; err == nil {
			err = zap.Do(ctx, "PATCH", "/threads/"+d.ThreadID, map[string]any{"metadata": map[string]string{"ticket": t.ID}}, nil, nil)
		}
		if err == nil {
			err = zap.Do(ctx, "POST", "/emails/receiving/"+d.EmailID+"/reply", map[string]any{
				"from":       "Acme Support <support@acme.com>",
				"text":       "Thanks for writing. Your ticket is " + t.ID + "; a person will answer within one business day.",
				"auto_reply": true,
			}, map[string]string{"Idempotency-Key": "ack-" + d.EmailID}, nil)
		}
	case "thread.replied":
		err = tickets.AddMessage(ctx, d.ThreadID, d.From, d.ReplyText, d.EmailID)
	}
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError) // ZapSMTP retries
		return
	}
	db.MarkEventSeen(ctx, eventID)
}
```

> The webhook carries metadata and `reply_text`; fetch the full body, headers and attachments with [GET /emails/receiving/{id}](https://www.zapsmtp.xyz/docs/receiving/get-received/). Replies to automated mail are refused with `422 automated_message` unless you pass `allow_automated: true`, and one conversation takes at most 20 replies an hour (`429 thread_reply_limit`), so two auto-responders cannot loop. A reply’s `from` defaults to the receiving address, which must then be on a verified sending domain; the recipe sends from `support@acme.com` instead.

## 7. Magic-link sign-in and CI tests with simulator addresses

**What you build:** passwordless sign-in with a 10-minute single-use link, plus CI tests that send real requests and check delivery and bounces without emailing anyone.

1. Store a hashed token with a short expiry; send the link with tracking off and the token id as the idempotency key.
2. In CI, use a `zap_test_` key and simulator recipients: `delivered+<label>@simulator.zapsmtp.xyz` delivers, `bounced@simulator.zapsmtp.xyz` bounces, `complained@simulator.zapsmtp.xyz` complains.
3. Poll the email until it reaches the expected status, then read its content and check the link.

## Send the sign-in link

`POST /v1/emails`

Plain HTML and text, no template needed. Open and click tracking are off so the link reaches the user exactly as you generated it.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: magic-link-9c4f7a10-1d2e-4b3a-8c5d-6e7f8a9b0c1d' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <login@acme.com>",
  "to": [
    "delivered+ci@simulator.zapsmtp.xyz"
  ],
  "subject": "Your Acme sign-in link",
  "html": "<p><a href=\"https://acme.com/login/verify?id=9c4f7a10&token=Qm…\">Sign in to Acme</a></p><p>The link works once, for 10 minutes.</p>",
  "text": "Sign in to Acme: https://acme.com/login/verify?id=9c4f7a10&token=Qm…\n\nThe link works once, for 10 minutes.",
  "tracking": {
    "opens": false,
    "clicks": false
  },
  "tags": [
    {
      "name": "category",
      "value": "magic-link"
    }
  ]
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

**Send a magic link**

Node.js:

```javascript
import crypto from 'node:crypto';
import { zap } from './zap.mjs';

const TTL_MINUTES = 10;

export async function sendMagicLink(email) {
  const id = crypto.randomUUID();
  const token = crypto.randomBytes(32).toString('base64url');
  await db.magicLinks.insert({
    id, email,
    tokenHash: crypto.createHash('sha256').update(token).digest('hex'),
    expiresAt: new Date(Date.now() + TTL_MINUTES * 60_000), // single use: delete on success
  });
  const url = `https://acme.com/login/verify?id=${id}&token=${token}`;
  return zap('POST', '/emails', {
    from: 'Acme <login@acme.com>',
    to: [email],
    subject: 'Your Acme sign-in link',
    html: `<p><a href="${url}">Sign in to Acme</a></p><p>The link works once, for ${TTL_MINUTES} minutes.</p>`,
    text: `Sign in to Acme: ${url}\n\nThe link works once, for ${TTL_MINUTES} minutes.`,
    tracking: { opens: false, clicks: false },
    tags: [{ name: 'category', value: 'magic-link' }],
  }, { 'Idempotency-Key': `magic-link-${id}` });
}
```

Python:

```python
import hashlib, secrets, uuid
from datetime import datetime, timedelta, timezone
from zap import zap

TTL_MINUTES = 10

def send_magic_link(email: str):
    link_id, token = str(uuid.uuid4()), secrets.token_urlsafe(32)
    db.magic_links.insert(id=link_id, email=email,
                          token_hash=hashlib.sha256(token.encode()).hexdigest(),
                          expires_at=datetime.now(timezone.utc) + timedelta(minutes=TTL_MINUTES))
    url = f"https://acme.com/login/verify?id={link_id}&token={token}"
    return zap("POST", "/emails", {
        "from": "Acme <login@acme.com>",
        "to": [email],
        "subject": "Your Acme sign-in link",
        "html": f'<p><a href="{url}">Sign in to Acme</a></p><p>The link works once, for {TTL_MINUTES} minutes.</p>',
        "text": f"Sign in to Acme: {url}\n\nThe link works once, for {TTL_MINUTES} minutes.",
        "tracking": {"opens": False, "clicks": False},
        "tags": [{"name": "category", "value": "magic-link"}],
    }, headers={"Idempotency-Key": f"magic-link-{link_id}"})
```

Go:

```go
const ttl = 10 * time.Minute

func SendMagicLink(ctx context.Context, email string) (string, error) {
	id := uuid.NewString()
	raw := make([]byte, 32)
	rand.Read(raw)
	token := base64.RawURLEncoding.EncodeToString(raw)
	sum := sha256.Sum256([]byte(token))
	if err := db.SaveMagicLink(ctx, id, email, hex.EncodeToString(sum[:]), time.Now().Add(ttl)); err != nil {
		return "", err
	}
	url := "https://acme.com/login/verify?id=" + id + "&token=" + token
	var res struct{ ID string }
	err := zap.Do(ctx, "POST", "/emails", map[string]any{
		"from":     "Acme <login@acme.com>",
		"to":       []string{email},
		"subject":  "Your Acme sign-in link",
		"html":     `<p><a href="` + url + `">Sign in to Acme</a></p><p>The link works once, for 10 minutes.</p>`,
		"text":     "Sign in to Acme: " + url + "\n\nThe link works once, for 10 minutes.",
		"tracking": map[string]bool{"opens": false, "clicks": false},
		"tags":     []map[string]string{{"name": "category", "value": "magic-link"}},
	}, map[string]string{"Idempotency-Key": "magic-link-" + id}, &res)
	return res.ID, err
}
```

## CI: wait for the outcome

`GET /v1/emails/{id}`

Poll until `recipients[0].status` is the status the simulator address produces (`delivered`, `bounced`…). Test keys may read, so CI never needs a live key.

Requires a full-access key.

Only data inside the plan's log retention is visible. metadata may be null.

### Path parameters

- `id` (string, required): Email id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found (events can take a few seconds to appear)

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "from": "Acme <hello@acme.com>",
  "subject": "Your receipt",
  "created_at": "2026-10-21T15:04:10.902Z",
  "recipients": [
    {
      "email": "jane@example.org",
      "status": "delivered",
      "updated_at": "2026-10-21T15:04:12.381Z",
      "response": "250 2.0.0 OK 1761059052 x7si123"
    }
  ],
  "events": [
    {
      "type": "Reception",
      "status": "queued",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:10.902Z",
      "attempts": 0
    },
    {
      "type": "Delivery",
      "status": "delivered",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:12.381Z",
      "response_code": 250,
      "response": "250 2.0.0 OK 1761059052 x7si123",
      "attempts": 1,
      "mx": "gmail-smtp-in.l.google.com.",
      "peer_addr": "142.250.153.27",
      "tls": "TLSv1.3 TLS_AES_256_GCM_SHA384",
      "egress_source": "ip-1"
    }
  ],
  "stream": "transactional",
  "test": false,
  "metadata": {
    "order_id": "A-1042"
  }
}
```

## CI: read what was sent

`GET /v1/emails/{id}/content`

Returns the HTML and text you sent, each truncated to 256 KiB in the archive; extract the link and drive your sign-in flow with it.

Requires a full-access key.

`source` is `api` or `smtp`; `tags` is the URL-encoded tag string. Content is kept for your plan’s log retention.

### Path parameters

- `id` (string, required): Email id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): content not available (past your plan's log retention)

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/content' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "source": "api",
  "from": "Acme <hello@acme.com>",
  "to": [
    "jane@example.org"
  ],
  "cc": [],
  "bcc": [],
  "subject": "Your receipt",
  "html": "<p>Thanks for your order!</p>",
  "text": "Thanks for your order!",
  "raw": "",
  "tags": "category=receipt",
  "size": 2481
}
```

**Test it in CI**

Node.js:

```javascript
// magic-link.test.mjs: node --test. ZAP_API_KEY is a zap_test_ key with full access.
import test from 'node:test';
import assert from 'node:assert/strict';
import { zap } from './zap.mjs';
import { sendMagicLink } from './magic-link.mjs';

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function waitForStatus(id, status) {
  for (let i = 0; i < 30; i++) {
    const email = await zap('GET', `/emails/${id}`);
    if (email.recipients[0]?.status === status) return email;
    await sleep(1000);
  }
  throw new Error(`email ${id} never reached ${status}`);
}

test('the sign-in link arrives and is well formed', async () => {
  assert.match(process.env.ZAP_API_KEY, /^zap_test_/); // never run CI against a live key
  const run = process.env.GITHUB_RUN_ID ?? Date.now();
  const { id } = await sendMagicLink(`delivered+ci-${run}@simulator.zapsmtp.xyz`);
  await waitForStatus(id, 'delivered');
  const { html } = await zap('GET', `/emails/${id}/content`);
  const link = html.match(/href="([^"]+)"/)[1];
  assert.match(link, /^https:\/\/acme\.com\/login\/verify\?id=/);
});

test('a bounce is reported', async () => {
  const { id } = await sendMagicLink('bounced@simulator.zapsmtp.xyz');
  const email = await waitForStatus(id, 'bounced');
  assert.equal(email.recipients[0].status, 'bounced');
});
```

Python:

```python
# test_magic_link.py: pytest. ZAP_API_KEY is a zap_test_ key with full access.
import os, re, time
from zap import zap
from magic_link import send_magic_link

def wait_for_status(email_id, status):
    for _ in range(30):
        email = zap("GET", f"/emails/{email_id}")
        if email["recipients"] and email["recipients"][0]["status"] == status:
            return email
        time.sleep(1)
    raise AssertionError(f"email {email_id} never reached {status}")

def test_link_arrives():
    assert os.environ["ZAP_API_KEY"].startswith("zap_test_")
    run = os.environ.get("GITHUB_RUN_ID", str(int(time.time())))
    sent = send_magic_link(f"delivered+ci-{run}@simulator.zapsmtp.xyz")
    wait_for_status(sent["id"], "delivered")
    html = zap("GET", f"/emails/{sent['id']}/content")["html"]
    link = re.search(r'href="([^"]+)"', html).group(1)
    assert link.startswith("https://acme.com/login/verify?id=")

def test_bounce_is_reported():
    sent = send_magic_link("bounced@simulator.zapsmtp.xyz")
    wait_for_status(sent["id"], "bounced")
```

Go:

```go
// magiclink_test.go: go test. ZAP_API_KEY is a zap_test_ key with full access.
func waitForStatus(t *testing.T, id, status string) {
	t.Helper()
	for i := 0; i < 30; i++ {
		var e struct{ Recipients []struct{ Status string } }
		if err := zap.Do(context.Background(), "GET", "/emails/"+id, nil, nil, &e); err != nil {
			t.Fatal(err)
		}
		if len(e.Recipients) > 0 && e.Recipients[0].Status == status {
			return
		}
		time.Sleep(time.Second)
	}
	t.Fatalf("email %s never reached %s", id, status)
}

func TestMagicLink(t *testing.T) {
	if !strings.HasPrefix(os.Getenv("ZAP_API_KEY"), "zap_test_") {
		t.Fatal("use a zap_test_ key in CI")
	}
	id, err := SendMagicLink(context.Background(), fmt.Sprintf("delivered+ci-%d@simulator.zapsmtp.xyz", time.Now().Unix()))
	if err != nil {
		t.Fatal(err)
	}
	waitForStatus(t, id, "delivered")
	var c struct{ HTML string }
	if err := zap.Do(context.Background(), "GET", "/emails/"+id+"/content", nil, nil, &c); err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(c.HTML, `href="https://acme.com/login/verify?id=`) {
		t.Fatalf("no sign-in link in %q", c.HTML)
	}
}

func TestMagicLinkBounce(t *testing.T) {
	id, err := SendMagicLink(context.Background(), "bounced@simulator.zapsmtp.xyz")
	if err != nil {
		t.Fatal(err)
	}
	waitForStatus(t, id, "bounced")
}
```

> Expiry is enforced by your application, not by the email: check the stored expiry and delete the token on first use. Some corporate mail filters open links to scan them, so let the link open a page whose button completes the sign-in. Test-key email carries `test: true` in webhooks and does not count against your monthly quota. All scenarios: [Testing & simulator](https://www.zapsmtp.xyz/docs/testing/).

## 8. Sending for many client domains (agencies)

**What you build:** one integration that sends for many clients, each from its own domain, without one client’s key ever sending as another.

**Two ways to separate clients**

- **One account per client**: Full separation: own domains, keys, webhooks, suppressions, logs, reputation and plan. Create client accounts from the account menu in the dashboard (there is no API for creating accounts), invite the client with a role, and use that account’s own key in the client’s integration. See [Teams & client accounts](https://www.zapsmtp.xyz/docs/teams/).
- **One account, a key per domain**: Your account holds every client domain; each client gets a `sending_access` key restricted with `domain_id`. Domains, quota, suppression list, webhooks and logs are shared, and only your full-access key can read logs and stats.

Pick separate accounts when clients need their own dashboard, billing or reputation; pick restricted keys when you run everything yourself. The code below automates the second option.

## Add the client’s domain

`POST /v1/domains`

The response lists the DNS records (DKIM required, SPF and DMARC recommended) to hand to the client. Then call [verify](https://www.zapsmtp.xyz/docs/domains/verify-domain/) until `status` is `verified`. Requires a full-access live key.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string, required): Domain name (lowercased, trailing dot removed). Limits: valid hostname <=253 chars, else 422 invalid_parameter "invalid domain name"

### Errors

- `plan_limit_reached` (HTTP 403): the <Plan> plan includes <n> domains; upgrade your plan to add more
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): domain already added
- `invalid_parameter` (HTTP 422): invalid domain name

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "mail.client-shop.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "pending",
  "dkim_selector": "zap",
  "dkim_verified": false,
  "spf_verified": false,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": null,
  "verified_at": null,
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "pending"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "pending"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ]
}
```

## Issue a key that can only send from that domain

`POST /v1/api-keys`

`domain_id` works with `sending_access` only. The key cannot read logs, change settings or send from any other domain (`403 restricted_api_key`). The token is shown once.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string, required): Limits: 1-100 characters (not trimmed) → 422 invalid_parameter "name is required (max 100 chars)"
- `permission` (string): One of `full_access`, `sending_access`. Default `full_access`.
- `domain_id` (string): Restrict sending to one of the account's domains. Only with sending_access. Limits: 422 "domain_id can only be used with sending_access" / "unknown domain_id"
- `mode` (string): test creates a zap_test_ key (see [API keys](https://www.zapsmtp.xyz/docs/conventions/#keys)). One of `live`, `test`. Default `live`.
- `stream` (string): Restrict the key to one message stream. One of `transactional`, `broadcast`.
- `expires_at` (string (RFC 3339)): Limits: must be in the future → 422 "expires_at must be in the future"
- `expires_in_days` (integer): Alternative to expires_at; when > 0 it overrides expires_at.

### Errors

- `key_restricted` (HTTP 403): this API key expires, so the keys it manages must expire no later than it does | this API key is limited to the <stream> stream, and so are the keys it manages
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): name, permission, domain_id, mode, stream or expiry invalid

```bash
curl -X POST 'https://zapsmtp.xyz/v1/api-keys' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "client-shop",
  "permission": "sending_access",
  "mode": "live",
  "domain_id": "019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f05-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
  "token": "zap_8fK2mQ9xLr3TzV7bN1cW5yHjP0aS4dE6gU2iO9kX",
  "key": {
    "id": "019a1f05-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
    "name": "Production",
    "prefix": "zap_8fK2mQ",
    "permission": "sending_access",
    "mode": "live",
    "stream": null,
    "expires_at": null,
    "domain_id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
    "last_used_at": null,
    "created_at": "2026-10-21T15:30:00Z"
  }
}
```

**Onboard a client domain**

Node.js:

```javascript
import { zap } from './zap.mjs'; // ZAP_API_KEY: your full-access agency key

export async function onboardClient(client) {
  const domain = await zap('POST', '/domains', { name: client.sendingDomain });
  await sendDnsInstructions(client, domain.records); // [{ type, name, value, required }]
  await db.clients.update(client.id, { zapDomainId: domain.id });
}

// From a job, until it succeeds (DNS can take a while).
export async function activateClient(client) {
  const domain = await zap('POST', `/domains/${client.zapDomainId}/verify`);
  if (domain.status !== 'verified') return false;
  const { token, key } = await zap('POST', '/api-keys', {
    name: `client-${client.slug}`,
    permission: 'sending_access',
    mode: 'live',
    domain_id: client.zapDomainId,
  });
  await secrets.put(`zapsmtp/${client.slug}`, token); // your secret manager: shown once
  await db.clients.update(client.id, { zapKeyId: key.id });
  return true;
}

// Offboarding: the key stops working on the next request.
export const offboardClient = (client) => zap('DELETE', `/api-keys/${client.zapKeyId}`);
```

Python:

```python
from zap import zap  # ZAP_API_KEY: your full-access agency key

def onboard_client(client):
    domain = zap("POST", "/domains", {"name": client.sending_domain})
    send_dns_instructions(client, domain["records"])
    db.clients.update(client.id, zap_domain_id=domain["id"])

def activate_client(client) -> bool:
    domain = zap("POST", f"/domains/{client.zap_domain_id}/verify")
    if domain["status"] != "verified":
        return False
    created = zap("POST", "/api-keys", {
        "name": f"client-{client.slug}",
        "permission": "sending_access",
        "mode": "live",
        "domain_id": client.zap_domain_id,
    })
    secrets.put(f"zapsmtp/{client.slug}", created["token"])  # shown once
    db.clients.update(client.id, zap_key_id=created["key"]["id"])
    return True

def offboard_client(client):
    zap("DELETE", f"/api-keys/{client.zap_key_id}")
```

PHP:

```php
<?php
require_once 'zap.php'; // ZAP_API_KEY: your full-access agency key

function onboard_client(array $client): void
{
    $domain = zap('POST', '/domains', ['name' => $client['sending_domain']]);
    send_dns_instructions($client, $domain['records']);
    db_update_client($client['id'], ['zap_domain_id' => $domain['id']]);
}

function activate_client(array $client): bool
{
    $domain = zap('POST', "/domains/{$client['zap_domain_id']}/verify");
    if ($domain['status'] !== 'verified') return false;
    $created = zap('POST', '/api-keys', [
        'name' => "client-{$client['slug']}",
        'permission' => 'sending_access',
        'mode' => 'live',
        'domain_id' => $client['zap_domain_id'],
    ]);
    secrets_put("zapsmtp/{$client['slug']}", $created['token']); // shown once
    db_update_client($client['id'], ['zap_key_id' => $created['key']['id']]);
    return true;
}

function offboard_client(array $client): void
{
    zap('DELETE', "/api-keys/{$client['zap_key_id']}");
}
```

> Restricted keys can also be limited to one stream (`stream`) and given an expiry (`expires_at` or `expires_in_days`). Change a key’s restrictions later with [PATCH /api-keys/{id}](https://www.zapsmtp.xyz/docs/keys/update-api-key/); the token stays the same.

## 9. Retries with exponential backoff and Retry-After

**What you build:** a wrapper that retries exactly the failures worth retrying, waits at least as long as the server asks, and never sends an email twice.

**What to retry**

- **Retry**: Network errors and timeouts; `429 rate_limit_exceeded` (`Retry-After: 1`); `429 overloaded`, the server at capacity (`Retry-After: 1` or `5`); `503 service_unavailable` (`Retry-After: 2` while a backing store fails over, `5` otherwise: the MTA unavailable, the suppression list loading, too many large bodies in flight); other 5xx; `409 idempotency_request_in_progress` (the first attempt is still running).
- **Do not retry**: `429 monthly_quota_exceeded` and `daily_quota_exceeded` (wait for the reset or upgrade); `421 misdirected_cell`: send to the URL the message names instead; every other 4xx: fix the request.
- **Never retry a 200**: A response with `unconfirmed: true` counts as sent; its events tell the outcome. `failed_recipients` lists addresses that were refused and not charged.

**Retry with backoff**

Node.js:

```javascript
import crypto from 'node:crypto';
import { zap } from './zap.mjs';

// Worth retrying: network errors, 5xx, the per-second rate limit and a duplicate in flight.
// Not worth it: monthly_quota_exceeded, daily_quota_exceeded and every other 4xx.
const RETRY_CODES = new Set(['rate_limit_exceeded', 'idempotency_request_in_progress']);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function withRetry(call, { attempts = 6, baseMs = 500, maxMs = 30_000 } = {}) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await call();
    } catch (err) {
      const retry = err.status === undefined || err.status >= 500 || RETRY_CODES.has(err.code);
      if (!retry || attempt >= attempts) throw err;
      const backoff = Math.random() * Math.min(maxMs, baseMs * 2 ** attempt); // full jitter
      await sleep(Math.max(backoff, (err.retryAfter || 0) * 1000));          // never sooner than Retry-After
    }
  }
}

// The key is created once, outside the loop: every attempt is the same request.
export function sendEmail(email, idempotencyKey = crypto.randomUUID()) {
  return withRetry(() => zap('POST', '/emails', email, { 'Idempotency-Key': idempotencyKey }));
}
```

Python:

```python
import random, time, uuid
import requests
from zap import zap, ZapError

RETRY_CODES = {"rate_limit_exceeded", "idempotency_request_in_progress"}

def with_retry(call, attempts=6, base=0.5, cap=30.0):
    for attempt in range(1, attempts + 1):
        try:
            return call()
        except requests.RequestException:  # network error, timeout
            if attempt == attempts:
                raise
            wait = 0.0
        except ZapError as e:
            if not (e.status >= 500 or e.code in RETRY_CODES) or attempt == attempts:
                raise
            wait = e.retry_after
        time.sleep(max(wait, random.uniform(0, min(cap, base * 2 ** attempt))))

def send_email(email: dict, idempotency_key: str | None = None):
    key = idempotency_key or str(uuid.uuid4())
    return with_retry(lambda: zap("POST", "/emails", email, headers={"Idempotency-Key": key}))
```

Go:

```go
var retryCodes = map[string]bool{"rate_limit_exceeded": true, "idempotency_request_in_progress": true}

func WithRetry(ctx context.Context, attempts int, call func() error) error {
	for attempt := 1; ; attempt++ {
		err := call()
		var zerr *zap.Error
		isZap := errors.As(err, &zerr)
		retry := err != nil && (!isZap || zerr.Status >= 500 || retryCodes[zerr.Code])
		if !retry || attempt >= attempts {
			return err
		}
		wait := time.Duration(rand.Int64N(int64(min(30*time.Second, 500*time.Millisecond<<attempt)))) // math/rand/v2
		if isZap && zerr.RetryAfter > wait {
			wait = zerr.RetryAfter
		}
		select {
		case <-ctx.Done():
			return ctx.Err()
		case <-time.After(wait):
		}
	}
}

func SendEmail(ctx context.Context, email map[string]any, out any) error {
	key := uuid.NewString() // one key for every attempt
	return WithRetry(ctx, 6, func() error {
		return zap.Do(ctx, "POST", "/emails", email, map[string]string{"Idempotency-Key": key}, out)
	})
}
```

PHP:

```php
<?php
require_once 'zap.php';

function zap_with_retry(callable $call, int $attempts = 6): mixed
{
    for ($attempt = 1; ; $attempt++) {
        try {
            return $call();
        } catch (ZapError $e) {
            $retry = $e->status === 0 || $e->status >= 500
                || in_array($e->zapCode, ['rate_limit_exceeded', 'idempotency_request_in_progress'], true);
            if (!$retry || $attempt >= $attempts) throw $e;
            $backoff = mt_rand(0, min(30000, 500 * 2 ** $attempt)) / 1000;
            usleep((int) (max($backoff, $e->retryAfter) * 1e6));
        }
    }
}

$key = bin2hex(random_bytes(16)); // one key for every attempt
$sent = zap_with_retry(fn () => zap('POST', '/emails', [
    'from' => 'Acme <hello@acme.com>',
    'to' => ['delivered@simulator.zapsmtp.xyz'],
    'subject' => 'Hello',
    'text' => 'Hi there!',
], ['Idempotency-Key' => $key]));
```

> Create the `Idempotency-Key` once per logical email and reuse it on every attempt: if a timed-out attempt actually succeeded, the retry returns its response with `Idempotent-Replayed: true`. In a batch, per-email failures such as `rate_limit_exceeded` come back in `errors[]` of a 200 response; resend only those emails with a new key, as in recipe 4.

## 10. Next.js, Express, Django and Laravel

**What you build:** a send endpoint and a webhook endpoint in your framework, with the key read from the environment on the server.

- Call ZapSMTP only from server code: Route Handlers or Server Actions in Next.js, never a client component.
- Webhook routes need the raw body for the signature, and no CSRF check (the signature replaces it).
- Answer webhooks with a 2xx quickly and dedupe on `Zap-Event-Id`.

**Framework integration**

Next.js:

```
// app/api/welcome/route.ts: a Route Handler runs on the server only.
// .env.local: ZAP_API_KEY=zap_...   Never prefix it with NEXT_PUBLIC_.
import { NextResponse } from 'next/server';

export const runtime = 'nodejs';

export async function POST(req: Request) {
  const { userId, email, firstName } = await req.json(); // authenticate the caller first
  const res = await fetch('https://zapsmtp.xyz/v1/emails', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ZAP_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `welcome-${userId}`,
    },
    body: JSON.stringify({
      from: 'Acme <hello@acme.com>',
      to: [email],
      template: { id: 'welcome', variables: { first_name: firstName } },
    }),
  });
  const data = await res.json();
  if (!res.ok) return NextResponse.json({ error: data.name }, { status: 502 });
  return NextResponse.json({ id: data.id });
}

// app/api/hooks/zapsmtp/route.ts: read the raw text before parsing.
import { verifyZapSignature } from '@/lib/zap'; // from Setup

export async function POST(req: Request) {
  const raw = await req.text();
  if (!verifyZapSignature(raw, req.headers.get('Zap-Signature'))) {
    return new Response('bad signature', { status: 400 });
  }
  const event = JSON.parse(raw); // dedupe on req.headers.get('Zap-Event-Id')
  return new Response(null, { status: 200 });
}
```

Express:

```
// server.mjs: ZAP_API_KEY and ZAP_WEBHOOK_SECRET come from the environment.
import express from 'express';
import { zap, verifyZapSignature } from './zap.mjs';

const app = express();

// webhooks before express.json(): they need the raw body
app.post('/hooks/zapsmtp', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyZapSignature(req.body, req.get('Zap-Signature'))) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

app.use(express.json());
app.post('/api/contact', async (req, res, next) => {
  try {
    const { name, email, message } = req.body; // validate these
    const { id } = await zap('POST', '/emails', {
      from: 'Acme Website <website@acme.com>',
      to: ['sales@acme.com'],
      reply_to: email,
      subject: `Contact form: ${name}`,
      text: message,
    });
    res.json({ id });
  } catch (err) {
    next(err);
  }
});

app.listen(3000);
```

Django:

```
# settings.py
ZAP_WEBHOOK_SECRET = os.environ["ZAP_WEBHOOK_SECRET"]  # zap.py reads ZAP_API_KEY itself

# views.py
import json
from django.conf import settings
from django.http import HttpResponse, JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from .zap import zap, verify_zap_signature, ZapError

@require_POST
def contact(request):
    form = json.loads(request.body)  # validate these
    try:
        sent = zap("POST", "/emails", {
            "from": "Acme Website <website@acme.com>",
            "to": ["sales@acme.com"],
            "reply_to": form["email"],
            "subject": f"Contact form: {form['name']}",
            "text": form["message"],
        })
    except ZapError as e:
        return JsonResponse({"error": e.code}, status=502)
    return JsonResponse({"id": sent["id"]})

@csrf_exempt  # ZapSMTP signs its requests instead
@require_POST
def zapsmtp_webhook(request):
    if not verify_zap_signature(request.body, request.headers.get("Zap-Signature", ""),
                                settings.ZAP_WEBHOOK_SECRET):
        return HttpResponse(status=400)
    event = json.loads(request.body)
    return HttpResponse(status=200)
```

Laravel:

```
<?php
// config/services.php
'zapsmtp' => [
    'key' => env('ZAP_API_KEY'),
    'webhook_secret' => env('ZAP_WEBHOOK_SECRET'),
],

// app/Http/Controllers/ContactController.php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

class ContactController extends Controller
{
    public function store(Request $request)
    {
        $data = $request->validate(['name' => 'required|string', 'email' => 'required|email', 'message' => 'required|string']);
        $res = Http::withToken(config('services.zapsmtp.key'))
            ->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
            ->post('https://zapsmtp.xyz/v1/emails', [
                'from' => 'Acme Website <website@acme.com>',
                'to' => ['sales@acme.com'],
                'reply_to' => $data['email'],
                'subject' => 'Contact form: ' . $data['name'],
                'text' => $data['message'],
            ]);
        abort_unless($res->successful(), 502, (string) $res->json('name'));
        return ['id' => $res->json('id')];
    }
}

// routes/api.php: API routes skip CSRF. verify_zap_signature() is in zap.php from Setup.
Route::post('/hooks/zapsmtp', function (Request $request) {
    abort_unless(verify_zap_signature($request->getContent(), (string) $request->header('Zap-Signature'),
        config('services.zapsmtp.webhook_secret')), 400);
    $event = json_decode($request->getContent(), true);
    return response('', 200);
});
```

---

# Migrating to ZapSMTP

Source: https://www.zapsmtp.xyz/docs/migration/

Move sending from Resend, SendGrid, Mailgun, Postmark or Amazon SES without a big-bang switch. Map your request fields and webhook events, convert templates, import suppressions, publish DNS next to your current records, then move traffic a percentage at a time with a rollback ready.

> The fastest path needs no code: if your application already sends over SMTP, change the host and credentials (SMTP relay). For the API, the tables below map every provider's fields and events one by one. Sends, batches and reads below run with a test key (`zap_test_…`) against simulator addresses. Setup and configuration requests (domains, templates, webhooks, suppressions, API keys) change the account and need a full-access live key: a test key gets `403 test_key_restricted`.

## Order of work

1. Add your domain and publish DKIM and SPF next to your existing records.
2. Create a test key (`zap_test_…`) and port the send call using the provider sections below.
3. Convert templates and connect webhooks.
4. Import suppressions before the first live email.
5. Shadow, then roll out by percentage, then cut over, keeping a rollback open.

## Zero-code path: SMTP relay

Applications, CMS plugins and frameworks that send through SMTP move by changing configuration only. SMTP and the API share one pipeline: the same email log, events, webhooks, suppressions and limits. Create an SMTP credential per application; its username starts with `smtp_`, it can only send, and you can revoke it on its own. Choose the stream per message with the `X-Zap-Stream: broadcast` header (default `transactional`). Full details are in [SMTP relay](https://www.zapsmtp.xyz/docs/smtp/).

**Point your mailer at ZapSMTP**

Generic:

```
SMTP_HOST=zapsmtp.xyz
SMTP_PORT=587            # STARTTLS; 2525 also works, 465 for implicit TLS
SMTP_USER=smtp_xxxxxxxxxxxx
SMTP_PASSWORD=…          # shown once when you create the credential
```

Laravel:

```
MAIL_MAILER=smtp
MAIL_HOST=zapsmtp.xyz
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=smtp_xxxxxxxxxxxx
MAIL_PASSWORD=…
```

Django:

```
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "zapsmtp.xyz"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = os.environ["ZAP_SMTP_USER"]
EMAIL_HOST_PASSWORD = os.environ["ZAP_SMTP_PASSWORD"]
```

SMTP is also the route for anything that sends prebuilt MIME, such as SES `SendRawEmail` or Mailgun’s MIME endpoint.

## From Resend

Request fields, the batch endpoint, idempotency keys and event names match, and error bodies also carry Resend’s flat `statusCode`, `name` and `message`, so Resend SDKs parse ZapSMTP errors. In the Node SDK, set `RESEND_BASE_URL` and use a ZapSMTP key. Test the SDK features your code uses (scheduling, templates, attachments) with a test key before switching.

**Request fields: Resend → ZapSMTP**

- **`from, to, cc, bcc, subject, html, text`**: Same names and shapes. Up to 50 recipients across `to`, `cc` and `bcc`.
- **`reply_to (SDK: replyTo)`**: `reply_to`
- **`scheduled_at (SDK: scheduledAt)`**: `scheduled_at`: RFC 3339 or `in 30 minutes`, up to 7 days ahead.
- **`tags [{name, value}]`**: `tags`, same shape. Names and values match `[A-Za-z0-9_-]`.
- **`headers, attachments`**: Same. Attachments take `filename` with `content` (base64) or `path` (HTTPS URL). The whole JSON request is capped at 40 MB, base64 included (about a third larger than the files), and a batch shares that one limit; larger requests get `413 payload_too_large`.
- **`Idempotency-Key header`**: Same header, kept 24 hours per API key.
- **`POST /emails/batch`**: Same endpoint, up to 100 emails.
- **`Authorization: Bearer re_…`**: `Authorization: Bearer zap_…`

**Webhook events: Resend → ZapSMTP**

- **`email.sent, email.delivered, email.delivery_delayed`**: Same names.
- **`email.bounced, email.complained, email.failed`**: Same names. Bounces carry `bounce.type` and `bounce.subType`.
- **`email.opened, email.clicked`**: Same names.
- **`email.received`**: Same name. Metadata only unless the endpoint has `include_content`.
- **`(no equivalent)`**: `email.suppressed`: the send was skipped because the address is on your suppression list.

**Node.js: Resend → ZapSMTP**

Before (Resend):

```
import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

await resend.emails.send({
  from: 'Acme <hello@acme.com>',
  to: ['jane@example.com'],
  subject: 'Your receipt',
  html: '<p>Thanks for your order.</p>',
  replyTo: 'support@acme.com',
  tags: [{ name: 'category', value: 'receipt' }],
});
```

After: environment:

```
# Server environment: only these two values change
RESEND_BASE_URL=https://zapsmtp.xyz/v1
RESEND_API_KEY=zap_your_api_key
```

After: application code:

```
// Unchanged: the SDK reads RESEND_BASE_URL and sends to ZapSMTP
import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

await resend.emails.send({
  from: 'Acme <hello@acme.com>',
  to: ['jane@example.com'],
  subject: 'Your receipt',
  html: '<p>Thanks for your order.</p>',
  replyTo: 'support@acme.com',
  tags: [{ name: 'category', value: 'receipt' }],
});
```

After (fetch):

```
const res = await fetch('https://zapsmtp.xyz/v1/emails', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.ZAP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'Acme <hello@acme.com>',
    to: ['jane@example.com'],
    subject: 'Your receipt',
    html: '<p>Thanks for your order.</p>',
    reply_to: 'support@acme.com',
    tags: [{ name: 'category', value: 'receipt' }],
  }),
});
const { id } = await res.json();
```

**Python: Resend → ZapSMTP**

Before (Resend):

```
import os, resend

resend.api_key = os.environ["RESEND_API_KEY"]
resend.Emails.send({
    "from": "Acme <hello@acme.com>",
    "to": ["jane@example.com"],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>",
    "reply_to": "support@acme.com",
})
```

After (ZapSMTP):

```
import os, requests

r = requests.post(
    "https://zapsmtp.xyz/v1/emails",
    headers={"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"},
    json={
        "from": "Acme <hello@acme.com>",
        "to": ["jane@example.com"],
        "subject": "Your receipt",
        "html": "<p>Thanks for your order.</p>",
        "reply_to": "support@acme.com",
    },
    timeout=30,
)
r.raise_for_status()
email_id = r.json()["id"]
```

**Webhooks.** Resend signs with `svix-id`, `svix-timestamp` and `svix-signature` headers (base64 signatures, base64-decoded secret). ZapSMTP sends `Zap-Signature: t=…,v1=…`: a hex HMAC-SHA256 over `<t>.<raw body>`, keyed with the whole `whsec_…` string, not decoded. Deduplicate on `Zap-Event-Id`. Replace the verification step; the payload handling can stay.

## The same request, sent to ZapSMTP

`POST /v1/emails`

A typical Resend-style send. Field names are unchanged; unknown fields are rejected with `400 validation_error`, so remove anything ZapSMTP does not document.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: order-1042-receipt' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Your receipt",
  "html": "<p>Thanks for your order.</p>",
  "reply_to": "support@acme.com",
  "tags": [
    {
      "name": "category",
      "value": "receipt"
    }
  ]
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## From SendGrid

SendGrid’s v3 `mail/send` nests recipients in `personalizations`. A single personalization maps to one ZapSMTP email; several personalizations that should each be a separate message map to `POST /emails/batch`. Note that all addresses in one ZapSMTP `to` see each other, as in any normal email.

**Request fields: SendGrid → ZapSMTP**

- **`from {email, name}`**: `from`: `"Acme <hello@acme.com>"`
- **`personalizations[].to / cc / bcc`**: `to`, `cc`, `bcc`. Each personalization that should be a separate email becomes one item in `POST /emails/batch`.
- **`subject`**: `subject`
- **`content [{type: text/plain \| text/html, value}]`**: `text` and `html`
- **`reply_to {email, name}`**: `reply_to`
- **`attachments [{content, filename, type, content_id}]`**: `attachments [{content, filename, content_type, content_id}]`
- **`categories []`**: `tags [{name, value}]`, e.g. `{name: "category", value: "receipt"}`
- **`custom_args {}`**: `metadata`: at most 10 string pairs, returned on the delivery events of that email.
- **`send_at (Unix time)`**: `scheduled_at` (RFC 3339), up to 7 days ahead.
- **`template_id + dynamic_template_data`**: `template: {id, variables}`; see Templates.
- **`tracking_settings`**: `tracking: {opens, clicks}`

**Event Webhook: SendGrid → ZapSMTP**

- **`processed`**: `email.sent`
- **`delivered`**: `email.delivered`
- **`deferred`**: `email.delivery_delayed`
- **`bounce`**: `email.bounced`
- **`dropped`**: `email.suppressed` when the address is suppressed, otherwise `email.failed`
- **`spamreport`**: `email.complained`
- **`open, click`**: `email.opened`, `email.clicked`
- **`unsubscribe`**: No event: the address is added to suppressions with reason `unsubscribe`.

**SendGrid → ZapSMTP**

Before (Node.js, SendGrid):

```
import sgMail from '@sendgrid/mail';

sgMail.setApiKey(process.env.SENDGRID_API_KEY);
await sgMail.send({
  to: 'jane@example.com',
  from: { email: 'hello@acme.com', name: 'Acme' },
  subject: 'Your receipt',
  html: '<p>Thanks for your order.</p>',
  categories: ['receipt'],
  customArgs: { order_id: 'A-1042' },
});
```

After (Node.js):

```
await fetch('https://zapsmtp.xyz/v1/emails', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ZAP_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: 'Acme <hello@acme.com>',
    to: 'jane@example.com',
    subject: 'Your receipt',
    html: '<p>Thanks for your order.</p>',
    tags: [{ name: 'category', value: 'receipt' }],
    metadata: { order_id: 'A-1042' },
  }),
});
```

Before (Python, SendGrid):

```
import os
from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail

message = Mail(
    from_email=("hello@acme.com", "Acme"),
    to_emails="jane@example.com",
    subject="Your receipt",
    html_content="<p>Thanks for your order.</p>",
)
SendGridAPIClient(os.environ["SENDGRID_API_KEY"]).send(message)
```

After (Python):

```
import os, requests

requests.post(
    "https://zapsmtp.xyz/v1/emails",
    headers={"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"},
    json={
        "from": "Acme <hello@acme.com>",
        "to": "jane@example.com",
        "subject": "Your receipt",
        "html": "<p>Thanks for your order.</p>",
        "tags": [{"name": "category", "value": "receipt"}],
        "metadata": {"order_id": "A-1042"},
    },
    timeout=30,
).raise_for_status()
```

**Webhooks.** SendGrid posts arrays of events and signs them with an ECDSA key (the `X-Twilio-Email-Event-Webhook-Signature` header). ZapSMTP posts one event per request with an HMAC-SHA256 `Zap-Signature`, so drop the array loop and the public-key check. `custom_args` come back as `data.metadata`.

**Templates.** Dynamic templates use Handlebars; convert conditionals and loops to Mustache sections (table below). Suppression groups have no direct equivalent: an unsubscribe applies to the whole account’s `broadcast` mail (transactional mail still goes out), and broadcast mail carries a one-click `List-Unsubscribe` header automatically.

## Personalizations as a batch

`POST /v1/emails/batch`

Several SendGrid personalizations (or Mailgun recipient variables) become one batch: each item is its own email with its own recipient, subject and metadata. Up to 100 per call.

Requires a full-access or sending-access key. Test keys follow the same rules as for sending.

Per-email error codes use the same classification as POST /emails (domain_not_verified, restricted_api_key, rate_limit_exceeded, monthly_quota_exceeded, etc. appear inside errors[] rather than as the HTTP status). Emails are sent concurrently (up to 16 at a time); each email may have its own scheduled_at.

Body: length 1-100 else 422 invalid_parameter "batch must contain 1 to 100 emails"

An item of `data` carries `reply_to` when reply tracking is on for that email.

### Headers

- `x-batch-validation` (string): strict (default) | permissive (case-insensitive). strict: if any email fails validation nothing is sent and 422 is returned. permissive: valid emails are sent; invalid ones are reported in errors.
- `Idempotency-Key` (string): optional, 1-256 bytes

### Body parameters

- `[ ]` (object[], required): 1–100 emails. Each item takes the fields of [Send an email](https://www.zapsmtp.xyz/docs/emails/send-email/).

### Errors

- `validation_error` (HTTP 400): invalid JSON or x-batch-validation not strict/permissive
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413)
- `invalid_parameter` (HTTP 422): batch size outside 1-100
- `validation_error` (HTTP 422): strict mode, any email invalid
- `service_unavailable` (HTTP 503): too many large bodies in flight

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered@simulator.zapsmtp.xyz"
    ],
    "subject": "Your order A-1042 shipped",
    "text": "Hi Ann, it is on its way.",
    "metadata": {
      "order_id": "A-1042"
    }
  },
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered+bob@simulator.zapsmtp.xyz"
    ],
    "subject": "Your order A-1043 shipped",
    "text": "Hi Bob, it is on its way.",
    "metadata": {
      "order_id": "A-1043"
    }
  }
]'
```

**Response `200 OK`**

```json
{
  "data": [
    {
      "index": 0,
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    },
    {
      "index": 2,
      "id": "019a1f2e-7c3c-7a10-8b21-4d5e6f7a8b9c",
      "suppressed": [
        "old@example.org"
      ]
    }
  ],
  "errors": [
    {
      "index": 1,
      "code": "missing_required_field",
      "message": "subject is required"
    }
  ]
}
```

## From Mailgun

Mailgun’s `/v3/<domain>/messages` takes form fields with `o:`, `h:` and `v:` prefixes and HTTP basic auth. ZapSMTP takes JSON with a bearer key, and the sending domain comes from `from` instead of the URL.

**Request fields: Mailgun → ZapSMTP**

- **`from, to, cc, bcc, subject, text, html`**: Same names, sent as JSON instead of form fields.
- **`h:Reply-To`**: `reply_to`
- **`h:X-My-Header`**: `headers: {"X-My-Header": "…"}`
- **`attachment / inline (files)`**: `attachments`; inline images set `content_id`.
- **`o:tag`**: `tags [{name, value}]`
- **`v:my-var (custom variables)`**: `metadata`
- **`o:deliverytime`**: `scheduled_at`
- **`o:tracking-opens, o:tracking-clicks`**: `tracking: {opens, clicks}`
- **`template + template variables`**: `template: {id, variables}`
- **`recipient-variables (batch sending)`**: One item per recipient in `POST /emails/batch`.

**Webhook events: Mailgun → ZapSMTP**

- **`accepted`**: `email.sent`
- **`delivered`**: `email.delivered`
- **`failed (temporary)`**: `email.delivery_delayed`
- **`failed (permanent)`**: `email.bounced`, or `email.suppressed` for a suppressed address
- **`complained`**: `email.complained`
- **`opened, clicked`**: `email.opened`, `email.clicked`
- **`unsubscribed`**: No event: suppression with reason `unsubscribe`.

**Mailgun → ZapSMTP**

Before (Node.js, Mailgun):

```
const form = new FormData();
form.append('from', 'Acme <hello@acme.com>');
form.append('to', 'jane@example.com');
form.append('subject', 'Your receipt');
form.append('html', '<p>Thanks for your order.</p>');
form.append('o:tag', 'receipt');
form.append('v:order_id', 'A-1042');

await fetch('https://api.mailgun.net/v3/mg.acme.com/messages', {
  method: 'POST',
  headers: { Authorization: 'Basic ' + btoa('api:' + process.env.MAILGUN_API_KEY) },
  body: form,
});
```

After (Node.js):

```
await fetch('https://zapsmtp.xyz/v1/emails', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ZAP_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: 'Acme <hello@acme.com>',
    to: 'jane@example.com',
    subject: 'Your receipt',
    html: '<p>Thanks for your order.</p>',
    tags: [{ name: 'tag', value: 'receipt' }],
    metadata: { order_id: 'A-1042' },
  }),
});
```

Before (Python, Mailgun):

```
import os, requests

requests.post(
    "https://api.mailgun.net/v3/mg.acme.com/messages",
    auth=("api", os.environ["MAILGUN_API_KEY"]),
    data={
        "from": "Acme <hello@acme.com>",
        "to": "jane@example.com",
        "subject": "Your receipt",
        "html": "<p>Thanks for your order.</p>",
        "o:tag": "receipt",
        "v:order_id": "A-1042",
    },
)
```

After (Python):

```
import os, requests

requests.post(
    "https://zapsmtp.xyz/v1/emails",
    headers={"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"},
    json={
        "from": "Acme <hello@acme.com>",
        "to": "jane@example.com",
        "subject": "Your receipt",
        "html": "<p>Thanks for your order.</p>",
        "tags": [{"name": "tag", "value": "receipt"}],
        "metadata": {"order_id": "A-1042"},
    },
    timeout=30,
).raise_for_status()
```

**Webhooks.** Mailgun puts a `signature` object (`timestamp`, `token`, `signature`) inside the JSON body and the event in `event-data`. ZapSMTP signs in the `Zap-Signature` header and puts the event fields in `data`. Permanent and temporary failures are separate event types in ZapSMTP instead of a `severity` field.

## Tags, metadata and scheduling

`POST /v1/emails`

`o:tag`, `v:` variables and `o:deliverytime` map to `tags`, `metadata` and `scheduled_at`. Metadata comes back on the delivery events of the email.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": "delivered@simulator.zapsmtp.xyz",
  "subject": "Your weekly summary",
  "html": "<p>Here is your week.</p>",
  "tags": [
    {
      "name": "tag",
      "value": "weekly-summary"
    }
  ],
  "metadata": {
    "user_id": "u_42"
  },
  "scheduled_at": "in 10 minutes",
  "tracking": {
    "opens": true,
    "clicks": true
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## From Postmark

Postmark uses PascalCase fields; ZapSMTP uses snake_case. Message streams map to `stream`: `transactional` or `broadcast`, each on its own IP pool. Postmark templates are Mustache-based, so most of them move with few or no changes.

**Request fields: Postmark → ZapSMTP**

- **`From, To, Cc, Bcc, Subject`**: `from`, `to`, `cc`, `bcc`, `subject`. Comma-separated lists become arrays.
- **`ReplyTo`**: `reply_to`
- **`HtmlBody, TextBody`**: `html`, `text`
- **`Headers [{Name, Value}]`**: `headers: {"Name": "Value"}`
- **`Attachments [{Name, Content, ContentType, ContentID}]`**: `attachments [{filename, content, content_type, content_id}]`
- **`Tag`**: `tags: [{name: "tag", value: "…"}]`. Values allow letters, digits, `_` and `-` only.
- **`Metadata`**: `metadata` (at most 10 keys)
- **`MessageStream`**: `stream`: `transactional` or `broadcast`
- **`TrackOpens, TrackLinks`**: `tracking: {opens, clicks}`
- **`TemplateAlias / TemplateId + TemplateModel`**: `template: {id, variables}`; `id` accepts a template id or alias.
- **`X-Postmark-Server-Token header`**: `Authorization: Bearer zap_…`

**Webhooks: Postmark RecordType → ZapSMTP**

- **`Delivery`**: `email.delivered`
- **`Bounce (hard)`**: `email.bounced` with `bounce.type: "Permanent"`
- **`Bounce (soft / transient)`**: `email.delivery_delayed` while retrying; `email.bounced` when retries run out
- **`SpamComplaint`**: `email.complained`
- **`Open, Click`**: `email.opened`, `email.clicked`
- **`SubscriptionChange`**: No event: suppression with reason `unsubscribe`.

**Postmark → ZapSMTP**

Before (Node.js, Postmark):

```
import { ServerClient } from 'postmark';

const client = new ServerClient(process.env.POSTMARK_SERVER_TOKEN);
await client.sendEmailWithTemplate({
  From: 'Acme <hello@acme.com>',
  To: 'jane@example.com',
  TemplateAlias: 'receipt',
  TemplateModel: { name: 'Jane', order_id: 'A-1042' },
  MessageStream: 'outbound',
});
```

After (Node.js):

```
await fetch('https://zapsmtp.xyz/v1/emails', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ZAP_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: 'Acme <hello@acme.com>',
    to: 'jane@example.com',
    template: { id: 'receipt', variables: { name: 'Jane', order_id: 'A-1042' } },
    stream: 'transactional',
  }),
});
```

Before (Python, Postmark):

```
import os, requests

requests.post(
    "https://api.postmarkapp.com/email/withTemplate",
    headers={"X-Postmark-Server-Token": os.environ["POSTMARK_SERVER_TOKEN"]},
    json={
        "From": "Acme <hello@acme.com>",
        "To": "jane@example.com",
        "TemplateAlias": "receipt",
        "TemplateModel": {"name": "Jane", "order_id": "A-1042"},
    },
)
```

After (Python):

```
import os, requests

requests.post(
    "https://zapsmtp.xyz/v1/emails",
    headers={"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"},
    json={
        "from": "Acme <hello@acme.com>",
        "to": "jane@example.com",
        "template": {"id": "receipt", "variables": {"name": "Jane", "order_id": "A-1042"}},
    },
    timeout=30,
).raise_for_status()
```

**Webhooks.** ZapSMTP signs every request; verify `Zap-Signature` as shown in [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/#signatures) instead of relying on URL credentials. Switch your handler from `RecordType` to `type`.

## Send with a stored template

`POST /v1/emails`

Postmark `TemplateAlias` + `TemplateModel`, SendGrid `template_id` + `dynamic_template_data` and SES `TemplateName` + `TemplateData` all become `template: {id, variables}`. The template must be published, and every variable it substitutes must be supplied; a missing section condition simply counts as false.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": "delivered@simulator.zapsmtp.xyz",
  "template": {
    "id": "welcome",
    "variables": {
      "first_name": "Ann"
    }
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## From Amazon SES

SES v2 `SendEmail` wraps content in `Content.Simple`, `Content.Raw` or `Content.Template` and is signed with AWS credentials. ZapSMTP uses a flat JSON body and an API key. Events arrive as webhooks directly, without a configuration set or an SNS topic in between.

**Request fields: SES v2 → ZapSMTP**

- **`FromEmailAddress`**: `from`
- **`Destination.ToAddresses / CcAddresses / BccAddresses`**: `to`, `cc`, `bcc`
- **`ReplyToAddresses`**: `reply_to`
- **`Content.Simple.Subject / Body.Html / Body.Text`**: `subject`, `html`, `text`
- **`Content.Raw (MIME)`**: No raw MIME field in the API: send prebuilt MIME through the [SMTP relay](https://www.zapsmtp.xyz/docs/smtp/).
- **`Content.Template (TemplateName, TemplateData)`**: `template: {id, variables}`; `variables` is an object, not a JSON string.
- **`EmailTags [{Name, Value}]`**: `tags [{name, value}]`
- **`ConfigurationSetName`**: Not needed: events go to the [webhooks](https://www.zapsmtp.xyz/docs/webhooks/) you subscribe; tracking is set per domain or with `tracking`.

**Event types: SES → ZapSMTP**

- **`Send`**: `email.sent`
- **`Delivery`**: `email.delivered`
- **`DeliveryDelay`**: `email.delivery_delayed`
- **`Bounce`**: `email.bounced`
- **`Complaint`**: `email.complained`
- **`Reject, Rendering Failure`**: `email.failed`; template errors are returned synchronously as `422 template_render_error`
- **`Open, Click`**: `email.opened`, `email.clicked`

**Amazon SES v2 → ZapSMTP**

Before (Node.js, SES v2):

```
import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2';

const ses = new SESv2Client({ region: 'us-east-1' });
await ses.send(new SendEmailCommand({
  FromEmailAddress: 'Acme <hello@acme.com>',
  Destination: { ToAddresses: ['jane@example.com'] },
  Content: {
    Simple: {
      Subject: { Data: 'Your receipt' },
      Body: { Html: { Data: '<p>Thanks for your order.</p>' } },
    },
  },
  EmailTags: [{ Name: 'category', Value: 'receipt' }],
}));
```

After (Node.js):

```
await fetch('https://zapsmtp.xyz/v1/emails', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.ZAP_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: 'Acme <hello@acme.com>',
    to: ['jane@example.com'],
    subject: 'Your receipt',
    html: '<p>Thanks for your order.</p>',
    tags: [{ name: 'category', value: 'receipt' }],
  }),
});
```

Before (Python, SES v2):

```
import boto3

ses = boto3.client("sesv2", region_name="us-east-1")
ses.send_email(
    FromEmailAddress="Acme <hello@acme.com>",
    Destination={"ToAddresses": ["jane@example.com"]},
    Content={"Simple": {
        "Subject": {"Data": "Your receipt"},
        "Body": {"Html": {"Data": "<p>Thanks for your order.</p>"}},
    }},
    EmailTags=[{"Name": "category", "Value": "receipt"}],
)
```

After (Python):

```
import os, requests

requests.post(
    "https://zapsmtp.xyz/v1/emails",
    headers={"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"},
    json={
        "from": "Acme <hello@acme.com>",
        "to": ["jane@example.com"],
        "subject": "Your receipt",
        "html": "<p>Thanks for your order.</p>",
        "tags": [{"name": "category", "value": "receipt"}],
    },
    timeout=30,
).raise_for_status()
```

**Webhooks.** Instead of confirming an SNS subscription and validating SNS message signatures, verify one HMAC header. Bounce details move from `bounce.bounceType` / `bounceSubType` to `data.bounce.type` (`Permanent`, `Transient`, `Undetermined`) and `data.bounce.subType`; see the [bounce classification](https://www.zapsmtp.xyz/docs/testing/#bounces).

**Suppressions.** Export the account-level suppression list (bounces and complaints) and import it as shown below.

## Templates

ZapSMTP templates are logic-less Mustache. Templates from Postmark (Mustache-based) usually carry over; Handlebars templates from SendGrid, Mailgun and SES need their conditionals, loops and helpers rewritten. Templates have a draft and a published version, and sends always use the published one: create with `"publish": true` or [publish](https://www.zapsmtp.xyz/docs/templates/publish-template/) after review. Handlebars tags are refused on save: `{{#each items}}`, `{{> footer}}` or `{{first name}}` return `422 template_render_error` *html: line L, column C: {{…}} is not a variable name*, with the position of the first one to rewrite. A required variable must be supplied on send: a missing one returns `422 template_variables_missing` instead of an empty string. A missing section condition (`{{#vip}}`) counts as false, variables inside a section that is skipped are not evaluated, and `zap:` placeholders are never required. Rendering works with a test key; creating and publishing templates needs a full-access live key.

**Handlebars-style → ZapSMTP**

- **`{{name}} / {{{html}}}`**: Same: escaped and raw.
- **`{{user.first_name}}`**: Same: dotted paths work.
- **`{{#if vip}}…{{/if}}`**: `{{#vip}}…{{/vip}}`: a section renders when the value is truthy.
- **`{{else}} / {{#unless x}}`**: An inverted section: `{{^x}}…{{/x}}`.
- **`{{#each items}}{{this.name}}{{/each}}`**: `{{#items}}{{name}}{{/items}}`; `{{.}}` is the current item of a list of strings.
- **`Helpers ({{formatDate …}}, {{#equals}} …)`**: None: templates are logic-less. Format values before you send them.
- **`%recipient.name% (Mailgun batch variables)`**: `{{name}}` with a separate batch item per recipient.
- **`Unsubscribe placeholders`**: `{{{zap:unsubscribe_url}}}` becomes the recipient’s signed one-click unsubscribe link.

**Convert a template**

Before (Handlebars-style):

```
<p>Hi {{customer.first_name}},</p>
{{#if vip}}<p>Your VIP discount is applied.</p>{{else}}<p>Join VIP for 10% off.</p>{{/if}}
<ul>
{{#each items}}<li>{{this.name}} × {{this.qty}}</li>{{/each}}
</ul>
```

After (ZapSMTP Mustache):

```
<p>Hi {{customer.first_name}},</p>
{{#vip}}<p>Your VIP discount is applied.</p>{{/vip}}{{^vip}}<p>Join VIP for 10% off.</p>{{/vip}}
<ul>
{{#items}}<li>{{name}} × {{qty}}</li>{{/items}}
</ul>
<p><a href="{{{zap:unsubscribe_url}}}">Unsubscribe</a></p>
```

## Check a converted template

`POST /v1/templates/render`

Render converted source with sample data before you save it. Syntax errors and the resulting subject, HTML and text come back without sending anything. Rendering works with a test key; saving templates needs a full-access live key.

Requires a full-access key.

### Body parameters

- `subject` (string)
- `html` (string)
- `text` (string)
- `variables` (object): Default `{}`.

### Errors

- `restricted_api_key` (HTTP 403)
- `template_render_error` (HTTP 422): <field>: <syntax error>

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/render' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "subject": "Order {{order_id}}",
  "html": "<p>Hi {{customer.first_name}},</p>{{#vip}}<p>VIP discount applied.</p>{{/vip}}{{^vip}}<p>Join VIP for 10% off.</p>{{/vip}}<ul>{{#items}}<li>{{name}} × {{qty}}</li>{{/items}}</ul>",
  "variables": {
    "order_id": "A-1042",
    "customer": {
      "first_name": "Ann"
    },
    "vip": false,
    "items": [
      {
        "name": "Mug",
        "qty": 2
      },
      {
        "name": "Tea",
        "qty": 1
      }
    ]
  }
}'
```

**Response `200 OK`**

```json
{
  "subject": "Hello Jane",
  "html": "<p>Welcome, Jane!</p>",
  "text": "",
  "missing_variables": [
    "plan"
  ],
  "variable_names": [
    "name",
    "plan"
  ],
  "design": null
}
```

## Webhooks during the transition

Run both providers’ endpoints side by side and normalize events into the shape your application already uses. ZapSMTP sends one event per recipient (`data.to` is a single address), retries failures for about 28 hours and keeps the event id stable in `Zap-Event-Id`. The delivery events of an email you sent (`email.sent` through `email.suppressed`) carry its `tags` and `metadata`. `email.replied` carries the tags but not the metadata, and inbound and conversation events (`email.received`, `thread.*`) have their own payloads; see [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/). Creating a webhook needs a live key.

**Normalize ZapSMTP events**

Node.js:

```javascript
// One handler for both providers while traffic is split.
// ZapSMTP posts one JSON event per request and per recipient; verify
// Zap-Signature first (see /docs/webhook-events/#signatures).
const ZAP = {
  'email.delivered': 'delivered',
  'email.delivery_delayed': 'deferred',
  'email.bounced': 'bounced',
  'email.complained': 'complained',
  'email.suppressed': 'dropped',
  'email.failed': 'dropped',
  'email.opened': 'opened',
  'email.clicked': 'clicked',
};

export function fromZap(event) {
  const kind = ZAP[event.type];
  if (!kind) return null;
  return {
    kind,
    email: event.data.to,                 // a single address
    messageId: event.data.email_id,
    permanent: event.data.bounce?.type === 'Permanent',
    meta: event.data.metadata ?? {},      // your former custom args
  };
}
```

Python:

```python
ZAP = {
    "email.delivered": "delivered",
    "email.delivery_delayed": "deferred",
    "email.bounced": "bounced",
    "email.complained": "complained",
    "email.suppressed": "dropped",
    "email.failed": "dropped",
    "email.opened": "opened",
    "email.clicked": "clicked",
}

def from_zap(event: dict) -> dict | None:
    kind = ZAP.get(event["type"])
    if kind is None:
        return None
    data = event["data"]
    return {
        "kind": kind,
        "email": data["to"],                       # a single address
        "message_id": data["email_id"],
        "permanent": (data.get("bounce") or {}).get("type") == "Permanent",
        "meta": data.get("metadata") or {},
    }
```

## Subscribe your webhook endpoint

`POST /v1/webhooks`

Point a new endpoint, or a new path on your existing handler, at ZapSMTP and keep the old provider’s endpoint running until cutover. The response contains the `whsec_…` signing secret.

Requires a full-access live key; test keys get 403 test_key_restricted.

The secret is also readable later via GET /webhooks/{id}.

To send clicks of one button to this endpoint: `{"events": ["email.clicked"], "filter": {"actions": ["confirm_order"]}}`. Endpoints always return `filter`, with an empty list when there is none.

### Body parameters

- `url` (string, required): Absolute https:// URL. Limits: 422 invalid_parameter "url must be an absolute https:// URL"
- `events` (string[]): Limits: unknown type → 422 invalid_parameter "unknown event type <x>; allowed: ..." One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `all event types`.
- `include_content` (boolean): `email.received` carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (`truncated: true`). Default `false`.
- `batch` (boolean): Send events up to 100 per request (or every second) as a JSON array, signed as one body; `Zap-Event-Id` is the batch id, each event keeps its own `id`. `email.received` with the full message still arrives alone. Default `false`.
- `filter` (object): Narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/); other event types are not affected. Empty or absent: every click. Default `{"actions": []}`.
  - `actions` (string[]): Action names (lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters). The endpoint then receives `email.clicked` only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/hooks/zapsmtp",
  "events": [
    "email.delivered",
    "email.delivery_delayed",
    "email.bounced",
    "email.complained",
    "email.suppressed",
    "email.failed"
  ]
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-21T15:40:00Z",
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": []
  }
}
```

## Import suppressions

Bring over hard bounces, complaints and unsubscribes before the first live email, so nobody who opted out or bounced is mailed again. Export them from your current provider (dashboard or API) as one address per line. `POST /suppressions/batch` takes up to 1,000 addresses per call and needs a full-access live key (test keys cannot change suppressions); imported entries use reason `manual` (stops every stream) or `unsubscribe` (stops broadcast mail only), while `hard_bounce` and `complaint` are set only by ZapSMTP itself. Sends to a suppressed address are skipped and reported as `email.suppressed`.

**Import a suppression export**

Node.js:

```javascript
// node import-suppressions.mjs suppressed.txt  (one address per line)
import { readFileSync } from 'node:fs';

const API = 'https://zapsmtp.xyz/v1';
const emails = [...new Set(readFileSync(process.argv[2], 'utf8')
  .split(/\r?\n/).map((s) => s.trim().toLowerCase()).filter(Boolean))];
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

for (let i = 0; i < emails.length; i += 1000) {
  const chunk = emails.slice(i, i + 1000);
  for (;;) {
    const res = await fetch(API + '/suppressions/batch', {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + process.env.ZAP_API_KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ emails: chunk, reason: 'manual' }),
    });
    if (res.status === 429 || res.status >= 500) {
      await sleep(1000 * Number(res.headers.get('Retry-After') ?? 1));
      continue;
    }
    if (!res.ok) throw new Error(res.status + ' ' + (await res.text()));
    const { added } = await res.json();
    console.log('rows', i, '-', i + chunk.length, 'added', added);
    break;
  }
  await sleep(200); // stay well under the rate limit
}
```

Python:

```python
# python import_suppressions.py suppressed.txt  (one address per line)
import os, sys, time, requests

API = "https://zapsmtp.xyz/v1"
with open(sys.argv[1]) as f:
    emails = sorted({line.strip().lower() for line in f if line.strip()})

s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['ZAP_API_KEY']}"
for i in range(0, len(emails), 1000):
    chunk = emails[i:i + 1000]
    while True:
        r = s.post(f"{API}/suppressions/batch",
                   json={"emails": chunk, "reason": "manual"}, timeout=60)
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        r.raise_for_status()
        print(f"rows {i}-{i + len(chunk)} added {r.json()['added']}")
        break
    time.sleep(0.2)  # stay well under the rate limit
```

## Import suppressions in bulk

`POST /v1/suppressions/batch`

Up to 1,000 addresses per call. Duplicates and addresses already on the list are kept as they are (except that a `manual` entry replaces an `unsubscribe`), so re-running an import is safe. `reason` is `manual`, which stops every stream, or `unsubscribe`, which stops broadcast mail only.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `emails` (string[], required): 1–1,000 addresses.
- `reason` (string): `manual`: no email at all; `unsubscribe`: no broadcast email (transactional email still goes out). One of `manual`, `unsubscribe`. Default `manual`.

### Errors

- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): Empty or over 1,000 addresses, an invalid address, or an unknown reason.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/suppressions/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "old-bounce@example.com",
    "complainer@example.net"
  ],
  "reason": "manual"
}'
```

**Response `201 Created`**

```json
{
  "object": "suppression_batch",
  "added": 2,
  "reason": "manual",
  "emails": [
    "ann@example.com",
    "bob@example.com"
  ]
}
```

## Import unsubscribes

`POST /v1/suppressions/batch`

Import marketing opt-outs with `reason: "unsubscribe"`: they then stop broadcast mail only, so receipts and password resets still reach those people. Import bounces and complaints as `manual`.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `emails` (string[], required): 1–1,000 addresses.
- `reason` (string): `manual`: no email at all; `unsubscribe`: no broadcast email (transactional email still goes out). One of `manual`, `unsubscribe`. Default `manual`.

### Errors

- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): Empty or over 1,000 addresses, an invalid address, or an unknown reason.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/suppressions/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "opted-out@example.com"
  ],
  "reason": "unsubscribe"
}'
```

**Response `201 Created`**

```json
{
  "object": "suppression_batch",
  "added": 2,
  "reason": "manual",
  "emails": [
    "ann@example.com",
    "bob@example.com"
  ]
}
```

## Migration plan

## 1. DNS side by side

Both providers can sign and send for the same domain at the same time. Adding and verifying a domain needs a full-access live key. Add ZapSMTP’s DKIM key under its own `zap` selector and leave the old provider’s key in place. A domain has one SPF record, so add the ZapSMTP include to it rather than publishing a second record, and keep the old include until the old provider sends nothing. Keep your DMARC record as it is. Live keys can send only from verified domains.

**Zone records through the migration**

Before:

```
acme.com.                TXT    "v=spf1 include:<old provider> ~all"
<old selector>._domainkey.acme.com.  CNAME/TXT  <old provider's DKIM key>
_dmarc.acme.com.         TXT    "v=DMARC1; p=quarantine; rua=mailto:dmarc@acme.com"
```

During migration:

```
; one SPF record, both includes (SPF allows one record per name)
acme.com.                TXT    "v=spf1 include:<old provider> include:_spf.zapsmtp.xyz ~all"
; keep the old DKIM key and add ZapSMTP's: different selectors coexist
<old selector>._domainkey.acme.com.  CNAME/TXT  <old provider's DKIM key>
zap._domainkey.acme.com. TXT    "v=DKIM1; k=rsa; p=MIIBIjANBgkq…"
; DMARC unchanged: keep your existing policy and reports
_dmarc.acme.com.         TXT    "v=DMARC1; p=quarantine; rua=mailto:dmarc@acme.com"
```

After cutover:

```
acme.com.                TXT    "v=spf1 include:_spf.zapsmtp.xyz ~all"
zap._domainkey.acme.com. TXT    "v=DKIM1; k=rsa; p=MIIBIjANBgkq…"
_dmarc.acme.com.         TXT    "v=DMARC1; p=quarantine; rua=mailto:dmarc@acme.com"
```

## Add your sending domain

`POST /v1/domains`

Returns the DKIM, SPF and DMARC records. The DKIM selector is `zap`, so it sits next to your current provider’s key without conflict.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string, required): Domain name (lowercased, trailing dot removed). Limits: valid hostname <=253 chars, else 422 invalid_parameter "invalid domain name"

### Errors

- `plan_limit_reached` (HTTP 403): the <Plan> plan includes <n> domains; upgrade your plan to add more
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): domain already added
- `invalid_parameter` (HTTP 422): invalid domain name

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "acme.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "pending",
  "dkim_selector": "zap",
  "dkim_verified": false,
  "spf_verified": false,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": null,
  "verified_at": null,
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "pending"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "pending"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ]
}
```

## 2. Test keys, simulator and shadow traffic

A test key can send and read, but not change the account. It accepts any From domain, runs validation, stored templates, the email log, events and webhooks exactly like a live key, never delivers and does not count against your plan. Use it first against [simulator addresses](https://www.zapsmtp.xyz/docs/testing/) to exercise every webhook path, then mirror production requests to catch fields or templates that do not convert. Filter shadow traffic with `GET /emails?mode=test` and the [request log](https://www.zapsmtp.xyz/docs/logs/list-logs/).

## Test before any traffic moves

`POST /v1/emails`

Send with a test key (`zap_test_…`) to simulator addresses: bounces, complaints and delays reach your webhook within seconds without touching real recipients or your reputation.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz",
    "bounced@simulator.zapsmtp.xyz",
    "complained@simulator.zapsmtp.xyz"
  ],
  "subject": "Migration check",
  "text": "Webhook and suppression handling test."
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

**Mirror production sends with a test key**

Node.js:

```javascript
// Shadow: keep sending live through the old provider and replay every
// request to ZapSMTP with a test key (zap_test_…). Test keys run validation,
// templates, the email log and webhooks, deliver nothing and are not counted.
export async function send(msg) {
  const result = await oldProvider.send(msg);           // still the source of truth
  fetch('https://zapsmtp.xyz/v1/emails', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + process.env.ZAP_TEST_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify(toZap(msg)),
  })
    .then(async (r) => { if (!r.ok) log.warn('zapsmtp shadow', r.status, await r.text()); })
    .catch((e) => log.warn('zapsmtp shadow', e.message));  // never affects the user
  return result;
}
```

Python:

```python
import os, threading, requests

def send(msg: dict):
    result = old_provider.send(msg)  # still the source of truth
    def shadow():
        try:
            r = requests.post("https://zapsmtp.xyz/v1/emails", timeout=10,
                              headers={"Authorization": f"Bearer {os.environ['ZAP_TEST_KEY']}"},
                              json=to_zap(msg))
            if not r.ok:
                log.warning("zapsmtp shadow %s %s", r.status_code, r.text)
        except requests.RequestException as e:
            log.warning("zapsmtp shadow %s", e)
    threading.Thread(target=shadow, daemon=True).start()
    return result
```

## 3. Percentage rollout

Switch a growing share of recipients to a live key: 1%, 10%, 50%, then all. Bucketing by recipient keeps each address on one provider, which keeps its events and suppressions in one place. Send an `Idempotency-Key` so a retried request never sends twice; a `429` or `5xx` means nothing was accepted, so a retry or fallback is safe. A `200` with `unconfirmed: true` counts as sent and must not be retried.

**Route a percentage of traffic**

Node.js:

```javascript
import { createHash } from 'node:crypto';

// ZAP_PERCENT: 0 → 1 → 10 → 50 → 100. Hashing the recipient keeps each
// address on one provider, so its events and suppressions stay in one place.
const bucket = (email) => createHash('sha256').update(email.toLowerCase()).digest().readUInt16BE(0) % 100;

export async function send(msg, idempotencyKey) {
  if (bucket(msg.to) >= Number(process.env.ZAP_PERCENT ?? 0)) return oldProvider.send(msg);
  const res = await fetch('https://zapsmtp.xyz/v1/emails', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.ZAP_API_KEY,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,   // safe to retry
    },
    body: JSON.stringify(toZap(msg)),
  });
  if (res.ok) return res.json();
  // 429 and 5xx mean nothing was accepted: retry later, or fall back once
  if (res.status === 429 || res.status >= 500) return oldProvider.send(msg);
  throw new Error('ZapSMTP ' + res.status + ': ' + (await res.text())); // 4xx: fix the request
}
```

Python:

```python
import hashlib, os, requests

def bucket(email: str) -> int:
    return int.from_bytes(hashlib.sha256(email.lower().encode()).digest()[:2], "big") % 100

def send(msg: dict, idempotency_key: str):
    if bucket(msg["to"]) >= int(os.environ.get("ZAP_PERCENT", "0")):
        return old_provider.send(msg)
    r = requests.post("https://zapsmtp.xyz/v1/emails", timeout=30, json=to_zap(msg), headers={
        "Authorization": f"Bearer {os.environ['ZAP_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    })
    if r.ok:
        return r.json()
    if r.status_code == 429 or r.status_code >= 500:  # nothing was accepted
        return old_provider.send(msg)
    raise RuntimeError(f"ZapSMTP {r.status_code}: {r.text}")  # 4xx: fix the request
```

Between steps, compare delivery, bounce and complaint rates for the two providers using [statistics](https://www.zapsmtp.xyz/docs/stats/), and check the [deliverability guide](https://www.zapsmtp.xyz/docs/deliverability/) if you send high volumes from new IPs.

## 4. Cutover checklist

- Domain verified: DKIM shows verified, SPF includes ZapSMTP, DMARC reports show ZapSMTP mail passing.
- Live API keys created per application and environment; SMTP credentials per application.
- Every template converted, rendered with real data and published.
- Webhook endpoint subscribed, signatures verified, duplicates skipped by `Zap-Event-Id`, a test event received ([send one](https://www.zapsmtp.xyz/docs/webhooks/test-webhook/)).
- Suppressions imported, including any added on the old provider during the rollout.
- Error handling covers `422` validation errors, `429` with `Retry-After`, and quota errors; see [Errors, limits & paging](https://www.zapsmtp.xyz/docs/conventions/).
- Rollout at 100% for a full sending cycle (daily and weekly jobs included) with stable rates.
- Then remove the old provider’s SPF include and DKIM record, and revoke its keys.

## 5. Rollback

Until the old provider’s DNS and keys are removed, rollback is a configuration change: set the rollout percentage to 0 (or point the SMTP host back). Before you resume on the old provider, copy over the suppressions ZapSMTP collected (bounces, complaints and one-click unsubscribes) so those recipients stay excluded. Webhook retries for emails already sent through ZapSMTP keep arriving, so leave the ZapSMTP endpoint running until they finish.

## Export suppressions for a rollback

`GET /v1/suppressions`

Page through the list with `after=next_cursor` and add the addresses to the previous provider, so recipients who bounced, complained or unsubscribed on ZapSMTP stay excluded there too.

Requires a full-access key.

`reason` is `hard_bounce`, `complaint`, `unsubscribe` or `manual`; `source_id` is the email that caused it (`null` when added by hand). Pass `next_cursor` as `after` for the next page.

`unsubscribe` stops only broadcast email (`stream: broadcast`); transactional email to the address still goes out. Every other reason stops all email to it.

### Query parameters

- `limit` (integer): 1-1000; out-of-range falls back to 100. Default `100`.
- `after` (string): Opaque cursor from next_cursor. Limits: 422 invalid_parameter "invalid after cursor"
- `before` (string): Legacy: RFC 3339 timestamp; returns entries created before it. Ignored when after is set. Limits: 422 invalid_parameter "before must be RFC3339"

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422)

```bash
curl 'https://zapsmtp.xyz/v1/suppressions?limit=1000' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "email": "old@example.org",
      "reason": "hard_bounce",
      "source_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "created_at": "2026-10-21T15:04:13Z"
    },
    {
      "email": "angry@example.net",
      "reason": "complaint",
      "source_id": "019a1f2a-1b2c-7d3e-8f4a-5b6c7d8e9f00",
      "created_at": "2026-10-21T11:20:40Z"
    }
  ],
  "next_cursor": "MTc2MTA0NzI0MDAwMDAwMDAwMHxhbmdyeUBleGFtcGxlLm5ldA"
}
```

---

# Sending email

Source: https://www.zapsmtp.xyz/docs/sending/

Everything [POST /emails](https://www.zapsmtp.xyz/docs/emails/send-email/) can do, with a working example for each. The examples send to the simulator: paste a test key and press **Try it** (the attachment-by-URL example points at a placeholder URL and has no Try it). Field names follow Resend, so an existing Resend integration only needs a new base URL and key.

> Base URL `https://zapsmtp.xyz/v1`. Send `Authorization: Bearer <key>` and a JSON body. Unknown fields are rejected with `400 validation_error`, so a misspelled field name is not silently ignored. The whole request, attachments included, may be up to 40 MB.

## Senders and recipients

Addresses use the RFC 5322 format: a bare `jane@example.org` or a display name with the address in angle brackets, `Jane Doe <jane@example.org>`. Put a display name that contains a comma or other punctuation in double quotes. Non-ASCII names are encoded for you.

**Address fields**

- **`from` (required)**: One address. With a live key its domain must be verified in your account (`403 domain_not_verified` otherwise); a test key accepts any domain. When you send only an address, the domain’s brand `from_name` becomes the display name. May be omitted when the template defines a sender.
- **`to` (required)**: A string or an array. At least one address.
- **`cc`, `bcc`**: A string or an array. Bcc addresses receive the email but are never written into its headers.
- **`reply_to`**: A string or an array: where replies go instead of `from`.
- **Limit**: At most 50 addresses across `to`, `cc` and `bcc` combined (`422 invalid_parameter`, “too many recipients (max 50)”). Recipients are lowercased and duplicates are sent once.
- **Invalid address**: `422 invalid_parameter` naming the field and the address, e.g. `invalid to address "jane@"`.

One email to several recipients is one message: everyone sees the same `To` and `Cc` headers. To send each person their own copy, use a batch with one recipient per email.

## Display names, cc, bcc and reply_to

`POST /v1/emails`

`to`, `cc`, `bcc` and `reply_to` take a string or an array; `from` takes one string. Display names are optional; Bcc recipients get the email but are not written into its headers.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "Jane Doe <delivered+jane@simulator.zapsmtp.xyz>"
  ],
  "cc": "\"Doe, John\" <delivered+john@simulator.zapsmtp.xyz>",
  "bcc": [
    "delivered+audit@simulator.zapsmtp.xyz"
  ],
  "reply_to": "Acme Support <support@acme.com>",
  "subject": "Your order has shipped",
  "text": "Your order A-1042 is on its way."
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## HTML and text

Send `html`, `text` or both; at least one is required (`422 missing_required_field`, “html or text is required”). `subject` is required and may not be blank. Some clients and many spam filters look at the text part, so an email with `html` and no `text` gets one generated from the HTML: links become “text (url)”, and hidden elements such as the preheader, styles and scripts are left out. Send your own `text` when you want to control its wording. Messages sent through SMTP relay go out exactly as given.

**What is sent**

- **`text` only**: A single `text/plain` part (UTF-8).
- **`html` only**: `multipart/alternative` with a text part generated from the HTML, then the HTML.
- **Both**: `multipart/alternative` with the text first and the HTML second.
- **`template`**: Instead of `html` and `text`; see Templates. A template without a text body gets a generated text part too.

## Send plain text only

`POST /v1/emails`

Omit `html` and the email goes out as a single `text/plain` part.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": "delivered@simulator.zapsmtp.xyz",
  "subject": "Your sign-in code",
  "text": "Your sign-in code is 482913. It expires in 10 minutes."
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Send HTML with a text alternative

`POST /v1/emails`

With both bodies the email is `multipart/alternative`: clients that cannot show HTML show the text.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Welcome to Acme",
  "html": "<h1>Welcome, Jane</h1><p>Your workspace is ready. <a href=\"https://acme.com/start\">Get started</a>.</p>",
  "text": "Welcome, Jane\n\nYour workspace is ready. Get started: https://acme.com/start"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Templates

Pass `template: {"id": "welcome", "variables": {"first_name": "Jane"}}` to render a stored template by id or alias instead of sending `html` or `text` (combining them returns `422 invalid_parameter`). Sends always use the published version. Every variable the template uses must be supplied, otherwise `422 template_render_error` lists the missing ones. A `subject` or `from` in the request overrides the template’s. See [Templates](https://www.zapsmtp.xyz/docs/templates/) and the [template editor](https://www.zapsmtp.xyz/docs/template-editor/).

## Attachments

Each item in `attachments` carries the file either inline in `content` or as a URL in `path`, never both.

**Attachment fields**

- **`filename` (required)**: The name the recipient sees. With `path` it may be omitted: the last segment of the URL is used.
- **`content`**: The file, standard base64 with padding.
- **`path`**: An `http(s)` URL we download when you send. The download must answer `200` within 20 seconds. Private and internal addresses are refused.
- **`content_type`**: MIME type. When omitted it comes from the file extension, or from the server’s `Content-Type` for a `path`.
- **`content_id`**: Makes the file inline: reference it in the HTML as `cid:<content_id>`. In an email without `html` it is sent as an ordinary attachment.
- **Size**: The request body is limited to 40 MB (`413 payload_too_large`); base64 makes a file about a third larger, so plan on roughly 30 MB of files. Files fetched by `path` may add up to 40 MB per request, a batch included.
- **Errors**: `422 invalid_attachment` with the index, e.g. `attachments[0]: content must be base64`, `filename is required`, `set either content or path, not both`, `fetching path returned HTTP 404`.

Receiving servers often refuse messages over 20–25 MB, whatever we accept. For large files, send a link instead. Attachments of a sent email can be read back with [GET /emails/{id}/attachments](https://www.zapsmtp.xyz/docs/emails/list-sent-attachments/).

**Base64-encode a file**

Node.js:

```javascript
import { readFile } from 'node:fs/promises';

const content = (await readFile('invoice.pdf')).toString('base64');
const attachment = { filename: 'invoice.pdf', content };
```

Python:

```python
import base64

with open("invoice.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode("ascii")
attachment = {"filename": "invoice.pdf", "content": content}
```

PHP:

```php
$attachment = [
    'filename' => 'invoice.pdf',
    'content'  => base64_encode(file_get_contents('invoice.pdf')),
];
```

Go:

```go
data, err := os.ReadFile("invoice.pdf")
if err != nil {
    return err
}
attachment := map[string]string{
    "filename": "invoice.pdf",
    "content":  base64.StdEncoding.EncodeToString(data),
}
```

Ruby:

```ruby
require "base64"

attachment = {
  filename: "invoice.pdf",
  content: Base64.strict_encode64(File.binread("invoice.pdf")),
}
```

## Attach a file

`POST /v1/emails`

Put the file in `content` as standard base64 (with padding). `content_type` is optional: it is detected from the file name.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Your export",
  "text": "The export you asked for is attached.",
  "attachments": [
    {
      "filename": "orders.csv",
      "content": "b3JkZXIsdG90YWwKQS0xMDQyLDQyLjAwCg==",
      "content_type": "text/csv"
    }
  ]
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Attach a file by URL

`POST /v1/emails`

Set `path` instead of `content` and we download the file when you send. Without a `filename`, the last segment of the URL is used.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Invoice A-1042",
  "html": "<p>Your invoice is attached.</p>",
  "attachments": [
    {
      "path": "https://acme.com/invoices/A-1042.pdf",
      "filename": "invoice-A-1042.pdf"
    }
  ]
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Embed an inline image

`POST /v1/emails`

Give the attachment a `content_id` and reference it from the HTML as `cid:<content_id>`. The image travels with the email, so it shows even when the client blocks remote images.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Inline image",
  "html": "<p><img src=\"cid:logo\" width=\"120\" alt=\"Acme\"></p><p>Thanks for signing up.</p>",
  "attachments": [
    {
      "filename": "logo.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "content_type": "image/png",
      "content_id": "logo"
    }
  ]
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Custom headers

`headers` is an object of header names to string values. Headers that we build or that receivers trust for authentication cannot be set and return `422 invalid_parameter` (“header … cannot be set”):

- `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Subject`, `Date`, `Message-ID`, `MIME-Version`, `Content-Type`, `Content-Transfer-Encoding`: use the body fields instead.
- `DKIM-Signature`, `Return-Path`, `Received`, `Sender`, `Authentication-Results`, `ARC-Seal`, `ARC-Message-Signature`, `ARC-Authentication-Results`, `Received-SPF`, `Resent-*`.
- Any `X-Zap-*` header.

Setting `In-Reply-To` and `References` to the `Message-ID` of the email you answer keeps the conversation together in the recipient’s client, and the response’s `thread_id` then names that conversation. On the broadcast stream, a `List-Unsubscribe` header of your own replaces the one we add.

## Add custom headers

`POST /v1/emails`

Header names are printable ASCII without spaces or colons; values may contain any text and are encoded for you.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Re: Delivery window",
  "text": "Tuesday works for us.",
  "headers": {
    "X-Entity-Ref-ID": "ticket-1042",
    "In-Reply-To": "<CAF1x8@mail.example.org>",
    "References": "<CAF1x8@mail.example.org>"
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Tags and metadata

**Tags and metadata**

- **`tags`**: An array of `{"name", "value"}`. Both match `^[A-Za-z0-9_-]{1,256}$`; at most 20 per email. Use them for categories you report on: they come back in webhooks as an object (`data.tags`, e.g. `{"category": "receipt"}`). On `email.opened` and `email.clicked` they are left out when the email’s tags, encoded, exceed 200 bytes and split delivery numbers in [GET /metrics?tag=category=receipt](https://www.zapsmtp.xyz/docs/stats/metrics/).
- **`metadata`**: An object of strings: at most 10 keys, keys match `^[A-Za-z0-9_-]{1,40}$`, values up to 500 bytes (UTF-8). Use it for your own ids. It comes back in delivery webhooks (`data.metadata`), on `email.opened` and `email.clicked` when its JSON fits in 200 bytes (not on reply events), and on `GET /emails/{id}`, and filters the email list with `GET /emails?metadata[key]=value`.

Invalid tags or metadata return `422 invalid_parameter`.

## Tag an email and attach your own data

`POST /v1/emails`

Tags group email in metrics; metadata ties an email to your own records. Both come back on the email’s delivery webhooks; see the table above for the exceptions.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Your receipt",
  "html": "<p>Thanks for your order.</p>",
  "tags": [
    {
      "name": "category",
      "value": "receipt"
    },
    {
      "name": "plan",
      "value": "pro"
    }
  ],
  "metadata": {
    "order_id": "A-1042",
    "customer_id": "cus_8812"
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Find emails by metadata

`GET /v1/emails`

Exact match on a metadata value. Repeat the parameter to match several keys.

### Query parameters

- `metadata[order_id]` (string): Exact match on the `order_id` metadata value.

```bash
curl 'https://zapsmtp.xyz/v1/emails?metadata%5Border_id%5D=A-1042' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "email",
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "from": "Acme <hello@acme.com>",
      "subject": "Your receipt",
      "to": [
        "jane@example.org"
      ],
      "last_status": "delivered",
      "last_event": "delivered",
      "created_at": "2026-10-21T15:04:10.902Z",
      "stream": "transactional",
      "test": false,
      "metadata": {
        "order_id": "A-1042"
      }
    }
  ]
}
```

## Idempotency

A timeout does not tell you whether the email was sent. Send an `Idempotency-Key` header (1–256 bytes) with `POST /emails` or `POST /emails/batch`, and a retry with the same key within 24 hours returns the first result instead of sending again. Keys are scoped to your API key and kept for 24 hours, together with a fingerprint of the request.

**A second request with the same key**

- **Same body, first request finished**: The original status and body come back, with the header `Idempotent-Replayed: true`. Nothing is sent again.
- **Different body**: `409 idempotency_key_reused`
- **First request still running**: `409 idempotency_request_in_progress`: wait briefly and retry.
- **First request got `429` or a `5xx`**: The key is released, so a retry with it is processed as new.
- **Key over 256 bytes**: `400 invalid_idempotency_key`

Use a key that names the email in your system, such as `order-1042-receipt`, not a random value created per attempt. Errors from the send itself (for example `422` or `403`) are stored under the key too: after fixing the request, use a new key. Errors found before the key is checked, such as malformed JSON, an unknown field, a body over 40 MB or an invalid batch size or `x-batch-validation`, are not stored.

## Send exactly once

`POST /v1/emails`

Derive the key from your own record, so every retry of the same email carries the same key.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: order-1042-receipt' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Your receipt",
  "text": "Thanks for your order A-1042."
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13"
}
```

## Scheduling

Add `scheduled_at` and the email waits until then. The request is checked when you make it: addresses, content, headers, tags, metadata, stream and the sender domain, so those errors come back at once. Rate limits, quotas and suppressions are applied when the email is dispatched: a rate-limited dispatch is retried later, while other dispatch failures, such as an exhausted monthly quota, mark the email `failed` with the reason, and suppressed recipients are skipped as for an immediate send.

**scheduled_at**

- **RFC 3339**: `2026-10-28T09:00:00Z` or with an offset, `2026-10-28T11:00:00+02:00`.
- **Relative**: `in <n> <unit>`, unit `min`, `mins`, `minute`, `minutes`, `h`, `hour`, `hours`, `d`, `day` or `days`: `in 30 minutes`, `in 2 hours`, `in 1 day`. Other phrases (“tomorrow at 9am”) are not understood.
- **In the past**: Sent immediately.
- **Limits**: Up to 7 days ahead (`422 invalid_parameter`, “scheduled_at must be within 7 days”). At most 10,000 emails, 256 MB in total, may wait per account.
- **At send time**: The account and the API key are checked again: a suspended account or a revoked or expired key fails the email, and `GET /emails/{id}` shows `failed` with the reason.

While it waits, `GET /emails/{id}` returns `status: "scheduled"` with its `scheduled_at`, and `GET /emails?status=scheduled` lists waiting emails, soonest first: up to `limit` of them (default 20, at most 100). That list has no further pages (`has_more` is always `false`), so with more waiting emails than the limit you see only the soonest. Rescheduling and canceling work until the email is dispatched; after that, and for unknown ids, they return `409 not_cancellable`. A key restricted to a domain or stream can only manage its own scheduled emails, and a test key cannot touch live ones (`403 restricted_api_key`).

## Schedule an email

`POST /v1/emails`

The response returns the id at once; nothing is sent until the time comes.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Your trial ends tomorrow",
  "text": "Your Acme trial ends tomorrow. Upgrade any time from Settings.",
  "scheduled_at": "in 1 hour"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f40-2b3c-7d4e-8f5a-6b7c8d9e0f12",
  "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13"
}
```

## Move a scheduled email

`PATCH /v1/emails/{id}`

Only `scheduled_at` can change. The new time follows the same rules as when scheduling.

### Path parameters

- `id` (string, required): Scheduled email id

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/emails/019a1f40-2b3c-7d4e-8f5a-6b7c8d9e0f12' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "scheduled_at": "2026-10-28T09:00:00Z"
}'
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f40-2b3c-7d4e-8f5a-6b7c8d9e0f12",
  "status": "scheduled",
  "last_event": "scheduled",
  "scheduled_at": "2026-10-23T09:00:00Z",
  "from": "Acme <hello@acme.com>",
  "to": [
    "jane@example.org"
  ],
  "subject": "Your weekly digest",
  "created_at": "2026-10-21T16:20:05.114Z"
}
```

## Cancel a scheduled email

`POST /v1/emails/{id}/cancel`

The email is never sent and its status becomes `canceled`.

### Path parameters

- `id` (string, required): Scheduled email id

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/019a1f40-2b3c-7d4e-8f5a-6b7c8d9e0f12/cancel' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f40-2b3c-7d4e-8f5a-6b7c8d9e0f12",
  "status": "canceled"
}
```

## Batch sending

[POST /emails/batch](https://www.zapsmtp.xyz/docs/emails/send-batch/) takes an array of 1 to 100 emails (`422 invalid_parameter` otherwise), each with the fields of a single send, and sends them concurrently. The 40 MB body limit applies to the whole batch. One `Idempotency-Key` covers the whole request.

**x-batch-validation**

- **`strict` (default)**: Every email is validated first. If any is invalid, nothing is sent and the response is `422 validation_error` with an `errors` array of `{index, code, message}`.
- **`permissive`**: Valid emails are sent; invalid ones appear in `errors` and the response is `200`.

A `200` response holds `data`, one `{index, id}` per accepted email (plus `suppressed` when some of its recipients were skipped), and `errors`. `index` is the email’s position in your array. Failures that happen at send time, such as `rate_limit_exceeded` or `monthly_quota_exceeded`, are reported inside `errors` in either mode rather than as the HTTP status, so always read `errors`. To retry only the failed emails, send them in a new batch with a new Idempotency-Key: repeating the old key replays the old response.

## Send a batch

`POST /v1/emails/batch`

Up to 100 emails in one request. Each item is a complete email and may use its own sender, stream or `scheduled_at`.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: digest-2026-10-26-chunk-1' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered+ann@simulator.zapsmtp.xyz"
    ],
    "subject": "Your weekly digest",
    "text": "Hi Ann, here is your week.",
    "tags": [
      {
        "name": "category",
        "value": "digest"
      }
    ]
  },
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered+bob@simulator.zapsmtp.xyz"
    ],
    "subject": "Your weekly digest",
    "text": "Hi Bob, here is your week.",
    "tags": [
      {
        "name": "category",
        "value": "digest"
      }
    ]
  }
]'
```

**Response `200 OK`**

```json
{
  "data": [
    {
      "index": 0,
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    },
    {
      "index": 1,
      "id": "019a1f2e-7c3c-7a10-8b21-4d5e6f7a8b9c"
    }
  ],
  "errors": []
}
```

## Send the valid emails, report the rest

`POST /v1/emails/batch`

With `x-batch-validation: permissive` the valid emails are sent and each invalid one is reported by its index.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'x-batch-validation: permissive' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered+ann@simulator.zapsmtp.xyz"
    ],
    "subject": "Hello Ann",
    "text": "Hi Ann!"
  },
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered+bob@simulator.zapsmtp.xyz"
    ],
    "text": "Hi Bob!"
  },
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "suppressed@simulator.zapsmtp.xyz"
    ],
    "subject": "Hello Cy",
    "text": "Hi Cy!"
  }
]'
```

**Response `200 OK`**

```json
{
  "data": [
    {
      "index": 0,
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    },
    {
      "index": 2,
      "id": "019a1f2e-7c3c-7a10-8b21-4d5e6f7a8b9c",
      "suppressed": [
        "suppressed@simulator.zapsmtp.xyz"
      ]
    }
  ],
  "errors": [
    {
      "index": 1,
      "code": "missing_required_field",
      "message": "subject is required"
    }
  ]
}
```

## Streams

`stream` is `transactional` (the default) or `broadcast`. On shared IPs the two leave from separate pools, so newsletter traffic does not slow down or weigh on the reputation of your password resets. An account with a dedicated IP pool sends both streams from it. Any other value returns `422 invalid_parameter`. A key restricted to one stream sends on it by default and gets `403 restricted_api_key` when asked for the other.

A broadcast email to a single recipient gets RFC 8058 one-click unsubscribe headers (`List-Unsubscribe` and `List-Unsubscribe-Post`) unless you set your own; an unsubscribe adds the address to your suppressions with reason `unsubscribe`, which stops later broadcast mail to it but not transactional mail. Hard bounces, complaints and `manual` suppressions apply to both streams. For a link in the body, write `{{{zap:unsubscribe_url}}}` in the HTML or text: it becomes the recipient’s signed unsubscribe link when the email is sent, with or without a template.

`tracking: {"opens": true, "clicks": true}` overrides the From domain’s open and click tracking for one email. `tls: "required"` delivers only over TLS and `tls: "verified"` also requires a valid certificate on the receiving server; either raises the domain’s TLS policy and never lowers it.

## Send on the broadcast stream

`POST /v1/emails`

Marketing and bulk mail goes on `broadcast`. The one-click unsubscribe headers are added for you; the body link below is optional.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme News <news@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "What shipped in October",
  "stream": "broadcast",
  "html": "<p>Three new features this month.</p><p><a href=\"{{{zap:unsubscribe_url}}}\">Unsubscribe</a></p>",
  "tracking": {
    "opens": true,
    "clicks": true
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Test keys and the simulator

Keys that start with `zap_test_` go through the same validation, email log, events and webhooks as live keys, accept any From domain, deliver nothing and do not count against your monthly plan (the per-second limit still applies). Addresses at `simulator.zapsmtp.xyz` act out outcomes with live and test keys alike: `delivered@`, `bounced@`, `full@`, `blocked@`, `delayed@`, `complained@`, `suppressed@`, and `bounce+<code>@` for any reply you need. They accept `+labels` and never touch your suppression list or reputation. See [Testing & simulator](https://www.zapsmtp.xyz/docs/testing/).

## Exercise the failure paths

`POST /v1/emails`

One request, three outcomes: each simulator recipient produces its own events and webhooks within seconds.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz",
    "bounced@simulator.zapsmtp.xyz",
    "delayed@simulator.zapsmtp.xyz"
  ],
  "subject": "Simulator run",
  "text": "Testing every path."
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## The response and what to store

A `200` means the email was accepted, not that it was delivered. Store `id` with your record: the email’s delivery webhooks carry it as `data.email_id`, and [GET /emails/{id}](https://www.zapsmtp.xyz/docs/emails/get-email/) returns its status and timeline. Delivery results arrive by [webhook](https://www.zapsmtp.xyz/docs/webhook-events/).

**Response fields**

- **`id`**: The email’s id, a time-ordered UUIDv7. Also part of the `Message-ID` header.
- **`thread_id`**: The conversation the email belongs to. Replies to it carry the same `thread_id`.
- **`suppressed`**: Recipients skipped because they are on your suppression list. Each gets an `email.suppressed` event. If every recipient is suppressed the request still succeeds: there is nothing to retry.
- **`failed_recipients`**: Recipients refused while the others were taken. They are not sent and not charged.
- **`unconfirmed`**: `true` when the message was handed over but the confirmation was lost. It counts as sent; do not retry it. Its events tell the outcome. ZapSMTP checks these sends itself: recipients the MTA never logged receiving are sent again once that MTA node has been back for 10 minutes, or after it has been down for an hour in a row. A rare duplicate is possible. A loss is extremely unlikely: ZapSMTP keeps the message to check it, and only if object storage stays unavailable for minutes is a send left unchecked (we count those).

Responses to immediate sends usually report your budget: `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` for recipients per second, and `Zap-Quota-Monthly-Limit` and `Zap-Quota-Monthly-Remaining` for the month. On paid plans without a spending cap, `Zap-Quota-Monthly-Limit` is `unlimited` and the remaining header is omitted. Scheduling responses, and accounts without a per-second limit, carry none of these headers. Every response carries an `X-Request-Id`; log it and include it when you contact support.

## Check what happened

`GET /v1/emails/{id}`

Per-recipient status and the full event timeline, including the receiving server’s reply.

### Path parameters

- `id` (string, required): Email id

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "from": "Acme <hello@acme.com>",
  "subject": "Your receipt",
  "created_at": "2026-10-21T15:04:10.902Z",
  "recipients": [
    {
      "email": "jane@example.org",
      "status": "delivered",
      "updated_at": "2026-10-21T15:04:12.381Z",
      "response": "250 2.0.0 OK 1761059052 x7si123"
    }
  ],
  "events": [
    {
      "type": "Reception",
      "status": "queued",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:10.902Z",
      "attempts": 0
    },
    {
      "type": "Delivery",
      "status": "delivered",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:12.381Z",
      "response_code": 250,
      "response": "250 2.0.0 OK 1761059052 x7si123",
      "attempts": 1,
      "mx": "gmail-smtp-in.l.google.com.",
      "peer_addr": "142.250.153.27",
      "tls": "TLSv1.3 TLS_AES_256_GCM_SHA384",
      "egress_source": "ip-1"
    }
  ],
  "stream": "transactional",
  "test": false,
  "metadata": {
    "order_id": "A-1042"
  }
}
```

## Errors and retries

Errors carry the HTTP status plus `name` (the error code) and `message`; the full list is in [Errors, limits & paging](https://www.zapsmtp.xyz/docs/conventions/#errors). Retry only what can succeed unchanged, always with the same Idempotency-Key, and back off exponentially when there is no `Retry-After`.

**Should you retry?**

- **`rate_limit_exceeded` (HTTP 429)**: Yes. Wait for `Retry-After` (1 second).
- **`overloaded` (HTTP 429)**: Yes. The server is at capacity or briefly backed up and nothing was sent: wait for `Retry-After` (1 or 5 seconds).
- **`service_unavailable` (HTTP 503)**: Yes. Wait for `Retry-After` (2–5 seconds).
- **`internal_error` (HTTP 500)**: Yes, with backoff and the same Idempotency-Key.
- **`idempotency_request_in_progress` (HTTP 409)**: Yes, after a short pause: the first request with this key is still running.
- **`Network error or timeout` (no response)**: Yes, with the same Idempotency-Key: you cannot tell whether the first attempt was accepted.
- **`daily_quota_exceeded` (HTTP 429)**: Not until the limit resets at 00:00 UTC.
- **`monthly_quota_exceeded` (HTTP 429)**: No. The Free plan or your spending cap is reached for the month.
- **`misdirected_cell` (HTTP 421)**: Not here. Your account is served by another cell: send to the URL named in the message (the `Zap-Cell` header names the cell).
- **`idempotency_key_reused` (HTTP 409)**: No. The key was used for a different body: fix the key, not the timing.
- **`400, 401, 403, 413, 422` (HTTP 4xx)**: No. The request itself has to change; the message says what is wrong.

The per-second limit counts recipients across all your requests. If you send in bursts, spread them using `RateLimit-Remaining` rather than waiting for `429`s.

**Retry safely**

Node.js:

```javascript
const API = 'https://zapsmtp.xyz/v1';
// Safe to repeat with the same Idempotency-Key: the email is sent at most once.
const RETRYABLE = new Set(['rate_limit_exceeded', 'overloaded', 'idempotency_request_in_progress', 'internal_error', 'service_unavailable']);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function send(email, idempotencyKey) {
  for (let attempt = 0; ; attempt++) {
    let res;
    try {
      res = await fetch(`${API}/emails`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.ZAP_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify(email),
      });
    } catch (networkError) {
      if (attempt >= 5) throw networkError;
      await sleep(2 ** attempt * 500); // no answer: retry with the same key
      continue;
    }
    const body = await res.json();
    if (res.ok) return body; // store body.id
    if (!RETRYABLE.has(body.name) || attempt >= 5) {
      throw new Error(`${res.status} ${body.name}: ${body.message}`);
    }
    const retryAfter = Number(res.headers.get('Retry-After'));
    await sleep(retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 500);
  }
}
```

Python:

```python
import os, time, requests

API = "https://zapsmtp.xyz/v1"
RETRYABLE = {"rate_limit_exceeded", "overloaded", "idempotency_request_in_progress", "internal_error", "service_unavailable"}

def send(email: dict, idempotency_key: str) -> dict:
    for attempt in range(6):
        try:
            res = requests.post(
                f"{API}/emails",
                json=email,
                headers={
                    "Authorization": f"Bearer {os.environ['ZAP_API_KEY']}",
                    "Idempotency-Key": idempotency_key,
                },
                timeout=30,
            )
        except requests.RequestException:
            time.sleep(2 ** attempt * 0.5)  # no answer: retry with the same key
            continue
        body = res.json()
        if res.ok:
            return body  # store body["id"]
        if body.get("name") not in RETRYABLE:
            raise RuntimeError(f"{res.status_code} {body.get('name')}: {body.get('message')}")
        time.sleep(float(res.headers.get("Retry-After") or 2 ** attempt * 0.5))
    raise RuntimeError("gave up after 6 attempts")
```

## SMTP instead of the API

If your application or platform already speaks SMTP, point it at the ZapSMTP relay with SMTP credentials. Messages sent that way get the same suppression checks, events, webhooks and email log. The API is the better fit when you want attachments by URL, templates, tags and metadata, scheduling, batches and idempotency. See [SMTP relay](https://www.zapsmtp.xyz/docs/smtp/).

---

# Domains & DNS setup

Source: https://www.zapsmtp.xyz/docs/domain-setup/

Live keys send only from verified domains. Add the domain, publish the TXT records ZapSMTP generates for it, and it verifies by itself within a minute of the DKIM record going live. This guide covers every record, every common DNS provider, and what to do when a record will not verify.

1. **Add the domain** in the dashboard under *Domains* or with POST /domains.
2. **Publish three TXT records** at your DNS provider: DKIM (required), SPF and DMARC (recommended).
3. **Wait for the check.** New domains are checked every minute; or press *Verify now* / call POST /domains/{id}/verify.
4. **Send with a live key** from any address at that exact domain.

> Adding, verifying, changing and deleting domains need a **live, full-access** key. Test keys can read domains but get `403 test_key_restricted` on any change, and restricted keys get `403 restricted_api_key`.

![A verified domain with its DKIM, SPF and DMARC records, each marked Found, and a copy button for each value](https://www.zapsmtp.xyz/docs/img/domain-light.webp)

## The records

All three are TXT records. Names and values below are for `acme.com`; yours come back from the API and the dashboard ready to copy.

**Records for acme.com**

- **DKIM (required)**: Name `zap._domainkey.acme.com` Value `v=DKIM1; k=rsa; p=MIIBIjANBg…IDAQAB`
- **SPF (recommended)**: Name `acme.com` Value `v=spf1 include:_spf.zapsmtp.xyz ~all`
- **DMARC (recommended)**: Name `_dmarc.acme.com` Value `v=DMARC1; p=none;`

### DKIM

When you add a domain we generate a 2048-bit RSA key pair for it. The private key stays with us, encrypted, and signs every message you send from that domain; the public key goes in DNS under the selector `zap`, so the name is always `zap._domainkey.<your domain>`. Because the selector is our own, it never collides with DKIM keys of other services (Google Workspace uses `google`, for example), and you can keep all of them published side by side.

DKIM is the record that proves you control the domain, and the only one required for verification. It is also what makes DMARC pass: the signature is made with your domain, so it is aligned with your From address.

### SPF

SPF lists the servers allowed to send for a domain. The bounce address (Return-Path) of messages we send is on a ZapSMTP domain, so receivers evaluate SPF for that domain, which we publish; DMARC then passes through DKIM. The `include:_spf.zapsmtp.xyz` record on your own domain is still recommended: it authorizes our sending IPs for your domain for receivers and tools that check the From domain, and it is reported as its own status. A domain can have only one SPF record.

### DMARC

DMARC tells receivers what to do with mail that claims to be from your domain but fails authentication, and where to send reports about it. We suggest `p=none` to start: it changes nothing about delivery and turns on reporting. Gmail and Yahoo expect a DMARC record from bulk senders, and brand logos need an enforcing policy. See DMARC rollout for the path to `p=reject`.

> A subdomain without its own DMARC record inherits the policy of its parent domain. If `_dmarc.acme.com` exists, `mail.acme.com` passes the DMARC check without publishing `_dmarc.mail.acme.com`; the API shows it as `(inherited from _dmarc.acme.com)`.

## Root domain or a sending subdomain

A verified domain covers exactly that name. Verifying `acme.com` lets you send from `…@acme.com`, not from `…@mail.acme.com`; that is a separate domain to add and verify.

**Choosing the From domain**

- **Root (acme.com)**: **Pros:** the address people recognise; replies go to your normal mailboxes; one set of records. **Cons:** its reputation is shared with your staff mail and every other service sending as `acme.com`; the SPF record must be merged with the one you already have.
- **Subdomain (mail.acme.com)**: **Pros:** keeps product or marketing mail apart from staff mail, so a bad campaign does not hurt your team’s inbox placement; its own SPF record, with no merging; easy to split further (`news.`, `notify.`). **Cons:** recipients see the subdomain; replies need a mailbox or reply routing; reputation still partly follows the parent domain.

For a subdomain the records go in the same DNS zone as the parent. The `zone` field of the response names that zone (for `mail.acme.co.uk` it is `acme.co.uk`), and the host to type at most providers is the part before it.

**Records for mail.acme.com, entered in the acme.com zone**

- **DKIM**: Full name `zap._domainkey.mail.acme.com`, host `zap._domainkey.mail`
- **SPF**: Full name `mail.acme.com`, host `mail`
- **DMARC**: Full name `_dmarc.mail.acme.com`, host `_dmarc.mail` (optional when `_dmarc.acme.com` exists)

## Add the root domain

`POST /v1/domains`

Send as `hello@acme.com`. The response carries a fresh DKIM key and all three records to publish.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string, required): Domain name (lowercased, trailing dot removed). Limits: valid hostname <=253 chars, else 422 invalid_parameter "invalid domain name"

### Errors

- `plan_limit_reached` (HTTP 403): the <Plan> plan includes <n> domains; upgrade your plan to add more
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): domain already added
- `invalid_parameter` (HTTP 422): invalid domain name

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "acme.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "pending",
  "dkim_selector": "zap",
  "dkim_verified": false,
  "spf_verified": false,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": null,
  "verified_at": null,
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "pending"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "pending"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ]
}
```

## Add a sending subdomain

`POST /v1/domains`

Send as `hello@mail.acme.com`. Records are generated for the subdomain; the `zone` field names the DNS zone they go in.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string, required): Domain name (lowercased, trailing dot removed). Limits: valid hostname <=253 chars, else 422 invalid_parameter "invalid domain name"

### Errors

- `plan_limit_reached` (HTTP 403): the <Plan> plan includes <n> domains; upgrade your plan to add more
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): domain already added
- `invalid_parameter` (HTTP 422): invalid domain name

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "mail.acme.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "mail.acme.com",
  "status": "pending",
  "dkim_selector": "zap",
  "dkim_verified": false,
  "spf_verified": false,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": null,
  "verified_at": null,
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.mail.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "pending"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "mail.acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "pending"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.mail.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ]
}
```

## Fetch the records again

`GET /v1/domains/{id}`

The `records` array is regenerated on every read, so you can always copy the exact values. Each record has its own `status`.

Requires a full-access key.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): domain not found

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `200`.

## Adding the records at your DNS provider

Add records where your domain’s *nameservers* point, which is not always where you bought it. Run `dig +short NS acme.com` (or check your registrar) to see which provider answers for the domain. The rules that apply everywhere:

- **Host field.** Most providers append your domain to what you type. Enter `zap._domainkey`, not `zap._domainkey.acme.com`, or the record ends up at `zap._domainkey.acme.com.acme.com`. Use `@` (or leave the field empty, depending on the provider) for the root.
- **Quotes.** Paste the value without surrounding quotes unless the provider requires them (Route 53 and zone files do). Quotes kept literally inside the value break it.
- **Long DKIM values.** The key is longer than the 255-character limit of one TXT string. Most web consoles split it for you; where they do not, enter it as several quoted strings in one record. Receivers join them back without spaces.
- **TTL.** Any value works. Verification asks your nameservers directly, so a long TTL does not delay it; it only matters for how long old values stay in other resolvers’ caches after a change.

### Cloudflare

1. Open the domain, then *DNS → Records → Add record*.
2. Type `TXT`, Name `zap._domainkey` (Cloudflare accepts the short host or the full name), Content: the DKIM value. Save.
3. Repeat with Name `@` for SPF and `_dmarc` for DMARC.

TXT records have no proxy setting in Cloudflare, so the orange cloud is not involved; none of our records is a CNAME. If you already have `v=spf1` at `@`, edit that record instead of adding a second one.

### GoDaddy

1. *Domain Portfolio* → your domain → *DNS* → *Add New Record*.
2. Type `TXT`, Name `zap._domainkey`, Value: the DKIM value. Save.
3. SPF: Name `@`; DMARC: Name `_dmarc`.

GoDaddy appends the domain to the Name. New domains often come with a default `_dmarc` record; edit it rather than adding another.

### Amazon Route 53

1. *Hosted zones* → your domain → *Create record*.
2. Record name `zap._domainkey` (the console shows the domain suffix next to the field), Record type `TXT`.
3. Value: wrap it in double quotes. For the DKIM key, split it into quoted strings of up to 255 characters on one line, as below.
4. SPF: leave Record name empty for the root. DMARC: `_dmarc`.

Route 53 holds one TXT record set per name. If the root already has TXT values (an existing SPF, a site verification token), edit that record set and put each value on its own line, each in its own quotes.

**TXT values with quoting**

Route 53 value (long DKIM key):

```
"v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxq3…first 255 characters…" "…the rest of the key…IDAQAB"
```

Zone file (BIND):

```
$ORIGIN acme.com.
zap._domainkey  3600  IN  TXT  ( "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOC…"
                                 "…the rest of the key…IDAQAB" )
@               3600  IN  TXT  "v=spf1 include:_spf.zapsmtp.xyz ~all"
_dmarc          3600  IN  TXT  "v=DMARC1; p=none;"
```

### Namecheap

1. *Domain List* → *Manage* → *Advanced DNS* → *Add New Record* → *TXT Record*.
2. Host `zap._domainkey`, Value: the DKIM value. Save with the check mark.
3. SPF: Host `@`; DMARC: Host `_dmarc`.

These records only take effect while the domain uses Namecheap’s nameservers. If it points to another provider (Cloudflare, for example), add them there.

### Google Cloud DNS and Squarespace Domains

**Cloud DNS:** *Network services → Cloud DNS* → your zone → *Add standard* (record set). DNS name `zap._domainkey` (the zone’s suffix is filled in), Resource record type `TXT`, TXT data: the value. Put several values for one name, such as two TXT strings at the root, in the same record set.

**Squarespace Domains** (formerly Google Domains): your domain → *DNS* → *DNS settings* → *Custom records* → *Add record*. Host `zap._domainkey`, Type `TXT`, Data: the value. Use `@` for the root.

### DigitalOcean

1. *Networking → Domains* → your domain → *Create new record* → *TXT*.
2. Hostname `zap._domainkey` (the domain is appended), Value: the DKIM value.
3. SPF: Hostname `@`; DMARC: `_dmarc`.

As with every hosted DNS, this works only if the domain’s nameservers are DigitalOcean’s.

### Any other provider

Look for *DNS*, *Zone editor* or *Advanced DNS*, add three TXT records and check with dig that the full names match the table above. If the provider imports zone files, the BIND tab above works as is.

## If you already have an SPF record

A domain may publish only one TXT record that starts with `v=spf1`. With two, receivers return a permanent error and treat SPF as failed for *every* service on the domain. Add our include to the record you have, before the final `~all` or `-all`, and keep its existing qualifier. The verify response warns when it finds more than one SPF record. Note that SPF can still show `verified` in that case, because our check only looks for the include in any of them; the warning is what tells you receivers will fail it.

**Merging SPF**

Before (broken: two records):

```
acme.com.  TXT  "v=spf1 include:_spf.google.com ~all"
acme.com.  TXT  "v=spf1 include:_spf.zapsmtp.xyz ~all"
```

After (one merged record):

```
acme.com.  TXT  "v=spf1 include:_spf.google.com include:_spf.zapsmtp.xyz ~all"
```

Keeping an existing -all:

```
; keep the existing qualifier; only add the include before it
acme.com.  TXT  "v=spf1 ip4:192.0.2.0/24 include:_spf.google.com include:_spf.zapsmtp.xyz -all"
```

**The 10-lookup limit.** SPF allows at most 10 DNS lookups while evaluating a record: every `include`, `a`, `mx`, `exists` and `redirect` counts, including those nested inside includes. Past ten the result is a permanent error. If adding our include crosses the limit, remove services you no longer use, replace `a`/`mx` with explicit `ip4`/`ip6` ranges where they are stable, or move this mail to a sending subdomain with its own short record.

## Verification

A domain is `verified` as soon as its DKIM record contains the public key we generated. SPF and DMARC do not block verification; they are reported separately. The check:

- runs automatically **every minute** for pending domains, for **72 hours** after you add them. After that, press *Verify now* in the dashboard or call the verify endpoint;
- asks your domain’s authoritative nameservers directly (the one with the newest zone serial), so a record is seen seconds after your provider publishes it, regardless of TTL; it falls back to public resolvers;
- compares DKIM ignoring whitespace, so a key split into several strings matches; SPF passes when a record starting with `v=spf1` contains `include:_spf.zapsmtp.xyz`; DMARC passes when `_dmarc.<domain>`, or the parent domain’s, starts with `v=DMARC1`, whatever the policy.

**Reading the status**

- **`status`**: `pending` until DKIM matches, then `verified`. `verified_at` is when that first happened.
- **`dkim_verified`, `spf_verified`, `dmarc_verified`**: The result of the latest check for each record; also as `records[].status` (`pending` or `verified`).
- **`last_checked_at`**: When DNS was last checked; `null` before the first check.
- **`found` (verify only)**: What is published right now under each name, to compare with the expected value. At the root only SPF values are listed.
- **`warnings` (verify only)**: Problems that do not block verification, such as several SPF records.

> Once verified, a domain stays verified: a later check updates the per-record flags but does not take sending away. Keep the DKIM record published anyway; without it, receivers fail DKIM and DMARC on every message. A domain can be verified by one account at a time; verifying it elsewhere returns `409 conflict`.

## Check DNS now

`POST /v1/domains/{id}/verify`

Runs the same check as the automatic one and returns what was found under each name, plus warnings such as duplicate SPF records.

Requires a full-access live key; test keys get 403 test_key_restricted.

`found` shows, per DNS name, what is published right now. For the root domain only SPF-type TXT values are listed; a DMARC policy inherited from the parent domain is marked “(inherited from _dmarc.<domain>)”.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `conflict` (HTTP 409): this domain is already verified by another account

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/verify' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T14:02:11Z",
  "verified_at": "2026-10-21T14:02:11Z",
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ],
  "found": {
    "zap._domainkey.acme.com": [
      "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
    ],
    "acme.com": [
      "v=spf1 include:_spf.zapsmtp.xyz ~all"
    ]
  }
}
```

## List every domain and its status

`GET /v1/domains`

Newest first. Useful for a deploy check that every From domain your app uses is `verified`.

Requires a full-access key.

`status` is `pending` or `verified`. Only DKIM is required to verify a domain; SPF and DMARC are recommended and reported separately.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
      "name": "acme.com",
      "status": "verified",
      "dkim_selector": "zap",
      "dkim_verified": true,
      "spf_verified": true,
      "dmarc_verified": true,
      "open_tracking": false,
      "click_tracking": false,
      "from_name": "Acme",
      "tls": "opportunistic",
      "reply_tracking": false,
      "reply_domain": "",
      "reply_forward_to": "",
      "brand_updated_at": null,
      "last_checked_at": "2026-10-21T09:12:44Z",
      "verified_at": "2026-10-20T14:03:10Z",
      "created_at": "2026-10-20T13:58:02Z",
      "zone": "acme.com",
      "records": [
        {
          "record": "DKIM",
          "type": "TXT",
          "name": "zap._domainkey.acme.com",
          "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
          "required": true,
          "status": "verified"
        },
        {
          "record": "SPF",
          "type": "TXT",
          "name": "acme.com",
          "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
          "required": false,
          "status": "verified"
        },
        {
          "record": "DMARC",
          "type": "TXT",
          "name": "_dmarc.acme.com",
          "value": "v=DMARC1; p=none;",
          "required": false,
          "status": "verified"
        }
      ]
    }
  ]
}
```

## Checking records from a terminal

Each command should print exactly the value from the dashboard. An empty answer means the name is wrong or the record is not published yet; a doubled domain in the name is the most common cause. A DKIM value split into several quoted strings is normal.

**Look up the records**

macOS / Linux:

```
# DKIM (required)
dig +short TXT zap._domainkey.acme.com

# SPF: there must be exactly one line starting with "v=spf1"
dig +short TXT acme.com

# DMARC (for a subdomain, also check the parent: _dmarc.acme.com)
dig +short TXT _dmarc.acme.com

# Bypass your local cache: ask a public resolver...
dig +short TXT zap._domainkey.acme.com @1.1.1.1

# ...or the domain's own nameservers, which is what we do
dig +short NS acme.com
dig +short TXT zap._domainkey.acme.com @<one of the NS hosts above>
```

Windows (cmd):

```
nslookup -type=TXT zap._domainkey.acme.com
nslookup -type=TXT acme.com
nslookup -type=TXT _dmarc.acme.com

rem Ask a public resolver instead of the local one
nslookup -type=TXT zap._domainkey.acme.com 1.1.1.1

rem Find and query the authoritative nameservers
nslookup -type=NS acme.com
nslookup -type=TXT zap._domainkey.acme.com <one of the NS hosts above>
```

PowerShell:

```
Resolve-DnsName -Type TXT zap._domainkey.acme.com
Resolve-DnsName -Type TXT acme.com | Where-Object { $_.Strings -like 'v=spf1*' }
Resolve-DnsName -Type TXT _dmarc.acme.com
Resolve-DnsName -Type TXT zap._domainkey.acme.com -Server 1.1.1.1
```

## Troubleshooting

**Symptom → cause → fix**

- **DKIM stays pending; dig finds nothing**: The record is at `zap._domainkey.acme.com.acme.com` because the provider appended the domain. → Enter only `zap._domainkey` as the host.
- **DKIM pending; dig finds a different key**: The domain was deleted and added again (each add generates a new key), or a value was copied from another domain. → Copy the value from GET /domains/{id} again.
- **DKIM pending; the value looks cut off**: The provider truncated the key at 255 characters. → Enter it as several quoted strings in one record.
- **DKIM pending; value has stray quotes**: Quotes were pasted into a field that adds its own. → Paste the value without quotes.
- **Records are correct but nothing resolves**: They were added at a provider that is not authoritative (the registrar while nameservers point elsewhere). → Check `dig NS` and add them there.
- **Domain was added days ago and never verified**: Automatic checks stop 72 hours after the domain is added. → Fix the record, then call verify.
- **Warning “Multiple SPF records found” (SPF may still show verified)**: Two `v=spf1` records at the same name. Our check marks SPF verified when any of them contains our include, but receivers treat two records as a permanent error and fail SPF. → Merge them into one.
- **SPF pending with one record**: The include is missing or misspelt, or the record does not start with `v=spf1`. → Use `include:_spf.zapsmtp.xyz` exactly.
- **SPF permerror reported by receivers**: More than 10 DNS lookups. → Trim includes or use a subdomain.
- **DMARC pending**: No `_dmarc` record on the domain or its parent, or the value does not start with `v=DMARC1`. → Publish it at `_dmarc`.
- **`409` “already verified by another account”**: The same domain is verified in another ZapSMTP account (another team, a client account). → Remove it there, or send from that account.
- **`409` “domain already added”**: The domain is already in this account. → Use GET /domains to find its id.
- **`403 domain_not_verified` when sending**: A live key sending from a domain that is not verified in this account, or from a different name (a subdomain of a verified domain, for example). → Verify that exact domain; test keys accept any From domain.
- **`403 plan_limit_reached` when adding**: The plan’s domain limit. → Remove unused domains or upgrade.

## DMARC rollout and reports

Move to enforcement in steps, reading reports at each step, so you find every service that sends as your domain (CRM, help desk, billing) before receivers start rejecting its mail.

1. **`p=none`** with our report address. Watch for two to four weeks. Each IP in `sources` that fails and is not marked `ours` is either a service you have not set up with DKIM/SPF, or someone spoofing you.
2. **`p=quarantine`** once every legitimate source passes. Failing mail goes to spam. You can stage it with `pct` below 100, but BIMI requires `pct=100`.
3. **`p=reject`** when quarantine has run cleanly. Failing mail is refused outright.

**Reports.** Every domain gets its own report address, `mailto:dmarc-<token>@zapsmtp.xyz`, returned as `rua` by the DMARC endpoint. The endpoint’s `record` is a starter record with `p=none`; publish it only if you have no DMARC record yet. Otherwise add the address to your existing record’s `rua` tag and keep your policy, so an enforcing `p=quarantine` or `p=reject` is not downgraded; you can list it next to an address of your own. Mailbox providers send one aggregate report a day; we parse them and keep them for 400 days. The *DMARC reports* section of the domain page and the endpoint below show totals, a daily series, each sending IP and each reporting organisation.

**_dmarc records at each step**

1. Monitor:

```
_dmarc.acme.com.  TXT  "v=DMARC1; p=none; rua=mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz"
```

2. Quarantine:

```
_dmarc.acme.com.  TXT  "v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz"
```

3. Reject:

```
_dmarc.acme.com.  TXT  "v=DMARC1; p=reject; rua=mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz"
```

Two report addresses:

```
_dmarc.acme.com.  TXT  "v=DMARC1; p=none; rua=mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz,mailto:dmarc@acme.com"
```

## Read DMARC reports

`GET /v1/domains/{id}/dmarc`

Aggregate reports for the last `days` (1–180). `record` is a starter record (`p=none` plus our `rua`), not your current policy: if you already publish DMARC, add the `rua` address to your record instead; `sources` lists every IP that sent as your domain.

Requires a full-access key.

Add `rua` to your DMARC record (keep your policy). Providers send one report a day; reports are kept 400 days. `ours` marks ZapSMTP sending IPs: another IP that fails DMARC is a service you have not set up (add its DKIM/SPF) or someone spoofing your domain.

### Path parameters

- `id` (string): Domain id.

### Query parameters

- `days` (integer): 1-180; out-of-range falls back to 30. Default `30`.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): Not a domain of this account.

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/dmarc?days=90' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "dmarc_summary",
  "domain": "acme.com",
  "days": 30,
  "since": "2026-09-26T00:00:00Z",
  "rua": "mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz",
  "record": {
    "type": "TXT",
    "name": "_dmarc.acme.com",
    "value": "v=DMARC1; p=none; rua=mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz"
  },
  "reports": 42,
  "totals": {
    "messages": 18240,
    "passed": 18015,
    "dkim_passed": 18001,
    "spf_passed": 17890,
    "quarantined": 190,
    "rejected": 35
  },
  "sources": [
    {
      "ip": "192.0.2.10",
      "messages": 18000,
      "passed": 17990,
      "dkim_passed": 17985,
      "spf_passed": 17880,
      "quarantined": 10,
      "rejected": 0,
      "reporters": [
        "Yahoo",
        "google.com"
      ],
      "ours": true
    },
    {
      "ip": "203.0.113.5",
      "messages": 240,
      "passed": 25,
      "dkim_passed": 16,
      "spf_passed": 10,
      "quarantined": 180,
      "rejected": 35,
      "reporters": [
        "google.com"
      ],
      "ours": false
    }
  ],
  "reporters": [
    {
      "org": "google.com",
      "reports": 30,
      "messages": 15400
    },
    {
      "org": "Yahoo",
      "reports": 12,
      "messages": 2840
    }
  ],
  "series": [
    {
      "day": "2026-10-24T00:00:00Z",
      "messages": 640,
      "passed": 632,
      "dkim_passed": 632,
      "spf_passed": 628,
      "quarantined": 6,
      "rejected": 2
    }
  ]
}
```

## Brand in the inbox (BIMI)

BIMI shows your logo next to your messages in Gmail, Apple Mail, Yahoo and others. ZapSMTP hosts the logo and certificate and tells you exactly what is missing. Requirements:

- The domain verified, so every message is DKIM-signed.
- DMARC at enforcement: `p=quarantine` or `p=reject` with `pct=100`, on the domain or its parent (for a subdomain, the parent’s `sp=` applies if set).
- A square SVG logo, at most 32 KB, without scripts, raster images, links or animation. On upload we convert it to the SVG Tiny PS profile (size at least 96 px, title, no x/y on the root) and report each fix; a solid background is recommended.
- A TXT record at `default._bimi.<domain>`, given to you as `bimi_record`, pointing at the hosted logo, e.g. `v=BIMI1; l=https://zapsmtp.xyz/bimi/acme.com/logo.svg; a=;`.
- For Gmail and Apple Mail, a Verified Mark Certificate (VMC, needs a registered trademark, adds the blue check mark) or a Common Mark Certificate (CMC), uploaded as a PEM chain: certificate, intermediate, root. Yahoo shows the logo without one.

Upload the logo and certificate in the domain’s *Brand in the inbox* section or with `logo_svg` and `cert_pem` on PUT /domains/{id}/brand; when a certificate is added the `a=` tag of the record changes, so update it in DNS. Providers may take up to 48 hours to show the logo. The same endpoint sets the default sender name.

## Check brand readiness

`GET /v1/domains/{id}/brand`

Every BIMI prerequisite as a checklist, the record to publish and readiness per mailbox provider.

Requires a full-access key.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): domain not found

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/brand' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "from_name": "Acme",
  "logo_url": "https://zapsmtp.xyz/bimi/acme.com/logo.svg",
  "cert_url": "",
  "has_logo": true,
  "has_cert": false,
  "bimi_record": {
    "record": "BIMI",
    "type": "TXT",
    "name": "default._bimi.acme.com",
    "value": "v=BIMI1; l=https://zapsmtp.xyz/bimi/acme.com/logo.svg; a=;",
    "required": false,
    "status": "verified"
  },
  "dmarc_record": {
    "record": "DMARC",
    "type": "TXT",
    "name": "_dmarc.acme.com",
    "value": "v=DMARC1; p=quarantine; pct=100;",
    "required": false,
    "status": "verified"
  },
  "dmarc": {
    "record": "v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc@acme.com",
    "domain": "acme.com",
    "p": "quarantine",
    "sp": "",
    "pct": 100,
    "enforced": true
  },
  "published_bimi": "v=BIMI1; l=https://zapsmtp.xyz/bimi/acme.com/logo.svg; a=;",
  "checks": [
    {
      "id": "auth",
      "label": "SPF, DKIM and DMARC pass",
      "ok": true,
      "detail": "Domain verified; ZapSMTP signs every message with DKIM."
    },
    {
      "id": "dmarc",
      "label": "DMARC at enforcement",
      "ok": true,
      "detail": "Found on acme.com: v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc@acme.com"
    },
    {
      "id": "logo",
      "label": "Logo in SVG Tiny PS, hosted over HTTPS",
      "ok": true,
      "detail": "Square, ≤ 32 KB, solid background. Upload it below; we fix the profile automatically."
    },
    {
      "id": "bimi",
      "label": "BIMI record published",
      "ok": true,
      "detail": "default._bimi.acme.com points to the hosted logo. Mailbox providers may take up to 48 hours to show it."
    },
    {
      "id": "cert",
      "label": "Verified Mark Certificate (VMC) or Common Mark Certificate (CMC)",
      "ok": false,
      "detail": "Required by Gmail and Apple Mail (Gmail does not support a standalone SVG). VMC needs a registered trademark and adds the blue checkmark. Upload the PEM chain in order: certificate, intermediate, root."
    },
    {
      "id": "name",
      "label": "Sender name",
      "ok": true,
      "detail": "Used when an email's from has no display name, e.g. hello@ → \"Acme <hello@…>\"."
    }
  ],
  "providers": {
    "gmail": "needs_certificate",
    "apple": "needs_certificate",
    "yahoo": "ready"
  }
}
```

## Set a default sender name

`PUT /v1/domains/{id}/brand`

Used when an email’s `from` is a bare address: `hello@acme.com` goes out as `Acme <hello@acme.com>`.

Requires a full-access live key; test keys get 403 test_key_restricted.

Hosted files are served publicly at /bimi/<domain>/logo.svg and /bimi/<domain>/cert.pem (outside /v1) for verified domains only.

### Path parameters

- `id` (string, required): Domain id

### Body parameters

- `from_name` (string): Display name used when an email's from has only an address. "" clears it. Limits: max 70 characters, no < > " or line breaks → 422 invalid_parameter
- `logo_svg` (string): SVG source; normalized to SVG Tiny PS (fixes reported in logo_fixed, warnings in logo_warnings). Limits: max 32 KB and valid SVG → otherwise 422 invalid_logo
- `cert_pem` (string): VMC/CMC PEM chain (certificate, intermediate, root). Limits: 422 invalid_certificate
- `remove_logo` (boolean): Default `False`.
- `remove_cert` (boolean): Default `False`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `invalid_certificate` (HTTP 422)
- `invalid_logo` (HTTP 422)
- `invalid_parameter` (HTTP 422)

```bash
curl -X PUT 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/brand' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from_name": "Acme"
}'
```

**Response `200 OK`**

```json
{
  "from_name": "Acme",
  "logo_url": "https://zapsmtp.xyz/bimi/acme.com/logo.svg",
  "cert_url": "",
  "has_logo": true,
  "has_cert": false,
  "bimi_record": {
    "record": "BIMI",
    "type": "TXT",
    "name": "default._bimi.acme.com",
    "value": "v=BIMI1; l=https://zapsmtp.xyz/bimi/acme.com/logo.svg; a=;",
    "required": false,
    "status": "verified"
  },
  "dmarc_record": {
    "record": "DMARC",
    "type": "TXT",
    "name": "_dmarc.acme.com",
    "value": "v=DMARC1; p=quarantine; pct=100;",
    "required": false,
    "status": "verified"
  },
  "dmarc": {
    "record": "v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc@acme.com",
    "domain": "acme.com",
    "p": "quarantine",
    "sp": "",
    "pct": 100,
    "enforced": true
  },
  "published_bimi": "v=BIMI1; l=https://zapsmtp.xyz/bimi/acme.com/logo.svg; a=;",
  "checks": [
    {
      "id": "auth",
      "label": "SPF, DKIM and DMARC pass",
      "ok": true,
      "detail": "Domain verified; ZapSMTP signs every message with DKIM."
    },
    {
      "id": "dmarc",
      "label": "DMARC at enforcement",
      "ok": true,
      "detail": "Found on acme.com: v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc@acme.com"
    },
    {
      "id": "logo",
      "label": "Logo in SVG Tiny PS, hosted over HTTPS",
      "ok": true,
      "detail": "Square, ≤ 32 KB, solid background. Upload it below; we fix the profile automatically."
    },
    {
      "id": "bimi",
      "label": "BIMI record published",
      "ok": true,
      "detail": "default._bimi.acme.com points to the hosted logo. Mailbox providers may take up to 48 hours to show it."
    },
    {
      "id": "cert",
      "label": "Verified Mark Certificate (VMC) or Common Mark Certificate (CMC)",
      "ok": false,
      "detail": "Required by Gmail and Apple Mail (Gmail does not support a standalone SVG). VMC needs a registered trademark and adds the blue checkmark. Upload the PEM chain in order: certificate, intermediate, root."
    },
    {
      "id": "name",
      "label": "Sender name",
      "ok": true,
      "detail": "Used when an email's from has no display name, e.g. hello@ → \"Acme <hello@…>\"."
    }
  ],
  "providers": {
    "gmail": "needs_certificate",
    "apple": "needs_certificate",
    "yahoo": "ready"
  }
}
```

## Tracking, TLS and replies per domain

Each domain carries sending defaults, set on its page in the dashboard or with `PATCH /domains/{id}`:

**Domain settings**

- **`open_tracking`, `click_tracking`**: Off by default. Opens use a pixel and clicks are rewritten through ZapSMTP’s link host (`https://zapsmtp.xyz`); no DNS record is needed on your side. Custom tracking domains are not available. A single email overrides the defaults with `tracking: {opens, clicks}`.
- **`tls`**: `opportunistic` (default: STARTTLS whenever the receiver offers it), `required` (no TLS, no delivery) or `verified` (TLS with a valid certificate for the MX host). Receivers that publish MTA-STS or DANE are always reached over a verified connection. An email’s own `tls` can raise the level, never lower it.
- **`reply_tracking`, `reply_domain`, `reply_forward_to`**: Ties replies to the exact email that was answered. Needs an [inbound domain](https://www.zapsmtp.xyz/docs/inbound/) such as `reply.acme.com` with a verified MX record first.

## Turn on open and click tracking

`PATCH /v1/domains/{id}`

Defaults for every email from this domain. A single email can still override them with `tracking`.

Requires a full-access live key; test keys get 403 test_key_restricted.

Fields left out keep their value. The response is the domain, as in `GET /domains/{id}`.

Reply tracking: each tracked email gets its own signed Reply-To, e.g. `r1-<email id>.<signature>@reply.acme.com`, so replies come back tied to the exact email. Each reply fires `email.replied` (classified as a person, out-of-office, unsubscribe request, bounce…) and arrives as a received email; only replies a person wrote are forwarded. The display name is kept (the Reply-To’s name, else the From name). One reply address takes at most 100 replies a day.

### Path parameters

- `id` (string, required): Domain id

### Body parameters

- `open_tracking` (boolean): Default open tracking for emails from this domain.
- `click_tracking` (boolean): Default click tracking for emails from this domain.
- `tls` (string): Outbound encryption: `opportunistic` (default: encrypt whenever offered), `required` (TLS or no delivery) or `verified` (TLS with a valid certificate). Limits: other values → 422 invalid_parameter "tls must be opportunistic, required or verified"
- `reply_tracking` (boolean): Default reply tracking for emails from this domain (override per email with `tracking.replies`). Limits: true without a reply_domain → 422 invalid_parameter "reply_tracking needs a reply_domain: add an inbound domain such as reply.<domain> first"
- `reply_domain` (string): Where tracked reply addresses live: one of your inbound domains, MX-verified, equal to this domain or a subdomain of it (e.g. `reply.acme.com`). `""` clears it. Limits: otherwise 422 invalid_parameter
- `reply_forward_to` (string): Where replies a person wrote are forwarded: a plain address on one of your verified domains, or a confirmed forward destination; never a receiving address. `""` (default) forwards to the email’s first Reply-To, else its From. Limits: otherwise 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `invalid_parameter` (HTTP 422): bad tls; reply_domain not one of your inbound domains, not this domain or a subdomain of it, or without a verified MX record; reply_forward_to not a plain address, a receiving address, or not on a verified domain / confirmed forward destination; reply_tracking without a reply_domain

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "open_tracking": true,
  "click_tracking": true
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": true,
  "open_tracking": true,
  "click_tracking": true,
  "from_name": "Acme",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T09:12:44Z",
  "verified_at": "2026-10-20T14:03:10Z",
  "created_at": "2026-10-20T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "verified"
    }
  ]
}
```

## Require TLS for outgoing mail

`PATCH /v1/domains/{id}`

With `required`, a receiver that cannot do STARTTLS does not get the email; `verified` also demands a valid certificate for its MX host.

Requires a full-access live key; test keys get 403 test_key_restricted.

Fields left out keep their value. The response is the domain, as in `GET /domains/{id}`.

Reply tracking: each tracked email gets its own signed Reply-To, e.g. `r1-<email id>.<signature>@reply.acme.com`, so replies come back tied to the exact email. Each reply fires `email.replied` (classified as a person, out-of-office, unsubscribe request, bounce…) and arrives as a received email; only replies a person wrote are forwarded. The display name is kept (the Reply-To’s name, else the From name). One reply address takes at most 100 replies a day.

### Path parameters

- `id` (string, required): Domain id

### Body parameters

- `open_tracking` (boolean): Default open tracking for emails from this domain.
- `click_tracking` (boolean): Default click tracking for emails from this domain.
- `tls` (string): Outbound encryption: `opportunistic` (default: encrypt whenever offered), `required` (TLS or no delivery) or `verified` (TLS with a valid certificate). Limits: other values → 422 invalid_parameter "tls must be opportunistic, required or verified"
- `reply_tracking` (boolean): Default reply tracking for emails from this domain (override per email with `tracking.replies`). Limits: true without a reply_domain → 422 invalid_parameter "reply_tracking needs a reply_domain: add an inbound domain such as reply.<domain> first"
- `reply_domain` (string): Where tracked reply addresses live: one of your inbound domains, MX-verified, equal to this domain or a subdomain of it (e.g. `reply.acme.com`). `""` clears it. Limits: otherwise 422 invalid_parameter
- `reply_forward_to` (string): Where replies a person wrote are forwarded: a plain address on one of your verified domains, or a confirmed forward destination; never a receiving address. `""` (default) forwards to the email’s first Reply-To, else its From. Limits: otherwise 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `invalid_parameter` (HTTP 422): bad tls; reply_domain not one of your inbound domains, not this domain or a subdomain of it, or without a verified MX record; reply_forward_to not a plain address, a receiving address, or not on a verified domain / confirmed forward destination; reply_tracking without a reply_domain

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "tls": "required"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": true,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "Acme",
  "tls": "required",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T09:12:44Z",
  "verified_at": "2026-10-20T14:03:10Z",
  "created_at": "2026-10-20T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "verified"
    }
  ]
}
```

## Route replies through a reply domain

`PATCH /v1/domains/{id}`

Optional. Each tracked email gets its own signed Reply-To on the reply domain. `reply_domain` must be one of your inbound domains, MX-verified, and equal to or a subdomain of the sending domain; `reply_forward_to` is where human replies go.

Requires a full-access live key; test keys get 403 test_key_restricted.

Fields left out keep their value. The response is the domain, as in `GET /domains/{id}`.

Reply tracking: each tracked email gets its own signed Reply-To, e.g. `r1-<email id>.<signature>@reply.acme.com`, so replies come back tied to the exact email. Each reply fires `email.replied` (classified as a person, out-of-office, unsubscribe request, bounce…) and arrives as a received email; only replies a person wrote are forwarded. The display name is kept (the Reply-To’s name, else the From name). One reply address takes at most 100 replies a day.

### Path parameters

- `id` (string, required): Domain id

### Body parameters

- `open_tracking` (boolean): Default open tracking for emails from this domain.
- `click_tracking` (boolean): Default click tracking for emails from this domain.
- `tls` (string): Outbound encryption: `opportunistic` (default: encrypt whenever offered), `required` (TLS or no delivery) or `verified` (TLS with a valid certificate). Limits: other values → 422 invalid_parameter "tls must be opportunistic, required or verified"
- `reply_tracking` (boolean): Default reply tracking for emails from this domain (override per email with `tracking.replies`). Limits: true without a reply_domain → 422 invalid_parameter "reply_tracking needs a reply_domain: add an inbound domain such as reply.<domain> first"
- `reply_domain` (string): Where tracked reply addresses live: one of your inbound domains, MX-verified, equal to this domain or a subdomain of it (e.g. `reply.acme.com`). `""` clears it. Limits: otherwise 422 invalid_parameter
- `reply_forward_to` (string): Where replies a person wrote are forwarded: a plain address on one of your verified domains, or a confirmed forward destination; never a receiving address. `""` (default) forwards to the email’s first Reply-To, else its From. Limits: otherwise 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `invalid_parameter` (HTTP 422): bad tls; reply_domain not one of your inbound domains, not this domain or a subdomain of it, or without a verified MX record; reply_forward_to not a plain address, a receiving address, or not on a verified domain / confirmed forward destination; reply_tracking without a reply_domain

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "reply_tracking": true,
  "reply_domain": "reply.acme.com",
  "reply_forward_to": "support@acme.com"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": true,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "Acme",
  "tls": "opportunistic",
  "reply_tracking": true,
  "reply_domain": "reply.acme.com",
  "reply_forward_to": "support@acme.com",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T09:12:44Z",
  "verified_at": "2026-10-20T14:03:10Z",
  "created_at": "2026-10-20T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "verified"
    }
  ]
}
```

## Reputation and blocklists

Verified sending domains are checked against the Spamhaus DBL, SURBL and URIBL every 6 hours. Each list’s latest result, with the date a listing started and a link to the list’s removal page, is on the domain’s page and in the reputation endpoint, with a history of listings and delistings. A failed lookup is shown as an error, never as clean. After requesting removal, run a check on demand.

## Read blocklist status

`GET /v1/domains/{id}/reputation`

The latest result for each domain blocklist and a history of listings and delistings.

Requires a full-access key.

Customer domains are checked automatically every 6 hours (operator-configurable). The exact JSON for codes/labels when empty (null vs []) depends on the stored arrays; not verified.

### Path parameters

- `id` (string (UUID), required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): domain not found

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/reputation' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "domain_reputation",
  "domain": "acme.com",
  "worst": "",
  "lists": [
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "spamhaus-dbl",
      "name": "Spamhaus DBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://check.spamhaus.org/"
    },
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "surbl",
      "name": "SURBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://www.surbl.org/surbl-analysis"
    },
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "uribl",
      "name": "URIBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://admin.uribl.com/"
    }
  ],
  "events": [
    {
      "id": "019a1e00-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "target": "acme.com",
      "kind": "domain",
      "list": "uribl",
      "name": "URIBL",
      "event": "delisted",
      "severity": null,
      "codes": [],
      "detail": "",
      "at": "2026-10-19T06:00:02Z"
    }
  ]
}
```

## Re-check blocklists now

`POST /v1/domains/{id}/reputation/check`

After a delisting request, check again without waiting for the next scheduled run. At most once a minute per domain. Returns the same body as the reputation read.

Requires a full-access live key; test keys get 403 test_key_restricted.

At most once per minute per domain name. No Retry-After header is set.

### Path parameters

- `id` (string (UUID), required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `rate_limit_exceeded` (HTTP 429): this domain was checked less than a minute ago

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/reputation/check' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "domain_reputation",
  "domain": "acme.com",
  "worst": "",
  "lists": [
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "spamhaus-dbl",
      "name": "Spamhaus DBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://check.spamhaus.org/"
    },
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "surbl",
      "name": "SURBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://www.surbl.org/surbl-analysis"
    },
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "uribl",
      "name": "URIBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://admin.uribl.com/"
    }
  ],
  "events": [
    {
      "id": "019a1e00-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "target": "acme.com",
      "kind": "domain",
      "list": "uribl",
      "name": "URIBL",
      "event": "delisted",
      "severity": null,
      "codes": [],
      "detail": "",
      "at": "2026-10-19T06:00:02Z"
    }
  ]
}
```

## Removing a domain

Deleting a domain removes it and its DKIM private key at once. Live sends from it are refused with `domain_not_verified` from then on, so switch your From address first. Then remove `zap._domainkey` and our include from your SPF record; leave DMARC in place if other services send as the domain. Adding the domain again later generates a new key, so the old DKIM record will not match.

## Remove a domain

`DELETE /v1/domains/{id}`

Deletes the domain and its DKIM key. Live sends from it fail with `domain_not_verified` from then on.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `204` with an empty body.

---

# Templates and variables

Source: https://www.zapsmtp.xyz/docs/templating/

Store the subject, HTML and plain text of an email once, then send it with a template id and a JSON object of variables. Templates use logic-less Mustache, the same syntax as Postmark, Mailgun and MailerSend templates: no code runs, so it is safe for any input.

> This guide is for developers working through the API. To design templates visually, write HTML with a live preview or browse the gallery, see the [Email template editor](https://www.zapsmtp.xyz/docs/template-editor/). Both edit the same templates.

## Syntax at a glance

Subject, HTML and text are each a template. Spaces inside a tag are ignored: `{{ name }}` equals `{{name}}`.

**Tags**

- **`{{name}}`**: Value of `name`. HTML-escaped in the HTML body; inserted as is in the subject and the text body.
- **`{{{name}}}`**: Raw value, never escaped. `{{& name}}` is the same.
- **`{{user.first_name}}`**: Dotted name: walks into nested objects.
- **`{{#name}}…{{/name}}`**: Section. A list repeats the block once per item; an object or any other truthy value renders it once with that value as context; a falsy or absent value skips it.
- **`{{^name}}…{{/name}}`**: Inverted section: renders only when the value is falsy, an empty list, or absent.
- **`{{.}}`**: The current item, for lists of strings or numbers.
- **`{{! note }}`**: Comment, removed from the output.
- **`{{{zap:unsubscribe_url}}}`**: Filled in at send time with the recipient’s unsubscribe link. Never a missing variable.
- **`{{global.key}}`**: One of the account’s global variables, such as `{{global.company_name}}`.

There is nothing else: no partials (`{{> footer}}`), no helpers or filters, no expressions, no custom delimiters. Saving a template checks every tag: one that is not a variable name, such as `{{first name}}`, `{{#each items}}` or `{{> footer}}`, is refused with `422 template_render_error` *html: line L, column C: {{…}} is not a variable name: letters, digits, _ and - (no spaces), parts joined with dots*. Anything you would compute, such as a formatted price, a plural or a date in the reader’s time zone, is computed in your code and passed as a variable.

## Escaping

In the HTML body, `{{x}}` escapes `< > & ' "`, so text from your users cannot inject markup. Use `{{{x}}}` only for HTML you produced yourself. The subject and the text body are not HTML, so nothing is escaped there.

**Escaped and raw**

HTML template:

```
<p>Hi {{name}}, your note: {{note}}</p>
<p>{{{signature_html}}}</p>
```

Variables:

```json
{
  "name": "Ann & \"Bob\"",
  "note": "<b>it's urgent</b>",
  "signature_html": "<em>The Acme team</em>"
}
```

HTML output:

```
<p>Hi Ann &amp; &#34;Bob&#34;, your note: &lt;b&gt;it&#39;s urgent&lt;/b&gt;</p>
<p><em>The Acme team</em></p>
```

Text output:

```
Hi Ann & "Bob", your note: <b>it's urgent</b>
```

## How values print

Variables are JSON. Strings print as they are; numbers print in their shortest form, so `19.90` becomes `19.9`. Pass money, dates and anything with a fixed format as strings.

**JSON value → output and truthiness**

- **Value**: **Prints as** · **In a section**
- **`"Ann"`**: Ann · true unless ""
- **`19.90`**: 19.9 · true unless 0
- **`2`**: 2 · true unless 0
- **`true / false`**: true / false · as is
- **`null`**: (empty) · false
- **`[…]`**: not useful: use a section · true unless []
- **`{…}`**: not useful: use a section or a dotted name · always true, even {}

**Numbers and booleans**

Template:

```
Price {{price}}, qty {{qty}}, paid {{paid}}
```

Variables:

```json
{
  "price": 19.9,
  "qty": 2,
  "paid": true
}
```

Output:

```
Price 19.9, qty 2, paid true
```

## Dotted names and context

`{{customer.address.city}}` walks into nested objects. Inside a section the current item is searched first, then each enclosing context out to the top-level variables, so a list item can use values defined outside the list, such as a currency.

**Nested objects**

Template:

```json
{{#shipping}}<p>{{name}}<br>{{address.line1}}<br>{{address.postcode}} {{address.city}}</p>{{/shipping}}
{{#items}}<p>{{name}}: {{price}} {{currency}}</p>{{/items}}
```

Variables:

```json
{
  "currency": "EUR",
  "shipping": {
    "name": "Ann Lee",
    "address": {
      "line1": "Rua Augusta 10",
      "postcode": "1100-053",
      "city": "Lisbon"
    }
  },
  "items": [
    {
      "name": "Grinder",
      "price": "89.00"
    }
  ]
}
```

Output:

```
<p>Ann Lee<br>Rua Augusta 10<br>1100-053 Lisbon</p>
<p>Grinder: 89.00 EUR</p>
```

Inside `{{#items}}`, `{{name}}` is the item’s name. If an item lacked `name`, the outer `shipping.name` would not be used (it is nested), but a top-level `name` would. Give every item every field it uses.

## Sections: lists, objects, conditions

What a section does depends on its value: a non-empty list repeats the block per item; an object renders it once with the object as context (so `{{code}}` means `coupon.code`); `true`, a non-empty string or a non-zero number renders it once. For a list of plain values, `{{.}}` is the item.

**List of strings and a string condition**

Template:

```
Tags: {{#labels}}{{.}}; {{/labels}}
{{#greeting}}<p>{{.}}</p>{{/greeting}}
```

Variables:

```json
{
  "labels": [
    "billing",
    "urgent"
  ],
  "greeting": "Welcome back!"
}
```

Output:

```
Tags: billing; urgent;
<p>Welcome back!</p>
```

Sections nest up to 32 levels. A render stops with an error when the output would pass 10 MB or the work grows past a fixed bound, Every tag visited and every list item counts towards that bound, so it is reached by lists nested inside each other, and also by one long flat list: the bound is about a million steps, one per list item plus one per tag or text run rendered.

## Inverted sections and empty states

`{{^x}}…{{/x}}` renders when `x` is `false`, `null`, `""`, `0`, `[]` or absent. Pair it with a section for if/else.

**Empty cart**

Template:

```json
{{#items}}<li>{{name}}</li>{{/items}}{{^items}}<p>Your cart is empty. <a href="{{shop_url}}">Keep shopping</a></p>{{/items}}
```

Variables:

```json
{
  "items": [],
  "shop_url": "https://acme.com/shop"
}
```

Output:

```
<p>Your cart is empty. <a href="https://acme.com/shop">Keep shopping</a></p>
```

**Zero as the else branch**

Template:

```json
{{#count}}You have {{count}} new messages.{{/count}}{{^count}}No new messages.{{/count}}
```

Variables (count 0):

```json
{
  "count": 0
}
```

Output:

```
No new messages.
```

## Line breaks around tags

Text outside tags is copied exactly, including the line break after a section tag that sits on its own line. In HTML that is invisible; in the plain-text body it adds blank lines. Put the opening tag at the start of the repeated line and the closing tag right after its line break.

**Plain-text list**

Tags on their own lines:

```
Your order {{order_id}}:
{{#items}}
- {{quantity}} x {{name}}: {{price}}
{{/items}}
Total: {{total}}
```

Output:

```
Your order A-1042:

- 2 x Coffee beans: $24.00

- 1 x Grinder: $89.00

Total: $113.00
```

Tight tags:

```
Your order {{order_id}}:
{{#items}}- {{quantity}} x {{name}}: {{price}}
{{/items}}Total: {{total}}
```

Tight output:

```
Your order A-1042:
- 2 x Coffee beans: $24.00
- 1 x Grinder: $89.00
Total: $113.00
```

## Missing variables: preview vs send

A variable is missing when `{{x}}` or `{{{x}}}` names something absent from the variables (for dotted names, any step of the path). The two paths treat it differently:

**Missing variables**

- **Preview**: `POST /templates/render` and `POST /templates/{id}/render` render it as empty text and list it in `missing_variables`, e.g. `plan.name`.
- **Send**: `POST /emails` and batches first apply the published variable schema: defaults fill gaps, optional variables without a default render empty, and a required one still missing is refused with `422 template_variables_missing`. Anything the template renders that is still absent then fails with `422 template_render_error` *missing template variables: …*. A half-filled email never goes out.
- **Not missing**: A section or inverted section whose name is absent: it counts as false, so section conditions may be omitted. Variables inside a section that is skipped are never evaluated, so they are not required either. Also any `zap:` tag, and a variable set to `null` or `""`. Send `null` to deliberately leave a value empty.

## See what is missing

`POST /v1/templates/render`

A preview never fails on missing variables: they render as empty text and are listed in `missing_variables`. A send with the same variables is refused.

Requires a full-access key.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/render' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "subject": "Hi {{first_name}}",
  "text": "Hi {{first_name}} {{last_name}}, your plan: {{plan.name}}",
  "variables": {
    "first_name": "Ann",
    "plan": {}
  }
}'
```

**Response `200 OK`**

```json
{
  "subject": "Hi Ann",
  "html": "",
  "text": "Hi Ann , your plan: ",
  "missing_variables": [
    "last_name",
    "plan.name"
  ],
  "variable_names": [
    "first_name",
    "last_name",
    "plan"
  ]
}
```

`variable_names` in responses lists the names used at the top level, section names included, and only the first part of a dotted name (`customer` for `{{customer.first_name}}`). Names used only inside a section are not listed.

## Unsubscribe links

`{{{zap:unsubscribe_url}}}` (or `{{zap:unsubscribe_url}}`) passes through rendering untouched and is replaced at send time with a signed one-click unsubscribe link for the recipient, in the HTML and the text body. It works in any email, templated or not, and is never wrapped by click tracking. When an email has several recipients, the link belongs to the first one, so send marketing mail one recipient per email. Broadcast-stream mail to a single recipient also gets `List-Unsubscribe` headers automatically unless you set your own.

**Footer**

Template:

```
<p>{{! shown in every newsletter }}You get this because you subscribed to {{list_name}}.
<a href="{{{zap:unsubscribe_url}}}">Unsubscribe</a></p>
```

After rendering:

```
<p>You get this because you subscribed to Acme news.
<a href="{{{zap:unsubscribe_url}}}">Unsubscribe</a></p>
```

As delivered:

```
<p>You get this because you subscribed to Acme news.
<a href="(signed link for this recipient)">Unsubscribe</a></p>
```

## Worked examples

## Order receipt with line items

The receipt used in the rest of this guide: a nested customer object, a loop over line items with prices passed as strings, and an optional coupon. Note the tight section tags, so the text body has no stray blank lines.

**Receipt**

HTML:

```html
<p>Hi {{customer.first_name}},</p>
<p>Thanks for order {{order_id}}.</p>
<table>
{{#items}}<tr><td>{{quantity}} × {{name}}</td><td>{{price}}</td></tr>
{{/items}}</table>
<p>Total: <strong>{{total}}</strong></p>
{{#coupon}}<p>Use <strong>{{code}}</strong> for {{percent}}% off your next order.</p>
{{/coupon}}
```

Text:

```
Hi {{customer.first_name}},

Thanks for order {{order_id}}.
{{#items}}- {{quantity}} x {{name}}: {{price}}
{{/items}}Total: {{total}}
{{#coupon}}
Use {{code}} for {{percent}}% off your next order.
{{/coupon}}
```

Variables:

```json
{
  "order_id": "A-1042",
  "customer": {
    "first_name": "Ann"
  },
  "items": [
    {
      "name": "Coffee beans",
      "quantity": 2,
      "price": "$24.00"
    },
    {
      "name": "Grinder",
      "quantity": 1,
      "price": "$89.00"
    }
  ],
  "total": "$113.00",
  "coupon": {
    "code": "THANKS15",
    "percent": 15
  }
}
```

HTML output:

```
<p>Hi Ann,</p>
<p>Thanks for order A-1042.</p>
<table>
<tr><td>2 × Coffee beans</td><td>$24.00</td></tr>
<tr><td>1 × Grinder</td><td>$89.00</td></tr>
</table>
<p>Total: <strong>$113.00</strong></p>
<p>Use <strong>THANKS15</strong> for 15% off your next order.</p>
```

Text output:

```
Hi Ann,

Thanks for order A-1042.
- 2 x Coffee beans: $24.00
- 1 x Grinder: $89.00
Total: $113.00

Use THANKS15 for 15% off your next order.
```

## Preview unsaved source

`POST /v1/templates/render`

Render subject, HTML and text with variables before saving anything. Syntax errors come back as `template_render_error`; missing variables are listed, not fatal. Reference: [Render unsaved source](https://www.zapsmtp.xyz/docs/templates/render-source/).

Requires a full-access key.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/render' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "subject": "Your Acme receipt {{order_id}}",
  "html": "<p>Hi {{customer.first_name}},</p>\n<p>Thanks for order {{order_id}}.</p>\n<table>\n{{#items}}<tr><td>{{quantity}} × {{name}}</td><td>{{price}}</td></tr>\n{{/items}}</table>\n<p>Total: <strong>{{total}}</strong></p>\n{{#coupon}}<p>Use <strong>{{code}}</strong> for {{percent}}% off your next order.</p>\n{{/coupon}}",
  "text": "Hi {{customer.first_name}},\n\nThanks for order {{order_id}}.\n{{#items}}- {{quantity}} x {{name}}: {{price}}\n{{/items}}Total: {{total}}\n{{#coupon}}\nUse {{code}} for {{percent}}% off your next order.\n{{/coupon}}",
  "variables": {
    "order_id": "A-1042",
    "customer": {
      "first_name": "Ann"
    },
    "items": [
      {
        "name": "Coffee beans",
        "quantity": 2,
        "price": "$24.00"
      },
      {
        "name": "Grinder",
        "quantity": 1,
        "price": "$89.00"
      }
    ],
    "total": "$113.00",
    "coupon": {
      "code": "THANKS15",
      "percent": 15
    }
  }
}'
```

**Response `200 OK`**

```json
{
  "subject": "Your Acme receipt A-1042",
  "html": "<p>Hi Ann,</p>\n<p>Thanks for order A-1042.</p>\n<table>\n<tr><td>2 × Coffee beans</td><td>$24.00</td></tr>\n<tr><td>1 × Grinder</td><td>$89.00</td></tr>\n</table>\n<p>Total: <strong>$113.00</strong></p>\n<p>Use <strong>THANKS15</strong> for 15% off your next order.</p>\n",
  "text": "Hi Ann,\n\nThanks for order A-1042.\n- 2 x Coffee beans: $24.00\n- 1 x Grinder: $89.00\nTotal: $113.00\n\nUse THANKS15 for 15% off your next order.\n",
  "missing_variables": [],
  "variable_names": [
    "coupon",
    "customer",
    "items",
    "order_id",
    "total"
  ]
}
```

## Conditional coupon block

An object is a condition and a context at once: when `coupon` is an object, the block renders with its fields; when it is `null`, `false` or absent, the block disappears and no variable is reported missing.

**Coupon**

Template:

```
<p>Thanks for your order.</p>{{#coupon}}<p>Use <strong>{{code}}</strong> for {{percent}}% off your next order.</p>{{/coupon}}
```

With coupon:

```json
{"coupon":{"code":"THANKS15","percent":15}}
```

Output with coupon:

```
<p>Thanks for your order.</p><p>Use <strong>THANKS15</strong> for 15% off your next order.</p>
```

Without coupon:

```json
{"coupon":null}
```

Output without coupon:

```
<p>Thanks for your order.</p>
```

> An empty object `{}` is still true and renders the block with empty fields. Send `null`, not `{}`, when there is no coupon.

## Plurals

There are no helpers, so decide the form in your code and pass a boolean. This works for any language’s plural rules: pass one flag per form you need.

**One or many**

Template:

```
You have {{count}} {{#one}}message{{/one}}{{^one}}messages{{/one}}.
```

Variables:

```json
{"count": 1, "one": true}
{"count": 3, "one": false}
```

Output:

```
You have 1 message.
You have 3 messages.
```

Your code (JS):

```
const count = inbox.unread;
const variables = {count, one: count === 1};
```

## One template per language

Keep one template per locale with the same variables and aliases such as `receipt`, `receipt-de`, `receipt-fr`. Your code picks the alias; the variables stay the same.

## Add a translation

`POST /v1/templates`

One template per language, same variables, aliases that share a prefix. Needs a full-access *live* key: test keys get `403 test_key_restricted`.

Requires a full-access live key; test keys get 403 test_key_restricted.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Receipt (de)",
  "alias": "receipt-de",
  "from": "Acme <billing@acme.com>",
  "subject": "Ihre Acme-Rechnung {{order_id}}",
  "text": "Hallo {{customer.first_name}},\n\nvielen Dank für Ihre Bestellung {{order_id}}.\n{{#items}}- {{quantity}} x {{name}}: {{price}}\n{{/items}}Summe: {{total}}\n",
  "variables": {
    "order_id": "A-1042",
    "customer": {
      "first_name": "Ann"
    },
    "items": [
      {
        "name": "Coffee beans",
        "quantity": 2,
        "price": "$24.00"
      },
      {
        "name": "Grinder",
        "quantity": 1,
        "price": "$89.00"
      }
    ],
    "total": "$113.00",
    "coupon": {
      "code": "THANKS15",
      "percent": 15
    }
  },
  "variable_schema": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "example": "A-1042",
      "description": "Order number shown to the customer"
    },
    {
      "name": "customer",
      "type": "object",
      "required": true
    },
    {
      "name": "items",
      "type": "list",
      "required": true
    },
    {
      "name": "total",
      "type": "string",
      "required": true
    }
  ],
  "publish": true
}'
```

**Response `201 Created`**

```json
{
  "object": "template",
  "alias": "receipt-de",
  "status": "published",
  "variable_names": [
    "customer",
    "items",
    "order_id",
    "total"
  ]
}
```

**Choose the alias**

```javascript
const alias = ['de', 'fr'].includes(user.locale) ? 'receipt-' + user.locale : 'receipt';
await fetch('https://zapsmtp.xyz/v1/emails', {
  method: 'POST',
  headers: {Authorization: 'Bearer ' + process.env.ZAP_API_KEY, 'Content-Type': 'application/json'},
  body: JSON.stringify({to: [user.email], template: {id: alias, variables}}),
});
```

## Managing templates

## Create a template

`name` is required (up to 200 characters) and at least one of `html` and `text`. `alias` is optional: lowercase letters, digits, `-` and `_`, starting with a letter or digit, up to 63 characters, unique in the account; it works wherever an id does. `from` is the default sender, `variables` are sample values for previews (they are never used for sending). `variable_schema` declares each variable’s type, whether a send must give it and its default; see Variable schema. A request body may be up to 4 MB. Creating, updating, publishing and restoring need a full-access live key; test keys (`zap_test_…`) may only read templates and call the two render endpoints, and get `403 test_key_restricted` otherwise.

Templates made in the visual editor also carry `design`, the editor’s document. Changing the HTML value through the API without sending `design` drops it (sending the same HTML again keeps it) and turns the template into a code template; see the [editor guide](https://www.zapsmtp.xyz/docs/template-editor/).

## Create the receipt template

`POST /v1/templates`

Store the source with an alias, a default From, sample variables and the variable schema. `publish: true` makes it sendable at once; leave it out to keep a draft. Reference: [Create a template](https://www.zapsmtp.xyz/docs/templates/create-template/). Needs a full-access *live* key: test keys get `403 test_key_restricted`.

Requires a full-access live key; test keys get 403 test_key_restricted.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Receipt",
  "alias": "receipt",
  "from": "Acme <billing@acme.com>",
  "subject": "Your Acme receipt {{order_id}}",
  "html": "<p>Hi {{customer.first_name}},</p>\n<p>Thanks for order {{order_id}}.</p>\n<table>\n{{#items}}<tr><td>{{quantity}} × {{name}}</td><td>{{price}}</td></tr>\n{{/items}}</table>\n<p>Total: <strong>{{total}}</strong></p>\n{{#coupon}}<p>Use <strong>{{code}}</strong> for {{percent}}% off your next order.</p>\n{{/coupon}}",
  "text": "Hi {{customer.first_name}},\n\nThanks for order {{order_id}}.\n{{#items}}- {{quantity}} x {{name}}: {{price}}\n{{/items}}Total: {{total}}\n{{#coupon}}\nUse {{code}} for {{percent}}% off your next order.\n{{/coupon}}",
  "variables": {
    "order_id": "A-1042",
    "customer": {
      "first_name": "Ann"
    },
    "items": [
      {
        "name": "Coffee beans",
        "quantity": 2,
        "price": "$24.00"
      },
      {
        "name": "Grinder",
        "quantity": 1,
        "price": "$89.00"
      }
    ],
    "total": "$113.00",
    "coupon": {
      "code": "THANKS15",
      "percent": 15
    }
  },
  "variable_schema": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "example": "A-1042",
      "description": "Order number shown to the customer"
    },
    {
      "name": "customer",
      "type": "object",
      "required": true
    },
    {
      "name": "items",
      "type": "list",
      "required": true
    },
    {
      "name": "total",
      "type": "string",
      "required": true
    },
    {
      "name": "coupon",
      "type": "object",
      "required": false
    }
  ],
  "publish": true
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "name": "Receipt",
  "alias": "receipt",
  "subject": "Your Acme receipt {{order_id}}",
  "html": "<p>Hi {{customer.first_name}},</p>\n<p>Thanks for order {{order_id}}.</p>\n<table>\n{{#items}}<tr><td>{{quantity}} × {{name}}</td><td>{{price}}</td></tr>\n{{/items}}</table>\n<p>Total: <strong>{{total}}</strong></p>\n{{#coupon}}<p>Use <strong>{{code}}</strong> for {{percent}}% off your next order.</p>\n{{/coupon}}",
  "text": "Hi {{customer.first_name}},\n\nThanks for order {{order_id}}.\n{{#items}}- {{quantity}} x {{name}}: {{price}}\n{{/items}}Total: {{total}}\n{{#coupon}}\nUse {{code}} for {{percent}}% off your next order.\n{{/coupon}}",
  "from": "Acme <billing@acme.com>",
  "variables": {
    "order_id": "A-1042",
    "customer": {
      "first_name": "Ann"
    },
    "items": [
      {
        "name": "Coffee beans",
        "quantity": 2,
        "price": "$24.00"
      },
      {
        "name": "Grinder",
        "quantity": 1,
        "price": "$89.00"
      }
    ],
    "total": "$113.00",
    "coupon": {
      "code": "THANKS15",
      "percent": 15
    }
  },
  "variable_schema": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "example": "A-1042",
      "description": "Order number shown to the customer"
    },
    {
      "name": "customer",
      "type": "object",
      "required": true
    },
    {
      "name": "items",
      "type": "list",
      "required": true
    },
    {
      "name": "total",
      "type": "string",
      "required": true
    },
    {
      "name": "coupon",
      "type": "object",
      "required": false
    }
  ],
  "created_at": "2026-10-21T16:10:00Z",
  "updated_at": "2026-10-21T16:10:00Z",
  "object": "template",
  "variable_names": [
    "coupon",
    "customer",
    "items",
    "order_id",
    "total"
  ],
  "status": "published",
  "has_unpublished_changes": false,
  "published_at": "2026-10-21T16:10:00Z",
  "published": {
    "subject": "Your Acme receipt {{order_id}}",
    "html": "<p>Hi {{customer.first_name}},</p>\n<p>Thanks for order {{order_id}}.</p>\n<table>\n{{#items}}<tr><td>{{quantity}} × {{name}}</td><td>{{price}}</td></tr>\n{{/items}}</table>\n<p>Total: <strong>{{total}}</strong></p>\n{{#coupon}}<p>Use <strong>{{code}}</strong> for {{percent}}% off your next order.</p>\n{{/coupon}}",
    "text": "Hi {{customer.first_name}},\n\nThanks for order {{order_id}}.\n{{#items}}- {{quantity}} x {{name}}: {{price}}\n{{/items}}Total: {{total}}\n{{#coupon}}\nUse {{code}} for {{percent}}% off your next order.\n{{/coupon}}",
    "from": "Acme <billing@acme.com>",
    "variable_schema": [
      {
        "name": "order_id",
        "type": "string",
        "required": true,
        "example": "A-1042",
        "description": "Order number shown to the customer"
      },
      {
        "name": "customer",
        "type": "object",
        "required": true
      },
      {
        "name": "items",
        "type": "list",
        "required": true
      },
      {
        "name": "total",
        "type": "string",
        "required": true
      },
      {
        "name": "coupon",
        "type": "object",
        "required": false
      }
    ]
  }
}
```

## Drafts and publishing

Each template has a draft (its top-level fields) and a published version (`published`). Edits always change the draft; sends always use the published version. So you can change a live template, preview it, and switch over in one step.

**Status fields**

- **`status`**: `draft` until the first publish, then `published`. Sending with a never-published template fails.
- **`has_unpublished_changes`**: `true` when the draft’s subject, HTML, text, From, design or variable schema differ from the published version.
- **`published_at`**: Time of the last publish.
- **`publish: true`**: On create or update, saves and publishes in one call.

## Edit the draft

`PATCH /v1/templates/{id}`

Partial update: omitted fields stay as they are. The change lands in the draft; sends keep using the published version and the response shows `has_unpublished_changes: true`. Reference: [Update a template](https://www.zapsmtp.xyz/docs/templates/update-template/). Needs a full-access *live* key: test keys get `403 test_key_restricted`.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Template id or alias

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/templates/receipt' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "subject": "Receipt {{order_id}} from Acme"
}'
```

**Response `200 OK`**

```json
{
  "object": "template",
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "alias": "receipt",
  "subject": "Receipt {{order_id}} from Acme",
  "status": "published",
  "has_unpublished_changes": true,
  "published": {
    "subject": "Your Acme receipt {{order_id}}",
    "html": "<p>Hi {{customer.first_name}},</p>\n<p>Thanks for order {{order_id}}.</p>\n<table>\n{{#items}}<tr><td>{{quantity}} × {{name}}</td><td>{{price}}</td></tr>\n{{/items}}</table>\n<p>Total: <strong>{{total}}</strong></p>\n{{#coupon}}<p>Use <strong>{{code}}</strong> for {{percent}}% off your next order.</p>\n{{/coupon}}",
    "text": "Hi {{customer.first_name}},\n\nThanks for order {{order_id}}.\n{{#items}}- {{quantity}} x {{name}}: {{price}}\n{{/items}}Total: {{total}}\n{{#coupon}}\nUse {{code}} for {{percent}}% off your next order.\n{{/coupon}}",
    "from": "Acme <billing@acme.com>"
  }
}
```

## Publish the draft

`POST /v1/templates/{id}/publish`

Copies the current draft to `published`. From this moment every send with `receipt` uses it. Reference: [Publish a template](https://www.zapsmtp.xyz/docs/templates/publish-template/). Needs a full-access *live* key: test keys get `403 test_key_restricted`.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Template id or alias.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/receipt/publish' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "template",
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "alias": "receipt",
  "subject": "Receipt {{order_id}} from Acme",
  "status": "published",
  "has_unpublished_changes": false,
  "published_at": "2026-10-22T09:00:00Z",
  "published": {
    "subject": "Receipt {{order_id}} from Acme",
    "html": "<p>Hi {{customer.first_name}},</p>\n<p>Thanks for order {{order_id}}.</p>\n<table>\n{{#items}}<tr><td>{{quantity}} × {{name}}</td><td>{{price}}</td></tr>\n{{/items}}</table>\n<p>Total: <strong>{{total}}</strong></p>\n{{#coupon}}<p>Use <strong>{{code}}</strong> for {{percent}}% off your next order.</p>\n{{/coupon}}",
    "text": "Hi {{customer.first_name}},\n\nThanks for order {{order_id}}.\n{{#items}}- {{quantity}} x {{name}}: {{price}}\n{{/items}}Total: {{total}}\n{{#coupon}}\nUse {{code}} for {{percent}}% off your next order.\n{{/coupon}}",
    "from": "Acme <billing@acme.com>"
  }
}
```

## Versions and restore

Every create, update, publish and restore records the draft as a version with its `kind` (`saved`, `published` or `restored`) and `author` (a user’s email, or `API key`). Only the newest 50 are kept.

## List versions

`GET /v1/templates/{id}/versions`

Every save, publish and restore is recorded; the newest 50 are kept, newest first. The list carries no bodies: fetch one with `GET /templates/{id}/versions/{vid}`.

Requires a full-access key.

### Path parameters

- `id` (string, required): Template id or alias

```bash
curl 'https://zapsmtp.xyz/v1/templates/receipt/versions' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f61-2b3c-7d4e-8f5a-6b7c8d9e0f1a",
      "kind": "published",
      "author": "API key",
      "name": "Receipt",
      "subject": "Receipt {{order_id}} from Acme",
      "created_at": "2026-10-22T09:00:00Z"
    },
    {
      "id": "019a1f60-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "kind": "saved",
      "author": "API key",
      "name": "Receipt",
      "subject": "Receipt {{order_id}} from Acme",
      "created_at": "2026-10-22T08:58:00Z"
    },
    {
      "id": "019a1f23-7f81-7192-8b3c-4d5e6f7a8b9d",
      "kind": "published",
      "author": "API key",
      "name": "Receipt",
      "subject": "Your Acme receipt {{order_id}}",
      "created_at": "2026-10-21T16:10:00Z"
    }
  ]
}
```

## Restore a version

`POST /v1/templates/{id}/versions/{vid}/restore`

Copies the version’s name, subject, HTML, text, From and design into the draft (alias and sample variables are kept). Publishing stays a separate step, so a restore never changes what is being sent. Needs a full-access *live* key: test keys get `403 test_key_restricted`.

Requires a full-access key.

### Path parameters

- `id` (string, required): Template id or alias
- `vid` (string, required): Version id from the list

### Errors

- `not_found` (HTTP 404): template not found / version not found

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/receipt/versions/019a1f23-7f81-7192-8b3c-4d5e6f7a8b9d/restore' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "template",
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "alias": "receipt",
  "subject": "Your Acme receipt {{order_id}}",
  "status": "published",
  "has_unpublished_changes": true
}
```

## Preview before you publish

Render a stored template’s draft to check a change, or render unsaved source to validate it. Both return the rendered subject, HTML and text, the missing variables and the variable names. Neither sends anything.

## Preview a stored template

`POST /v1/templates/{id}/render`

Renders the *draft* with the variables you pass, or with its sample variables when `variables` is omitted. Here `coupon` is `null`, so the coupon block disappears. Reference: [Render a template](https://www.zapsmtp.xyz/docs/templates/render-template/).

Requires a full-access key.

### Path parameters

- `id` (string, required): Template id or alias

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/receipt/render' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "variables": {
    "order_id": "A-1042",
    "customer": {
      "first_name": "Ann"
    },
    "items": [
      {
        "name": "Coffee beans",
        "quantity": 2,
        "price": "$24.00"
      },
      {
        "name": "Grinder",
        "quantity": 1,
        "price": "$89.00"
      }
    ],
    "total": "$113.00",
    "coupon": null
  }
}'
```

**Response `200 OK`**

```json
{
  "subject": "Receipt A-1042 from Acme",
  "html": "<p>Hi Ann,</p>\n<p>Thanks for order A-1042.</p>\n<table>\n<tr><td>2 × Coffee beans</td><td>$24.00</td></tr>\n<tr><td>1 × Grinder</td><td>$89.00</td></tr>\n</table>\n<p>Total: <strong>$113.00</strong></p>\n",
  "text": "Hi Ann,\n\nThanks for order A-1042.\n- 2 x Coffee beans: $24.00\n- 1 x Grinder: $89.00\nTotal: $113.00\n",
  "missing_variables": [],
  "variable_names": [
    "coupon",
    "customer",
    "items",
    "order_id",
    "total"
  ]
}
```

## Catch a syntax error

`POST /v1/templates/render`

Unclosed or mismatched tags are reported with the field, line and column (1-based). The same check runs when a template is created or updated, so a broken template cannot be saved.

Requires a full-access key.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/render' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "html": "<ul>\n  {{#items}}\n  <li>{{name}}</li>\n</ul>",
  "variables": {
    "items": []
  }
}'
```

**Response `422 `**

```json
{
  "statusCode": 422,
  "name": "template_render_error",
  "message": "html: line 2, column 3: unclosed section {{#items}}",
  "error": {
    "code": "template_render_error",
    "message": "html: line 2, column 3: unclosed section {{#items}}",
    "type": "invalid_request_error"
  }
}
```

## Variables

## Three kinds of variables

Every name in a template belongs to one of three kinds. [`GET /variables`](https://www.zapsmtp.xyz/docs/variables/list-variables/) lists them all in one catalogue, with the templates that use each.

**Kinds**

- **Kind**: **Written as** · **Value comes from** · **Editable**
- **System**: `{{{zap:unsubscribe_url}}}` · ZapSMTP, at send time · No
- **Global**: `{{global.company_name}}` · The account (`PUT /variables/global/{key}`) · Yes, never by a send
- **Template**: `{{order_id}}, {{customer.first_name}}` · `template.variables` in the send, else the declared default · Per template

## Variable schema

A template declares its own variables in `variable_schema`: a list of entries with `name`, `type`, `required`, `default`, `example` and `description`. Send it on [create](https://www.zapsmtp.xyz/docs/templates/create-template/) or [update](https://www.zapsmtp.xyz/docs/templates/update-template/); it replaces the declared list. Names are letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved. A default and an example must be of the variable’s type. Up to 200 entries.

**Types**

- **`string`**: A JSON string.
- **`number`**: A JSON number.
- **`boolean`**: `true` or `false`.
- **`url`**: A string: an `http://` or `https://` URL with a host, or a `mailto:` or `tel:` link.
- **`date`**: A string: an RFC 3339 time (`2026-11-28T23:59:59Z`) or a date (`2026-11-28`).
- **`list`**: A JSON array: for sections that repeat.
- **`object`**: A JSON object: for dotted names and sections that render once.
- **`any`**: Any JSON value, not checked. Discovery on save gives this type to names you have not declared.

**Discovery on save.** Every save compares the schema with the source. A top-level name the source uses but the schema lacks is added, with its sample value from `variables` as `example`, and never stricter than sends were before schemas: a section (`{{#items}}`, `{{^vip}}`) as an optional `any` (left out, it is skipped), a dotted name (`{{customer.first_name}}`) as a required `object`, and any other name as a required `any`. Declare a type (`string`, `number`, `list` and so on) to have sends checked against it. A declared name the source no longer uses is kept and marked `unused: true`, never dropped silently.

The schema has a draft and a published copy like the rest of the template, and sends use the published one (`published.variable_schema`).

## Defaults and errors at send time

For each declared variable, in this order:

1. A value in `template.variables` (other than `null`) is used and must be of its type; otherwise the send fails with `422 template_variables_invalid`, listing the names.
2. Without a value, the default is used.
3. Without a default, a required variable fails the send with `422 template_variables_missing`, listing the names; an optional one is `null`, so it renders empty and its section is skipped.

Wrong types are reported first. Values the schema does not declare are passed through untouched. Global variables are added next, then the template is rendered: a field missing inside an object (`customer.first_name`) or a global variable with no value still fails with `422 template_render_error`.

> A template last published before variable schemas existed has `published.variable_schema: null` and keeps the old rule: every variable it renders must be given, or the send fails with `template_render_error`. Save it, so its schema is stored, then publish it to switch to the schema.

## A required variable is missing

`POST /v1/emails`

The receipt declares `customer` and `total` as required with no default. Without them the send is refused and nothing is queued.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "template": {
    "id": "receipt",
    "variables": {
      "order_id": "A-1042",
      "items": [
        {
          "name": "Coffee beans",
          "quantity": 2,
          "price": "$24.00"
        },
        {
          "name": "Grinder",
          "quantity": 1,
          "price": "$89.00"
        }
      ]
    }
  }
}'
```

**Response `422 `**

```json
{
  "statusCode": 422,
  "name": "template_variables_missing",
  "message": "missing required template variables: customer, total",
  "error": {
    "code": "template_variables_missing",
    "message": "missing required template variables: customer, total",
    "type": "invalid_request_error"
  }
}
```

## Global variables

Company name, postal address, support URL, social links: values every template shares are set once for the account and written `{{global.key}}`. Keys follow the rules for variable names; values are strings of up to 10 KB, with an optional description of up to 500 bytes. A change applies to every template that uses the key from the next send on, with no publish needed.

- A send cannot override them: `template.variables.global` is refused with `422 invalid_parameter`, and `global` cannot be declared in a schema.
- A global variable a template uses but the account has not set is missing: sends fail with `template_render_error`, and the catalogue lists it without a value so you can set it.
- Values are escaped in HTML like any other: use `{{{global.address_html}}}` only for HTML you wrote.

## Set a global variable

`PUT /v1/variables/global/{key}`

Creates or replaces `{{global.company_name}}` for every template of the account, from the next send on. Reference: [Set a global variable](https://www.zapsmtp.xyz/docs/variables/put-global-variable/). Needs a full-access *live* key: test keys get `403 test_key_restricted`.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `key` (string, required): The key, used as `{{global.key}}`: letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved. Limits: other keys → 422 invalid_parameter

```bash
curl -X PUT 'https://zapsmtp.xyz/v1/variables/global/company_name' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "value": "Acme Inc.",
  "description": "Legal name for footers"
}'
```

**Response `200 OK`**

```json
{
  "object": "variable",
  "name": "global.company_name",
  "kind": "global",
  "type": "string",
  "key": "company_name",
  "value": "Acme Inc.",
  "description": "Legal name for footers",
  "updated_at": "2026-10-27T10:30:00Z",
  "templates": []
}
```

## Previews

`POST /templates/{id}/render` renders the draft with, for each variable, the value you pass, else its `example`, else its `default`; without a `variables` object it takes the template’s sample `variables`. `POST /templates/render` uses only the values you pass. Both add the account’s global variables, and neither checks types or required variables: what is missing is listed in `missing_variables`.

## Sending

## Sending with a template

Pass `template.id` and the variables instead of `subject`, `html` and `text`. `template.id` takes either of two names for the same template:

**template.id**

- **Template id**: The UUID, e.g. `019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c`. Shown with a copy button in the dashboard’s template list and editor header, and returned as `id` by the API. It never changes.
- **Alias**: Your readable name, e.g. `receipt`, if the template has one. Unique in the account and works wherever an id does. You can change it; if you do, update the code that sends with it.

Sends always use the **published** version: subject, HTML, text, From and variable schema. Draft changes have no effect until you publish them, and a template that was never published cannot be sent (`422 invalid_parameter`). Previews render the draft.

## Send rules

**template on POST /emails**

- **`template.id`**: Template id or alias. Required.
- **`template.variables`**: Object of values for the template’s own variables, checked against the published variable schema (types, required, defaults). Values the schema does not declare are passed through. Every `{{x}}` or `{{{x}}}` that is actually rendered must end up with a value; tags inside skipped sections are not checked. The key `global` is reserved.
- **`html`, `text`**: Not allowed together with `template`.
- **`subject`**: Optional; overrides the template’s subject and is used as written, without rendering.
- **`from`**: Optional when the template has a From; overrides it when given. Live keys still need a verified domain.
- **Everything else**: `cc`, `bcc`, `reply_to`, `headers`, `attachments`, `tags`, `metadata`, `tracking`, `stream`, `scheduled_at` and `tls` work as in any send.

## Send with a template

`POST /v1/emails`

Pass `template.id` (id or alias) and its `variables` instead of `subject`, `html` and `text`. From comes from the template here. Reference: [Send an email](https://www.zapsmtp.xyz/docs/emails/send-email/).

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "template": {
    "id": "receipt",
    "variables": {
      "order_id": "A-1042",
      "customer": {
        "first_name": "Ann"
      },
      "items": [
        {
          "name": "Coffee beans",
          "quantity": 2,
          "price": "$24.00"
        },
        {
          "name": "Grinder",
          "quantity": 1,
          "price": "$89.00"
        }
      ],
      "total": "$113.00",
      "coupon": {
        "code": "THANKS15",
        "percent": 15
      }
    }
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Override From and subject

`POST /v1/emails`

`from` and `subject` in the request win over the template’s. The request subject is used as written: it is not rendered, so it cannot contain variables.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme Orders <orders@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Receipt A-1042 (copy)",
  "template": {
    "id": "receipt",
    "variables": {
      "order_id": "A-1042",
      "customer": {
        "first_name": "Ann"
      },
      "items": [
        {
          "name": "Coffee beans",
          "quantity": 2,
          "price": "$24.00"
        },
        {
          "name": "Grinder",
          "quantity": 1,
          "price": "$89.00"
        }
      ],
      "total": "$113.00",
      "coupon": {
        "code": "THANKS15",
        "percent": 15
      }
    }
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Templates with tags, metadata and scheduling

`POST /v1/emails`

Every other send field works as usual. The template is rendered when the request is accepted: a scheduled email keeps that content even if the template is published again before it goes out.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: order-A-1042-receipt' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "template": {
    "id": "receipt",
    "variables": {
      "order_id": "A-1042",
      "customer": {
        "first_name": "Ann"
      },
      "items": [
        {
          "name": "Coffee beans",
          "quantity": 2,
          "price": "$24.00"
        },
        {
          "name": "Grinder",
          "quantity": 1,
          "price": "$89.00"
        }
      ],
      "total": "$113.00",
      "coupon": null
    }
  },
  "tags": [
    {
      "name": "category",
      "value": "receipt"
    }
  ],
  "metadata": {
    "order_id": "A-1042",
    "customer_id": "C-77"
  },
  "scheduled_at": "in 2 hours"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Send a batch from one template

`POST /v1/emails/batch`

Each item of a batch carries its own variables. With the default `x-batch-validation: strict`, one item with missing variables stops the whole batch; with `permissive` it is reported in `errors` and the others go out. Reference: [Send a batch](https://www.zapsmtp.xyz/docs/emails/send-batch/).

Requires a full-access or sending-access key. Test keys follow the same rules as for sending.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "to": [
      "delivered@simulator.zapsmtp.xyz"
    ],
    "template": {
      "id": "receipt",
      "variables": {
        "order_id": "A-1042",
        "customer": {
          "first_name": "Ann"
        },
        "items": [
          {
            "name": "Coffee beans",
            "quantity": 2,
            "price": "$24.00"
          },
          {
            "name": "Grinder",
            "quantity": 1,
            "price": "$89.00"
          }
        ],
        "total": "$113.00",
        "coupon": {
          "code": "THANKS15",
          "percent": 15
        }
      }
    }
  },
  {
    "to": [
      "delivered+bob@simulator.zapsmtp.xyz"
    ],
    "template": {
      "id": "receipt",
      "variables": {
        "order_id": "A-1043",
        "customer": {
          "first_name": "Bob"
        },
        "items": [
          {
            "name": "Filters",
            "quantity": 3,
            "price": "$6.00"
          }
        ],
        "total": "$6.00",
        "coupon": null
      }
    }
  }
]'
```

**Response `200 OK`**

```json
{
  "data": [
    {
      "index": 0,
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    },
    {
      "index": 1,
      "id": "019a1f2e-7c3c-7a10-8b21-4d5e6f7a8b9c"
    }
  ],
  "errors": []
}
```

## Errors

Errors use the standard [error shape](https://www.zapsmtp.xyz/docs/conventions/). In a batch, the same codes appear per item in `errors[]`.

**Template errors**

- **`template_variables_missing` (HTTP 422)**: `missing required template variables: customer, total` Send: required variables of the published schema have no value and no default. Sorted by name.
- **`template_variables_invalid` (HTTP 422)**: `template variables of the wrong type: items` Send: values that do not match their declared type. Checked before missing ones. Sorted by name.
- **`template_render_error` (HTTP 422)**: `missing template variables: last_name, plan.name` Send: a variable the template renders is still absent: a field inside an object, a global variable with no value, or any variable of a template published before variable schemas. Names come in no particular order.
- **`invalid_parameter` (HTTP 422)**: `template.variables.global is reserved: global variables are set in the account (PUT /v1/variables/global/{key})` Send: `template.variables` has a `global` key.
- **`invalid_parameter` (HTTP 422)**: `variable_schema: items: type must be one of string, number, boolean, url, date, list, object, any` Create, update: a bad schema entry. Also: a bad or reserved name, a name declared twice, a default or example not of its type, a description over 500 bytes, more than 200 entries.
- **`template_render_error` (HTTP 422)**: `html: line 2, column 3: unclosed section {{#items}}` Create, update, render: syntax error in subject, html or text.
- **`template_render_error` (HTTP 422)**: `html: line 4, column 1: {{#each items}} is not a variable name: letters, digits, _ and - (no spaces), parts joined with dots` Create, update: a tag that names no variable, such as `{{first name}}`, Handlebars `{{#each items}}` or a partial `{{> footer}}`. Templates saved before this check still send.
- **`template_render_error` (HTTP 422)**: `html: template output too large (lists nested too deep or too long)` Render or send: the output would exceed 10 MB or the work limit.
- **`invalid_parameter` (HTTP 422)**: `template receipt not found` Send: no template with this id or alias in the account.
- **`invalid_parameter` (HTTP 422)**: `template receipt is not published (POST /v1/templates/<id>/publish)` Send: the template has never been published.
- **`invalid_parameter` (HTTP 422)**: `html/text cannot be combined with template` Send: the request has both a body and a template.
- **`missing_required_field` (HTTP 422)**: `template.id is required` Send: `template` without `id`.
- **`missing_required_field` (HTTP 422)**: `html or text is required` Create, update: both bodies empty.
- **`invalid_parameter` (HTTP 422)**: `alias must match [a-z0-9][a-z0-9_-]{0,62}` Create, update: bad alias.
- **`conflict` (HTTP 409)**: `a template with this alias already exists` Create, update: aliases are unique per account.
- **`not_found` (HTTP 404)**: `template not found` Template endpoints: unknown id or alias.
- **`test_key_restricted` (HTTP 403)**: `test-mode keys can send test email and read, not change the account: use a live key` Create, update, publish, duplicate, restore, delete with a test key.

```json
{
  "statusCode": 422,
  "name": "template_render_error",
  "message": "missing template variables: total",
  "error": {
    "code": "template_render_error",
    "message": "missing template variables: total",
    "type": "invalid_request_error"
  }
}
```

> To catch missing variables before production, render with the exact variables your code builds: `POST /templates/{id}/render` and fail your test when `missing_variables` is not empty. Note that it renders the draft, while sends use the published version.

---

# Email template editor

Source: https://www.zapsmtp.xyz/docs/template-editor/

Keep your emails in ZapSMTP and send them with a template id and variables: your code stays free of HTML, and anyone on the team can change a message without a deploy. Build a template visually, or write the HTML yourself.

## Templates

*Templates* lists every template with its editor, status and the variables it uses. A template is a *draft* until you publish it; sends always use the published version, so you can edit safely while it is in use. An alias (`order-shipped`) lets your code refer to it by name.

![The Templates list: order shipped, order confirmation, password reset, welcome, abandoned cart and a receipt written in HTML, with statuses and variables](https://www.zapsmtp.xyz/docs/img/templates-light.webp)

## Start from the gallery

*New template* opens a gallery of ready designs: order and shipping updates, password resets, welcome series, promotions, newsletters, invoices and more. Every one is responsive, supports dark mode and is filled with sample data, so you see the finished email before you pick it. Start blank, or with code, from the same page.

![The template gallery with categories Quick start, Transactional, Triggers, Promo, Business and Info, and live previews of each design](https://www.zapsmtp.xyz/docs/img/gallery-light.webp)

## The visual editor

Drag rows and blocks onto the email: headings, text, images, buttons, dividers, social links, menus, lists, tables, video, countdown timers and custom HTML. Click any block to change it on the right, edit text in place, and switch between desktop and mobile views as you go. Rows can repeat for each item of a list (an order's products) or appear only when a variable is set.

![The visual editor: a palette of blocks on the left, an order-shipped email in the middle, and the selected button's settings on the right](https://www.zapsmtp.xyz/docs/img/visual-editor-light.webp)

The visual editor: blocks on the left, settings for the selected button on the right.

Variables are written as `{{name}}` and highlighted in the email. The editor keeps an undo history, saves a backup in your browser while you work, and keeps the last 50 saved versions, any of which you can preview and restore. *Preview* shows the email on desktop, on a phone, in dark mode and as plain text; *Test* sends it to your inbox; *Spam check* scores it with SpamAssassin and rspamd.

## Writing HTML

Prefer your own HTML? The code editor highlights HTML and variables, completes variable names as you type `{{`, and marks a template error on its line. The preview on the right renders with your sample variables as you type. The plain-text part is one click away: *Generate from HTML*.

![The code editor: a receipt template in HTML on the left and its live preview with sample data on the right](https://www.zapsmtp.xyz/docs/img/code-editor-light.webp)

**Template syntax**

- **`{{name}}`**: The value, HTML-escaped.
- **`{{{url}}}`**: The value as is: for links and trusted HTML.
- **`{{#items}}…{{/items}}`**: Repeats for each item of a list, or shows the part when the value is set.
- **`{{^items}}…{{/items}}`**: Shows the part when the value is empty or missing.
- **`{{user.plan}}`**: A field of an object.

## Sending with a template

Pass the template's id or alias and its variables instead of a subject and HTML. The subject, the HTML and the plain text are all rendered from the published version; a missing variable is an error, so a half-filled email never goes out.

```
curl -X POST https://zapsmtp.xyz/v1/emails \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["sofia@example.com"],
    "template": {
      "id": "order-shipped",
      "variables": { "name": "Sofia", "order_id": "H-20512", "carrier": "UPS" }
    }
  }'
```

Every template has a *Send it* example with your own variables in its Details tab. The full request is in the [API reference](https://www.zapsmtp.xyz/docs/emails/send-email/).

---

# SMTP relay

Source: https://www.zapsmtp.xyz/docs/smtp/

Point any application, CMS or mail library at ZapSMTP. SMTP and the API share one pipeline: the same email log, events, webhooks, suppressions and limits.

**Settings**

- **Host**: `zapsmtp.xyz`
- **Ports**: `587` or `2525` with STARTTLS, `465` with TLS
- **Encryption**: TLS 1.2 or newer. Authentication is refused on an unencrypted connection.
- **Authentication**: `PLAIN` or `LOGIN`
- **Limits**: 40 MB per message, 50 recipients per message

## Credentials

Create an SMTP credential for each application in the dashboard or with [the API](https://www.zapsmtp.xyz/docs/keys/create-smtp-credential/). Its username looks like `smtp_k3f9x2m7q1ab` and it has its own password, shown once. Credentials can only send; they never work with the HTTP API, and you can revoke one without touching the others.

An API key also works as the password with any username that does not start with `smtp_` (for example `zapsmtp`). Test keys work too: the message runs the whole pipeline and is not delivered.

Choose the stream per message with the header `X-Zap-Stream: broadcast` (default `transactional`).

Turn [reply tracking](https://www.zapsmtp.xyz/docs/inbound-guide/#reply-tracking-intro) on or off for one message with `X-Zap-Reply-Tracking: on` or `off`; without the header the From domain’s default applies. Any other value is refused with `550 5.6.0`.

**Send over SMTP**

Node.js:

```javascript
import nodemailer from 'nodemailer';

const transport = nodemailer.createTransport({
  host: 'zapsmtp.xyz',
  port: 587, // STARTTLS
  auth: { user: process.env.ZAP_SMTP_USER, pass: process.env.ZAP_SMTP_PASSWORD },
});

await transport.sendMail({
  from: 'Acme <hello@acme.com>',
  to: 'delivered@simulator.zapsmtp.xyz',
  subject: 'Hello over SMTP',
  html: '<p>It works.</p>',
});
```

Python:

```python
import os
import smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "Acme <hello@acme.com>"
msg["To"] = "delivered@simulator.zapsmtp.xyz"
msg["Subject"] = "Hello over SMTP"
msg.set_content("It works.")

with smtplib.SMTP("zapsmtp.xyz", 587) as smtp:
    smtp.starttls()
    smtp.login(os.environ["ZAP_SMTP_USER"], os.environ["ZAP_SMTP_PASSWORD"])
    smtp.send_message(msg)
```

PHP:

```php
<?php
use PHPMailer\PHPMailer\PHPMailer;

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'zapsmtp.xyz';
$mail->Port = 587;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->SMTPAuth = true;
$mail->Username = getenv('ZAP_SMTP_USER');
$mail->Password = getenv('ZAP_SMTP_PASSWORD');

$mail->setFrom('hello@acme.com', 'Acme');
$mail->addAddress('delivered@simulator.zapsmtp.xyz');
$mail->Subject = 'Hello over SMTP';
$mail->Body = 'It works.';
$mail->send();
```

Go:

```go
package main

import (
	"net/smtp"
	"os"
)

func main() {
	auth := smtp.PlainAuth("", os.Getenv("ZAP_SMTP_USER"), os.Getenv("ZAP_SMTP_PASSWORD"), "zapsmtp.xyz")
	msg := []byte("From: Acme <hello@acme.com>\r\n" +
		"To: delivered@simulator.zapsmtp.xyz\r\n" +
		"Subject: Hello over SMTP\r\n\r\nIt works.\r\n")
	// net/smtp upgrades to TLS with STARTTLS before authenticating
	err := smtp.SendMail("zapsmtp.xyz:587", auth, "hello@acme.com",
		[]string{"delivered@simulator.zapsmtp.xyz"}, msg)
	if err != nil {
		panic(err)
	}
}
```

Ruby:

```ruby
require 'net/smtp'

msg = <<~MAIL
  From: Acme <hello@acme.com>
  To: delivered@simulator.zapsmtp.xyz
  Subject: Hello over SMTP

  It works.
MAIL

Net::SMTP.start('zapsmtp.xyz', 587, starttls: :always,
                user: ENV.fetch('ZAP_SMTP_USER'), secret: ENV.fetch('ZAP_SMTP_PASSWORD'),
                authtype: :plain) do |smtp|
  smtp.send_message(msg, 'hello@acme.com', 'delivered@simulator.zapsmtp.xyz')
end
```

Laravel:

```
MAIL_MAILER=smtp
MAIL_HOST=zapsmtp.xyz
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=smtp_xxxxxxxxxxxx
MAIL_PASSWORD="your SMTP credential password"
MAIL_FROM_ADDRESS=hello@acme.com
```

Django:

```
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "zapsmtp.xyz"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = os.environ["ZAP_SMTP_USER"]
EMAIL_HOST_PASSWORD = os.environ["ZAP_SMTP_PASSWORD"]
```

swaks:

```
swaks --server zapsmtp.xyz:587 --tls \
  --auth-user "$ZAP_SMTP_USER" --auth-password "$ZAP_SMTP_PASSWORD" \
  --from hello@acme.com --to delivered@simulator.zapsmtp.xyz \
  --header "Subject: Hello over SMTP" --body "It works."
```

## Reply codes

`250` after `DATA` means the message was accepted, not delivered; delivery results arrive as [webhook events](https://www.zapsmtp.xyz/docs/webhook-events/). A `4xx` reply is temporary: your mailer keeps the message and retries. A `5xx` reply is permanent: retrying the same message fails the same way.

**SMTP replies**

- **`550 5.6.0` (permanent)**: The message failed validation (for example an unparsable From, a bad header or attachment); the reply says what.
- **`550 5.7.1` (permanent)**: The From domain is not verified, the credential or key is restricted to another domain or to another stream, or the account is suspended.
- **`550 5.1.1` (permanent)**: Every recipient is on your suppression list: nothing is sent.
- **`535 5.7.8` (permanent)**: Authentication failed, or the credential was revoked or expired after you logged in (`Credentials no longer valid`).
- **`451 4.7.0` (temporary)**: Over your per-second rate limit.
- **`452 4.2.2` (temporary)**: Monthly or daily quota reached. The mailer keeps retrying, but nothing goes out until the quota resets or your plan changes.
- **`452 4.5.3` (temporary)**: More than 50 recipients in one message. The extra recipients are refused; send them in another message.
- **`451 4.3.1` (temporary)**: Server busy: too many large messages in flight.
- **`451 4.3.0` (temporary)**: Overloaded, the MTA is briefly unavailable, or an internal error. Retry shortly.
- **`454 4.7.0` (temporary)**: Too many failed logins from your IP (20 in 10 minutes), a temporary authentication failure, or `Account moved`: your account is served by another cell, named with its URL in the reply. Point the mailer at that host.

---

# Webhook events

Source: https://www.zapsmtp.xyz/docs/webhook-events/

ZapSMTP POSTs a JSON event to your endpoint for every recipient and every change. Answer with any 2xx within a few seconds; do the work afterwards.

![A webhook endpoint in the dashboard: its signing secret with verification code, a test-event form and the last deliveries with status codes and timings](https://www.zapsmtp.xyz/docs/img/webhook-light.webp)

Add endpoints under Webhooks in the dashboard: send a test event, watch every delivery and replay any of them.

**Event types**

- **`email.sent`**: Accepted for delivery.
- **`email.delivered`**: The receiving server accepted the message.
- **`email.delivery_delayed`**: A temporary failure; we keep retrying.
- **`email.bounced`**: Permanently rejected, or retries ran out.
- **`email.complained`**: The recipient marked it as spam.
- **`email.failed`**: Rejected before sending.
- **`email.opened`**: The tracking pixel loaded (open tracking on).
- **`email.clicked`**: A tracked link was clicked (click tracking on, or a link with a click action).
- **`email.suppressed`**: Not sent: the recipient is on your suppression list.
- **`email.received`**: An inbound email arrived. Metadata only, unless the endpoint has include_content: then text, html, headers and 24-hour download links for attachments and the raw message (cut at 1 MB, truncated: true).
- **`thread.created`**: A new conversation: a received email that answers nothing. Not sent for automated mail.
- **`thread.replied`**: A customer answered in a conversation. Not sent for auto-replies, bounces and notifications.
- **`email.replied`**: Someone answered an email sent with reply tracking. Sent for every tracked reply, automated ones included; data.reply.type tells them apart.

## Payload

One event per recipient: `data.to` is a single address. `bounce` appears on bounced, delayed, failed and suppressed events; `click` and `open` carry the link, IP and user agent; `click.action` names a link marked with a [click action](https://www.zapsmtp.xyz/docs/click-actions/), and `click.unique`, present on every click, is `true` on the first click of that action by that recipient of that email and `false` on later clicks and on links without an action; `email.opened` and `email.clicked` carry the email’s `metadata` and `tags` when each fits in 200 bytes; and `open.machine` is `true` when Apple Mail Privacy Protection loaded the pixel (such opens may not be a person reading; they still count as opens, and metrics split them out as `human_opened` / `human_open_rate`); `test` is `true` for test keys. `tls` (`version`, e.g. `TLSv1_3`, and `cipher`) appears when the attempt reached the receiving server over TLS.

`email.replied` carries `reply`: `email_id` (the received reply, readable with [GET /emails/receiving/{id}](https://www.zapsmtp.xyz/docs/receiving/get-received/); `data.email_id` is the email that was answered), `from`, `from_name`, `subject`, `text` (the reply without the quoted email, at most 2,000 characters), `type` (`human`, `unsubscribe`, `out_of_office`, `auto_reply`, `auto_generated`, `bounce` or `bulk`), `is_spam`, `sender_matches_recipient` (the replier was one of the email’s To or Cc recipients; `data.to` then names them, otherwise it is empty) and `forward`: `{to, status, reason}`, where `status` is `queued` or `skipped` and `reason` is `spam`, `automated`, `unsubscribe`, `not_allowed` or `no_destination`.

`email.received`, `thread.created` and `thread.replied` have their own `data` (see [Receiving email](https://www.zapsmtp.xyz/docs/inbound-guide/)) and no top-level `id`: dedupe them on the `Zap-Event-Id` header.

```json
{
  "id": "evt_5f0c2a9b7d1e4c3a8b6f2e10",
  "type": "email.bounced",
  "created_at": "2026-10-21T15:04:12.381Z",
  "data": {
    "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
    "from": "Acme <hello@acme.com>",
    "to": "jane@example.org",
    "subject": "Your receipt",
    "tags": {
      "category": "receipt"
    },
    "metadata": {
      "order_id": "A-1042"
    },
    "stream": "transactional",
    "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
    "attempts": 1,
    "response": {
      "code": 550,
      "message": "5.1.1 The email account that you tried to reach does not exist"
    },
    "bounce": {
      "type": "Permanent",
      "subType": "MailboxDoesNotExist",
      "message": "5.1.1 The email account that you tried to reach does not exist",
      "suppressed": true
    }
  }
}
```

An `email.clicked` event:

```json
{
  "id": "evt_7a1d0c3e9b2f4a6c8e5d1b07",
  "type": "email.clicked",
  "created_at": "2026-10-27T08:41:05.214Z",
  "data": {
    "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
    "from": "<@acme.com>",
    "to": "jane@example.org",
    "tags": {
      "category": "receipt"
    },
    "metadata": {
      "order_id": "A-1042"
    },
    "stream": "transactional",
    "click": {
      "link": "https://acme.com/orders/A-1042/confirm",
      "action": "confirm_order",
      "unique": true,
      "ip_address": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.1 Safari/605.1.15"
    }
  }
}
```

An endpoint with `filter.actions` receives `email.clicked` only for those actions; see [Send actions to their own endpoints](https://www.zapsmtp.xyz/docs/click-actions/#webhooks).

**Headers**

- **`Zap-Signature`**: `t=<unix seconds>,v1=<hex HMAC-SHA256>`. After you rotate the secret, both secrets sign for 24 hours and the header carries two `v1` values.
- **`Zap-Event-Id`**: Stable across retries and replays. Store it and skip events you have already processed.
- **`Zap-Webhook-Id`**: The endpoint that this delivery is for.

## Verify signatures

Compute HMAC-SHA256 with your endpoint’s secret (the whole string, including `whsec_`) over `<t>.<raw body>` and compare it, in constant time, with each `v1` value. Reject timestamps older than five minutes. Always use the raw request body: re-serialized JSON will not match.

**Verify Zap-Signature**

Node.js:

```javascript
import crypto from 'node:crypto';
import express from 'express';

const app = express();
// keep the raw body: the signature covers the exact bytes
app.post('/hooks/zapsmtp', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('Zap-Signature') ?? '';
  const parts = header.split(',').map((p) => p.split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
  const expected = crypto.createHmac('sha256', process.env.ZAP_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const ok = fresh && sigs.some((s) => s.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  // dedupe on req.get('Zap-Event-Id'): retries repeat the same id
  res.sendStatus(200);
});
```

Python:

```python
import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/zapsmtp")
def zapsmtp():
    parts = [p.split("=", 1) for p in request.headers.get("Zap-Signature", "").split(",")]
    t = next((v for k, v in parts if k == "t"), "0")
    sigs = [v for k, v in parts if k == "v1"]
    expected = hmac.new(os.environ["ZAP_WEBHOOK_SECRET"].encode(),
                        f"{t}.".encode() + request.get_data(), hashlib.sha256).hexdigest()
    if abs(time.time() - int(t)) > 300 or not any(hmac.compare_digest(s, expected) for s in sigs):
        abort(400)
    event = request.get_json()
    return "", 200
```

PHP:

```php
<?php
$body = file_get_contents('php://input');
$t = null; $sigs = [];
foreach (explode(',', $_SERVER['HTTP_ZAP_SIGNATURE'] ?? '') as $part) {
    [$k, $v] = array_pad(explode('=', $part, 2), 2, '');
    if ($k === 't') $t = $v;
    if ($k === 'v1') $sigs[] = $v;
}
$expected = hash_hmac('sha256', $t . '.' . $body, getenv('ZAP_WEBHOOK_SECRET'));
$valid = abs(time() - (int) $t) < 300
    && count(array_filter($sigs, fn ($s) => hash_equals($expected, $s))) > 0;
if (!$valid) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);
http_response_code(200);
```

Go:

```go
func zapsmtp(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	var t string
	var sigs []string
	for _, part := range strings.Split(r.Header.Get("Zap-Signature"), ",") {
		k, v, _ := strings.Cut(part, "=")
		switch k {
		case "t":
			t = v
		case "v1":
			sigs = append(sigs, v)
		}
	}
	mac := hmac.New(sha256.New, []byte(os.Getenv("ZAP_WEBHOOK_SECRET")))
	mac.Write([]byte(t + "."))
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))
	ts, _ := strconv.ParseInt(t, 10, 64)
	ok := false
	for _, s := range sigs {
		ok = ok || hmac.Equal([]byte(s), []byte(expected))
	}
	if !ok || time.Since(time.Unix(ts, 0)).Abs() > 5*time.Minute {
		http.Error(w, "bad signature", http.StatusBadRequest)
		return
	}
	w.WriteHeader(http.StatusOK)
}
```

Ruby:

```ruby
require 'openssl'
require 'rack/utils'

post '/hooks/zapsmtp' do
  body = request.body.read
  parts = request.env['HTTP_ZAP_SIGNATURE'].to_s.split(',').map { |p| p.split('=', 2) }
  t = parts.find { |k, _| k == 't' }&.last.to_s
  sigs = parts.select { |k, _| k == 'v1' }.map(&:last)
  expected = OpenSSL::HMAC.hexdigest('SHA256', ENV.fetch('ZAP_WEBHOOK_SECRET'), "#{t}.#{body}")
  fresh = (Time.now.to_i - t.to_i).abs < 300
  halt 400 unless fresh && sigs.any? { |s| Rack::Utils.secure_compare(s, expected) }
  event = JSON.parse(body)
  200
end
```

### Check a signature here

Paste a secret and a body to get the header we would send, or paste a received header to check it. Everything runs in your browser.

## Batched delivery

For high volumes, turn on `batch` when you [create](https://www.zapsmtp.xyz/docs/webhooks/create-webhook/) or [update](https://www.zapsmtp.xyz/docs/webhooks/update-webhook/) an endpoint. Events then arrive up to 100 per request, or whatever arrived within a second, as a JSON array of the usual event objects. The array is signed as one body, exactly like a single event. `Zap-Event-Id` is the batch’s id, the same on every retry. Each event in it keeps its own `id`, so dedupe per event (`email.received` and thread events have no `id`: dedupe those on `type` plus `data.email_id`). A failed batch is retried as it was, with the same schedule as single events. `email.received` with `include_content` still arrives on its own.

How fast ZapSMTP sends adapts to your endpoint. Requests in flight start at 32. They grow while your endpoint answers quickly, and halve when it times out or answers 5xx or 429. A slow endpoint is not flooded, and a fast one is not held back.

## Retries

Network errors, timeouts, 5xx, 408 and 429 are retried after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h and 10 h — eight attempts over about 28 hours. Other 4xx answers are final. An endpoint that keeps failing is paused for a minute without losing attempts, and is disabled if five events exhaust their retries within 24 hours (re-enable it with [PATCH](https://www.zapsmtp.xyz/docs/webhooks/update-webhook/)). The last 100 attempts are kept: [list them](https://www.zapsmtp.xyz/docs/webhooks/webhook-deliveries/) and [replay](https://www.zapsmtp.xyz/docs/webhooks/replay-event/) any event.

---

# Click actions

Source: https://www.zapsmtp.xyz/docs/click-actions/

An action is a named button or link. Mark *Confirm order* with `confirm_order` and every click on it reaches your webhook as `email.clicked` with `click.action: "confirm_order"` and the email’s metadata, such as the order id. No parsing URLs to tell one button from another.

## Mark a link

In HTML, whether a code template or `html` in a send, add `data-zap-action` to the link. In the visual editor, every Button block and every link in text has an *Action* field: pick an action the account already has, or type a new name.

**Two actions in a receipt**

HTML:

```html
<p>Thanks for order {{order_id}}. Please confirm it:</p>
<a href="https://acme.com/orders/{{order_id}}/confirm" data-zap-action="confirm_order">Confirm order</a>
<a href="https://acme.com/orders/{{order_id}}/track" data-zap-action="track_parcel">Track parcel</a>
```

Send:

```json
{
  "from": "Acme <orders@acme.com>",
  "to": [
    "ann@example.com"
  ],
  "template": {
    "id": "receipt",
    "variables": {
      "order_id": "A-1042"
    }
  },
  "metadata": {
    "order_id": "A-1042"
  }
}
```

**Rules**

- **Names**: Lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters: `confirm_order`, `plan.upgrade`. A link whose name does not fit is treated as an ordinary link, without an action.
- **Which links**: An `<a>` whose `href` is an absolute `http://` or `https://` URL, in the HTML part. The attribute may stand anywhere in the tag, quoted with `"` or `'`.
- **Click tracking off**: A link with an action is tracked anyway, whether click tracking is off for the domain or for the send (`tracking.clicks: false`). Other links follow the usual setting.
- **`data-zap-notrack`**: Wins: a link with both attributes is left alone, so no click is reported.
- **Forgery**: The action and the destination are signed into the link, so a recipient cannot change the action or point it elsewhere. The browser is redirected to your `href`.
- **Declaring**: Not needed. Any valid name works the moment an email carries it, and it appears in the catalogue as not described.

Everything else about [click tracking](https://www.zapsmtp.xyz/docs/analytics/#click-tracking) applies: links work for 365 days after the send, a repeated click on the same link from the same network within 10 minutes still redirects but is not reported again, and links in the plain-text part are not rewritten.

## What the webhook receives

A click on a marked link is an ordinary [`email.clicked`](https://www.zapsmtp.xyz/docs/webhook-events/) event, with two more fields in `click`:

**data.click**

- **`link`**: The destination, as the browser followed it.
- **`action`**: The link’s action. Absent for links without one.
- **`unique`**: Present on every click: `true` on the first click of that action by that recipient of that email, `false` on later clicks and on links without an action. Use it for “confirm once” flows.
- **`ip_address`, `user_agent`**: Of the click.

The event, like `email.opened`, carries the email’s `metadata` and `tags` when each fits in 200 bytes (metadata as JSON, tags URL-encoded), so keep the ids you need there short: `{"order_id": "A-1042"}`. For click events, `from` holds only the sending domain and there is no `subject`. When an email has several recipients, its links belong to the first `to` address, so send one recipient per email when the action is a person’s answer.

```json
{
  "id": "evt_7a1d0c3e9b2f4a6c8e5d1b07",
  "type": "email.clicked",
  "created_at": "2026-10-27T08:41:05.214Z",
  "data": {
    "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
    "from": "<@acme.com>",
    "to": "ann@example.com",
    "tags": {
      "category": "receipt"
    },
    "metadata": {
      "order_id": "A-1042"
    },
    "stream": "transactional",
    "click": {
      "link": "https://acme.com/orders/A-1042/confirm",
      "action": "confirm_order",
      "unique": true,
      "ip_address": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148"
    }
  }
}
```

> `unique` is a convenience, not a lock. In rare cases, such as a failure of our internal cache, a repeat click may also arrive with `unique: true`. Make the work behind it idempotent on your side: confirming an order twice should change nothing.

**Confirm an order once**

Node.js:

```javascript
// after verifying Zap-Signature (see Webhook events)
const event = JSON.parse(req.body);
if (event.type === 'email.clicked' && event.data.click?.action === 'confirm_order') {
  const orderId = event.data.metadata?.order_id;
  if (event.data.click.unique) {
    await orders.confirm(orderId); // make this idempotent too
  }
}
res.sendStatus(200);
```

Python:

```python
event = request.get_json()
click = event["data"].get("click") or {}
if event["type"] == "email.clicked" and click.get("action") == "confirm_order":
    order_id = (event["data"].get("metadata") or {}).get("order_id")
    if click.get("unique"):
        orders.confirm(order_id)  # make this idempotent too
return "", 200
```

## Send actions to their own endpoints

A webhook endpoint takes an optional `filter`. With `filter.actions` set, it receives `email.clicked` only for links with one of those actions; every other event type it subscribes to is unaffected. Without a filter, or with an empty list, it receives every click, as before. Use one endpoint per action, or one for several: up to 50 actions per endpoint.

## Send one button to its own endpoint

`POST /v1/webhooks`

This endpoint receives `email.clicked` only for links marked `confirm_order`. Reference: [Create a webhook](https://www.zapsmtp.xyz/docs/webhooks/create-webhook/).

Requires a full-access live key; test keys get 403 test_key_restricted.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/hooks/confirm-order",
  "events": [
    "email.clicked"
  ],
  "filter": {
    "actions": [
      "confirm_order"
    ]
  }
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10",
  "url": "https://acme.com/hooks/confirm-order",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "events": [
    "email.clicked"
  ],
  "enabled": true,
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": [
      "confirm_order"
    ]
  },
  "disabled_reason": null,
  "created_at": "2026-10-27T08:00:00Z"
}
```

## Add an action to an endpoint

`PATCH /v1/webhooks/{id}`

`filter` is replaced as a whole: send the full list. `{"actions": []}` removes the filter, and the endpoint receives every click again. Reference: [Update a webhook](https://www.zapsmtp.xyz/docs/webhooks/update-webhook/).

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Webhook id

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "filter": {
    "actions": [
      "confirm_order",
      "cancel_order"
    ]
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10",
  "url": "https://acme.com/hooks/confirm-order",
  "events": [
    "email.clicked"
  ],
  "enabled": true,
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": [
      "confirm_order",
      "cancel_order"
    ]
  },
  "disabled_reason": null,
  "created_at": "2026-10-27T08:00:00Z"
}
```

## The catalogue

The *Actions* page in the dashboard and `GET /actions` show each action with its description, clicks over 7 and 30 days, unique clickers over 30 days, the last click, how many templates use it and the webhook endpoints filtered on it. `declared: false` marks an action that links use but nobody described. In the dashboard, *New action* can also create a webhook for it, or add it to an existing endpoint’s filter, in the same step.

Deleting an action removes only its description. Links that name it keep working, and webhooks filtered on it keep receiving its clicks.

## Read the catalogue

`GET /v1/actions`

Every action the account declared, every action links named in the last 30 days, and every action a template or webhook filter uses, with activity. Reference: [List actions](https://www.zapsmtp.xyz/docs/actions/list-actions/).

Requires a full-access key.

```bash
curl 'https://zapsmtp.xyz/v1/actions' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "action",
      "name": "confirm_order",
      "description": "Customer confirms the order from the receipt",
      "declared": true,
      "created_at": "2026-10-24T09:12:00Z",
      "updated_at": "2026-10-24T09:12:00Z",
      "clicks_7d": 42,
      "clicks_30d": 180,
      "unique_clickers_30d": 171,
      "last_click_at": "2026-10-27T08:41:05Z",
      "templates": 1,
      "webhooks": [
        "019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10"
      ]
    },
    {
      "object": "action",
      "name": "track_parcel",
      "description": "",
      "declared": false,
      "created_at": null,
      "updated_at": null,
      "clicks_7d": 12,
      "clicks_30d": 64,
      "unique_clickers_30d": 60,
      "last_click_at": "2026-10-26T19:02:44Z",
      "templates": 2,
      "webhooks": []
    }
  ]
}
```

## Describe an action

`POST /v1/actions`

Optional: a link works with any valid name. Declaring one gives it a description your team sees in the dashboard. `PATCH /actions/{name}` changes it later, and declares an action that links already use. Reference: [Declare an action](https://www.zapsmtp.xyz/docs/actions/create-action/).

Requires a full-access live key; test keys get 403 test_key_restricted.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/actions' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "confirm_order",
  "description": "Customer confirms the order from the receipt"
}'
```

**Response `201 Created`**

```json
{
  "object": "action",
  "name": "confirm_order",
  "description": "Customer confirms the order from the receipt",
  "declared": true,
  "created_at": "2026-10-24T09:12:00Z",
  "updated_at": "2026-10-24T09:12:00Z",
  "clicks_7d": 0,
  "clicks_30d": 0,
  "unique_clickers_30d": 0,
  "last_click_at": null,
  "templates": 0,
  "webhooks": []
}
```

---

# Tracking and analytics

Source: https://www.zapsmtp.xyz/docs/analytics/

Every recipient of every email gets its own trail of events: accepted, delayed, delivered or bounced, then opened, clicked or reported as spam. Read that trail per email, list and filter emails, pull aggregated metrics with rates, or receive each event as a webhook the moment it happens.

![The dashboard overview: sent, delivered, bounced and complaint counts with delivery, open and click rates and a chart of the last days](https://www.zapsmtp.xyz/docs/img/overview-light.webp)

The dashboard’s overview is built from the same data as the API calls on this page.

> Analytics cover live traffic. Mail sent with test keys (`zap_test_…`) appears in the email list and timelines (filter it with `mode=test`) and fires webhooks with `test: true`, but is left out of `/stats` and `/metrics`.

## The life of a recipient

Statuses belong to recipients, not to emails: an email to three people has three trails. Each event changes the recipient’s status to the event’s status, so the status you read is always the *latest* event, not the “best” one. A recipient who opened a delivered email shows `opened`; one who later reports it as spam shows `complained`.

A typical trail is `queued` → `delivered` → `opened` → `clicked`. A slow receiver adds one or more `delivery_delayed` before `delivered` or `bounced`. An address on your suppression list goes straight to `suppressed` and is never sent.

**Statuses and events**

- **Status (Webhook event)**: **Timeline `type`** · **Meaning** · **Ends delivery**
- **`queued` (email.sent)**: `Reception` · Accepted for delivery. One per recipient. · No
- **`delivery_delayed` (email.delivery_delayed)**: `TransientFailure` · The receiving server answered with a temporary failure (4xx) or could not be reached. We keep retrying; this can repeat. · No
- **`delivered` (email.delivered)**: `Delivery` · The receiving server accepted the message (2xx). Its reply is in response. · Yes
- **`bounced` (email.bounced)**: `Bounce, Expiration, OOB, AdminBounce` · Permanently rejected, retries ran out (subType Expired), the message was withdrawn from the queue, or a bounce email arrived later for a message that had been delivered (OOB). · Yes
- **`failed` (email.failed)**: `Rejection` · Rejected before sending. A scheduled email also fails when its account or key is no longer valid at send time. · Yes
- **`suppressed` (email.suppressed)**: `Suppressed` · Not sent: the address is on your suppression list. · Yes
- **`complained` (email.complained)**: `Feedback` · The recipient marked the message as spam. The address is added to your suppressions. · After delivery
- **`opened` (email.opened)**: `Open` · The tracking pixel loaded. Open tracking only; can repeat. · After delivery
- **`clicked` (email.clicked)**: `Click` · A tracked link was followed. Click tracking only; can repeat. · After delivery

**Final outcomes.** `delivered`, `bounced`, `failed` and `suppressed` end the delivery attempt: no more retries follow. After `delivered` the trail can still grow: opens and clicks, a complaint, or a late `bounced` when the receiving server accepts the message first and sends a bounce email afterwards. `queued` and `delivery_delayed` are never final.

**Bounce details.** Bounced, delayed, failed and suppressed events carry a classification: `Permanent`, `Transient` or `Undetermined` with a `subType` such as `MailboxDoesNotExist` or `Expired`. Only permanent mailbox- or domain-level failures and complaints add the address to your suppressions. The full list is in [Bounce classification](https://www.zapsmtp.xyz/docs/testing/#bounces), and every scenario can be produced on demand with [simulator addresses](https://www.zapsmtp.xyz/docs/testing/).

**Two more statuses.** `scheduled` is not an event: `GET /emails?status=scheduled` lists sends still waiting for their `scheduled_at`. With reply tracking on, an answer to an email appears in its log as `replied` and fires `email.replied`.

## Open tracking

With open tracking on, ZapSMTP adds a 1×1 transparent image just before `</body>` of the HTML part (or at its end when there is no `</body>`). The image URL carries a signed token naming the email and recipient. When a mail client loads it, the recipient gets an `opened` event and you get `email.opened` with `data.open.ip_address` and `data.open.user_agent`, plus `data.open.machine: true` when the open came from Apple’s privacy proxy. The image is served with no-cache headers, so a client that loads it again later records another open (repeats within 10 minutes from the same network are folded, see below).

- **HTML only.** A text-only email has nowhere to put a pixel, so it records no opens.
- **Images off means no open.** A recipient who reads the email without loading images is not counted. Open counts are a lower bound in that direction.
- **Repeats from the same network are folded.** The same pixel loaded again from the same IP address (the same /64 for IPv6) within 10 minutes is served but not counted again, so a client that refreshes or a scanner that retries does not inflate opens or send duplicate webhooks.

> **Apple Mail Privacy Protection.** Apple Mail users who turn on Mail Privacy Protection have every remote image fetched through Apple’s proxy, usually soon after delivery and whether or not the person reads the email. ZapSMTP recognises these fetches by the bare `Mozilla/5.0` user agent Apple’s proxy sends and marks their `email.opened` webhooks with `data.open.machine: true`. They still count as opens, and are split out everywhere: `GET /v1/metrics` returns `human_opened` and `human_open_rate` next to `opened` and `open_rate`, `GET /v1/stats/breakdown` returns `human_unique_opens` and `machine_opens`, an email’s open events carry `machine: true`, and the dashboard’s open rate is the human one. An email that a person opened after the proxy did counts as opened by a person. Use the human figures, or clicks, replies and conversions in your own app, for decisions that matter, such as removing inactive subscribers.

## Click tracking

With click tracking on, every `<a>` whose `href` is an absolute `http://` or `https://` URL is rewritten to a link on our tracking host. The original destination, the email and the recipient are inside a token signed with HMAC-SHA256, so the redirector only ever sends people to URLs that were in your email: it cannot be turned into an open redirect, and a token that was tampered with is answered with 404. A click records `clicked`, sends `email.clicked` with `data.click.link`, `ip_address` and `user_agent`, and redirects the browser to the destination with HTTP 302.

- HTML entities in the `href` (`&amp;`, `&#38;`) are decoded first, so people land exactly where the browser would have sent them.
- `mailto:`, `tel:`, relative links and anchors are left alone; links in the plain-text part are not rewritten.
- A repeated click on the same link from the same network within 10 minutes still redirects but is not counted again.
- Tracked links work for 365 days after the email was sent. After that they answer 410 *Gone* instead of redirecting.
- Your unsubscribe link, `{{{zap:unsubscribe_url}}}`, is filled in after click tracking and is never wrapped.
- A link marked with a [click action](https://www.zapsmtp.xyz/docs/click-actions/) (`data-zap-action`) is tracked even when click tracking is off, and its `email.clicked` carries `click.action`.

### Keep a link out of tracking

Add the `data-zap-notrack` attribute to any link that should go out untouched: password resets, magic sign-in links, links your security team wants to be readable, or links whose exact URL a receiver checks. The attribute can stand anywhere in the tag and is left in the sent HTML, where mail clients ignore it.

**Opting links out of click tracking**

```html
<!-- tracked: rewritten through the click redirector -->
<a href="https://acme.com/orders/A-1042">Track your order</a>

<!-- not tracked: data-zap-notrack may come before or after href -->
<a data-zap-notrack href="https://acme.com/account/reset?t=8f2c">Reset your password</a>

<!-- never rewritten: not an http(s) link -->
<a href="mailto:support@acme.com">Write to us</a>

<!-- your unsubscribe link is filled in after tracking and never wrapped -->
<a href="{{{zap:unsubscribe_url}}}">Unsubscribe</a>
```

## Tracking settings

Tracking is decided per email, from two layers:

1. **The domain default.** Each sending domain has `open_tracking` and `click_tracking`, both off when the domain is added. Set them on the domain page in the dashboard or with [PATCH /domains/{id}](https://www.zapsmtp.xyz/docs/domains/update-domain/). They apply to every email whose From address is on that domain.
2. **The per-send override.** `tracking` on [POST /emails](https://www.zapsmtp.xyz/docs/emails/send-email/) and on each item of [a batch](https://www.zapsmtp.xyz/docs/emails/send-batch/) takes `opens` and `clicks` (and `replies` for reply tracking). A field you set wins over the domain; a field you leave out keeps the domain default.

## Set a domain’s tracking defaults

`PATCH /v1/domains/{id}`

Every email from this domain is tracked unless the send says otherwise. New domains start with both off.

Requires a full-access live key; test keys get 403 test_key_restricted.

Fields left out keep their value. The response is the domain, as in `GET /domains/{id}`.

Reply tracking: each tracked email gets its own signed Reply-To, e.g. `r1-<email id>.<signature>@reply.acme.com`, so replies come back tied to the exact email. Each reply fires `email.replied` (classified as a person, out-of-office, unsubscribe request, bounce…) and arrives as a received email; only replies a person wrote are forwarded. The display name is kept (the Reply-To’s name, else the From name). One reply address takes at most 100 replies a day.

### Path parameters

- `id` (string, required): Domain id

### Body parameters

- `open_tracking` (boolean): Default open tracking for emails from this domain.
- `click_tracking` (boolean): Default click tracking for emails from this domain.
- `tls` (string): Outbound encryption: `opportunistic` (default: encrypt whenever offered), `required` (TLS or no delivery) or `verified` (TLS with a valid certificate). Limits: other values → 422 invalid_parameter "tls must be opportunistic, required or verified"
- `reply_tracking` (boolean): Default reply tracking for emails from this domain (override per email with `tracking.replies`). Limits: true without a reply_domain → 422 invalid_parameter "reply_tracking needs a reply_domain: add an inbound domain such as reply.<domain> first"
- `reply_domain` (string): Where tracked reply addresses live: one of your inbound domains, MX-verified, equal to this domain or a subdomain of it (e.g. `reply.acme.com`). `""` clears it. Limits: otherwise 422 invalid_parameter
- `reply_forward_to` (string): Where replies a person wrote are forwarded: a plain address on one of your verified domains, or a confirmed forward destination; never a receiving address. `""` (default) forwards to the email’s first Reply-To, else its From. Limits: otherwise 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `invalid_parameter` (HTTP 422): bad tls; reply_domain not one of your inbound domains, not this domain or a subdomain of it, or without a verified MX record; reply_forward_to not a plain address, a receiving address, or not on a verified domain / confirmed forward destination; reply_tracking without a reply_domain

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "open_tracking": true,
  "click_tracking": true
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": true,
  "open_tracking": true,
  "click_tracking": true,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": true,
  "reply_domain": "reply.acme.com",
  "reply_forward_to": "support@acme.com",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T14:05:00Z",
  "verified_at": "2026-10-21T14:05:00Z",
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "verified"
    }
  ]
}
```

## Turn tracking on for one email

`POST /v1/emails`

tracking overrides the From domain’s defaults for this email only. Leave a field out to keep the domain default.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Your October invoice",
  "html": "<p>Your invoice is ready: <a href=\"https://acme.com/invoices/A-1042\">view it</a>.</p><p><a href=\"https://acme.com/account/reset?t=8f2c\" data-zap-notrack>Reset your password</a></p>",
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "tags": [
    {
      "name": "category",
      "value": "invoice"
    }
  ],
  "metadata": {
    "invoice_id": "A-1042"
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Turn tracking off for one email

`POST /v1/emails`

A password reset from a domain that tracks by default: no pixel, no rewritten links.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <security@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Reset your password",
  "html": "<p><a href=\"https://acme.com/account/reset?t=8f2c\">Choose a new password</a></p>",
  "tracking": {
    "opens": false,
    "clicks": false
  },
  "tags": [
    {
      "name": "category",
      "value": "password_reset"
    }
  ]
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

> **One recipient per email for exact attribution.** The pixel and links are added once per message, so their token can name a single recipient. When an email has several recipients, opens and clicks are attributed to the first `To` address, whoever actually opened it. To know exactly who opened and clicked, send one email per recipient; [POST /emails/batch](https://www.zapsmtp.xyz/docs/emails/send-batch/) takes up to 100 at once.

Open and click tracking applies to the HTML of emails sent through the HTTP API, templates included. Delivery, bounce and complaint events are recorded for every email, tracked or not, including mail sent over [SMTP](https://www.zapsmtp.xyz/docs/smtp/).

## One email’s timeline

[GET /emails/{id}](https://www.zapsmtp.xyz/docs/emails/get-email/) returns the email with `recipients` (each with its latest `status`, `updated_at` and the last server `response`) and `events` in time order. Each event has the public `status` from the table above and a `type` naming what happened. Delivery attempts add `response_code`, `response`, `attempts`, the `mx` host and `peer_addr` it talked to, and the `tls` version and cipher. Failures add `bounce_type` and `bounce_subtype`. Opens and clicks add `user_agent`; for a click, `response` holds the link that was followed.

## Read one email’s timeline

`GET /v1/emails/{id}`

Per-recipient status plus every event in order: the remote server’s reply, MX host, IP, TLS, attempts and, for opens and clicks, the user agent.

Requires a full-access key.

Only data inside the plan's log retention is visible. metadata may be null.

### Path parameters

- `id` (string, required): Email id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found (events can take a few seconds to appear)

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "from": "Acme <hello@acme.com>",
  "subject": "Your receipt",
  "created_at": "2026-10-21T15:04:10.902Z",
  "recipients": [
    {
      "email": "jane@example.org",
      "status": "delivered",
      "updated_at": "2026-10-21T15:04:12.381Z",
      "response": "250 2.0.0 OK 1761059052 x7si123"
    }
  ],
  "events": [
    {
      "type": "Reception",
      "status": "queued",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:10.902Z",
      "attempts": 0
    },
    {
      "type": "Delivery",
      "status": "delivered",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:12.381Z",
      "response_code": 250,
      "response": "250 2.0.0 OK 1761059052 x7si123",
      "attempts": 1,
      "mx": "gmail-smtp-in.l.google.com.",
      "peer_addr": "142.250.153.27",
      "tls": "TLSv1.3 TLS_AES_256_GCM_SHA384",
      "egress_source": "ip-1"
    }
  ],
  "stream": "transactional",
  "test": false,
  "metadata": {
    "order_id": "A-1042"
  }
}
```

![One email in the dashboard: each recipient’s status and the event timeline with the receiving server’s reply, MX host, IP and TLS version](https://www.zapsmtp.xyz/docs/img/email-detail-light.webp)

The same timeline in the dashboard, under Emails.

The email id is the `id` returned by the send call. Keep it next to your own record (order, user, ticket) or put your own id in `metadata` so you can find the email later without storing ours. Emails are visible for your plan’s log retention (`plan.retention_days` in usage).

## List and filter emails

[GET /emails](https://www.zapsmtp.xyz/docs/emails/list-emails/) lists emails newest first, one item per email with `last_status`: the status of the email’s most recent event across all recipients.

**Filters**

- **`status`**: Latest status: `queued`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `failed`, `opened`, `clicked`, `suppressed`, or `scheduled` for waiting sends. Because it is the *latest* status, `status=delivered` leaves out delivered emails that were later opened; ask for `opened` and `clicked` too when you mean “reached the inbox”.
- **`q`**: Case-insensitive substring of a recipient or the subject, or an exact email id.
- **`metadata[key]`**: Exact match on a metadata value. Repeat for several keys; all must match.
- **`stream`**: `transactional` or `broadcast`.
- **`mode`**: `live` or `test`.
- **`days`**: Look-back window, 1–90 days, default 30, always capped by your plan’s retention.
- **`after`, `before`**: An email id or an RFC 3339 time. Together they give a date range; `before` with the last id of a page is the cursor for the next page.
- **`limit`**: 1–100, default 20.

The list has no tag filter: tags are for aggregated metrics and webhooks. To find individual emails, put the identifiers you will search by in `metadata`.

## Emails that bounced this week

`GET /v1/emails`

status matches the latest event of the email.

Requires a full-access key.

Use the last item's id as before= for the next page. metadata may be null when the email has none. last_status and last_event carry the same value.

### Query parameters

- `limit` (integer): 1-100; out-of-range values fall back to 20. Default `20`.
- `before` (string): Cursor: an email id (UUIDv7) or RFC 3339 time; returns emails accepted before it. An email id gives an exact page boundary. Limits: 422 invalid_parameter "before must be an email id or RFC 3339 time"
- `after` (string): Email id or RFC 3339 time; only emails created after it (still newest first). Limits: 422 invalid_parameter "after must be an email id or RFC 3339 time"
- `status` (string): Filter by latest status. status=scheduled lists pending scheduled sends instead (different item shape, ordered by scheduled time ascending, has_more always false, other filters/cursors ignored). One of `queued`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `failed`, `opened`, `clicked`, `replied`, `suppressed`, `scheduled`.
- `q` (string): Case-insensitive substring of a recipient or subject, or an exact email id.
- `days` (integer): Look-back window in days, 1-90 (other values ignored). Always capped by the plan's log retention. Default `30`.
- `stream` (string): One of `transactional`, `broadcast`.
- `mode` (string): Filter live or test-mode (sandbox) traffic; other values ignored. One of `live`, `test`.
- `metadata[<key>]` (string): Exact match on a metadata value, e.g. metadata[order_id]=A-1042. Repeatable for several keys.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): bad before/after

```bash
curl 'https://zapsmtp.xyz/v1/emails?status=bounced&days=7&limit=50' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "email",
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "from": "Acme <hello@acme.com>",
      "subject": "Your receipt",
      "to": [
        "jane@example.org"
      ],
      "last_status": "delivered",
      "last_event": "delivered",
      "created_at": "2026-10-21T15:04:10.902Z",
      "stream": "transactional",
      "test": false,
      "metadata": {
        "order_id": "A-1042"
      }
    }
  ]
}
```

## Find the emails of one order

`GET /v1/emails`

Exact match on a metadata value. Repeat metadata[...] to require several keys.

Requires a full-access key.

Use the last item's id as before= for the next page. metadata may be null when the email has none. last_status and last_event carry the same value.

### Query parameters

- `limit` (integer): 1-100; out-of-range values fall back to 20. Default `20`.
- `before` (string): Cursor: an email id (UUIDv7) or RFC 3339 time; returns emails accepted before it. An email id gives an exact page boundary. Limits: 422 invalid_parameter "before must be an email id or RFC 3339 time"
- `after` (string): Email id or RFC 3339 time; only emails created after it (still newest first). Limits: 422 invalid_parameter "after must be an email id or RFC 3339 time"
- `status` (string): Filter by latest status. status=scheduled lists pending scheduled sends instead (different item shape, ordered by scheduled time ascending, has_more always false, other filters/cursors ignored). One of `queued`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `failed`, `opened`, `clicked`, `replied`, `suppressed`, `scheduled`.
- `q` (string): Case-insensitive substring of a recipient or subject, or an exact email id.
- `days` (integer): Look-back window in days, 1-90 (other values ignored). Always capped by the plan's log retention. Default `30`.
- `stream` (string): One of `transactional`, `broadcast`.
- `mode` (string): Filter live or test-mode (sandbox) traffic; other values ignored. One of `live`, `test`.
- `metadata[<key>]` (string): Exact match on a metadata value, e.g. metadata[order_id]=A-1042. Repeatable for several keys.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): bad before/after

```bash
curl 'https://zapsmtp.xyz/v1/emails?metadata%5Border_id%5D=A-1042' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "email",
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "from": "Acme <hello@acme.com>",
      "subject": "Your receipt",
      "to": [
        "jane@example.org"
      ],
      "last_status": "delivered",
      "last_event": "delivered",
      "created_at": "2026-10-21T15:04:10.902Z",
      "stream": "transactional",
      "test": false,
      "metadata": {
        "order_id": "A-1042"
      }
    }
  ]
}
```

## Broadcast mail in a time range

`GET /v1/emails`

after and before take an email id or an RFC 3339 time; the window is still capped by days and your plan’s retention.

Requires a full-access key.

Use the last item's id as before= for the next page. metadata may be null when the email has none. last_status and last_event carry the same value.

### Query parameters

- `limit` (integer): 1-100; out-of-range values fall back to 20. Default `20`.
- `before` (string): Cursor: an email id (UUIDv7) or RFC 3339 time; returns emails accepted before it. An email id gives an exact page boundary. Limits: 422 invalid_parameter "before must be an email id or RFC 3339 time"
- `after` (string): Email id or RFC 3339 time; only emails created after it (still newest first). Limits: 422 invalid_parameter "after must be an email id or RFC 3339 time"
- `status` (string): Filter by latest status. status=scheduled lists pending scheduled sends instead (different item shape, ordered by scheduled time ascending, has_more always false, other filters/cursors ignored). One of `queued`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `failed`, `opened`, `clicked`, `replied`, `suppressed`, `scheduled`.
- `q` (string): Case-insensitive substring of a recipient or subject, or an exact email id.
- `days` (integer): Look-back window in days, 1-90 (other values ignored). Always capped by the plan's log retention. Default `30`.
- `stream` (string): One of `transactional`, `broadcast`.
- `mode` (string): Filter live or test-mode (sandbox) traffic; other values ignored. One of `live`, `test`.
- `metadata[<key>]` (string): Exact match on a metadata value, e.g. metadata[order_id]=A-1042. Repeatable for several keys.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): bad before/after

```bash
curl 'https://zapsmtp.xyz/v1/emails?stream=broadcast&after=2026-10-20T00%3A00%3A00Z&before=2026-10-21T00%3A00%3A00Z&days=30&limit=100' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "email",
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "from": "Acme <hello@acme.com>",
      "subject": "Your receipt",
      "to": [
        "jane@example.org"
      ],
      "last_status": "delivered",
      "last_event": "delivered",
      "created_at": "2026-10-21T15:04:10.902Z",
      "stream": "transactional",
      "test": false,
      "metadata": {
        "order_id": "A-1042"
      }
    }
  ]
}
```

## Search by recipient or subject

`GET /v1/emails`

q is a case-insensitive substring of a recipient or the subject, or an exact email id.

Requires a full-access key.

Use the last item's id as before= for the next page. metadata may be null when the email has none. last_status and last_event carry the same value.

### Query parameters

- `limit` (integer): 1-100; out-of-range values fall back to 20. Default `20`.
- `before` (string): Cursor: an email id (UUIDv7) or RFC 3339 time; returns emails accepted before it. An email id gives an exact page boundary. Limits: 422 invalid_parameter "before must be an email id or RFC 3339 time"
- `after` (string): Email id or RFC 3339 time; only emails created after it (still newest first). Limits: 422 invalid_parameter "after must be an email id or RFC 3339 time"
- `status` (string): Filter by latest status. status=scheduled lists pending scheduled sends instead (different item shape, ordered by scheduled time ascending, has_more always false, other filters/cursors ignored). One of `queued`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `failed`, `opened`, `clicked`, `replied`, `suppressed`, `scheduled`.
- `q` (string): Case-insensitive substring of a recipient or subject, or an exact email id.
- `days` (integer): Look-back window in days, 1-90 (other values ignored). Always capped by the plan's log retention. Default `30`.
- `stream` (string): One of `transactional`, `broadcast`.
- `mode` (string): Filter live or test-mode (sandbox) traffic; other values ignored. One of `live`, `test`.
- `metadata[<key>]` (string): Exact match on a metadata value, e.g. metadata[order_id]=A-1042. Repeatable for several keys.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): bad before/after

```bash
curl 'https://zapsmtp.xyz/v1/emails?q=jane%40example.org&mode=live' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "email",
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "from": "Acme <hello@acme.com>",
      "subject": "Your receipt",
      "to": [
        "jane@example.org"
      ],
      "last_status": "delivered",
      "last_event": "delivered",
      "created_at": "2026-10-21T15:04:10.902Z",
      "stream": "transactional",
      "test": false,
      "metadata": {
        "order_id": "A-1042"
      }
    }
  ]
}
```

**Page through every result**

Node.js:

```javascript
// Every bounced email of the last 7 days, page by page.
const API = 'https://zapsmtp.xyz/v1';
const headers = { Authorization: `Bearer ${process.env.ZAP_API_KEY}` };

const all = [];
let before;
do {
  const q = new URLSearchParams({ status: 'bounced', days: '7', limit: '100', ...(before && { before }) });
  const res = await fetch(`${API}/emails?${q}`, { headers });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  const page = await res.json();
  all.push(...page.data);
  before = page.has_more ? page.data.at(-1).id : undefined;
} while (before);

console.log(all.length, 'bounced emails');
```

Python:

```python
# Every bounced email of the last 7 days, page by page.
import os, requests

API = "https://zapsmtp.xyz/v1"
H = {"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"}

emails, before = [], None
while True:
    params = {"status": "bounced", "days": 7, "limit": 100}
    if before:
        params["before"] = before
    r = requests.get(f"{API}/emails", headers=H, params=params, timeout=30)
    r.raise_for_status()
    page = r.json()
    emails += page["data"]
    if not page["has_more"]:
        break
    before = page["data"][-1]["id"]

print(len(emails), "bounced emails")
```

## Metrics

[GET /metrics](https://www.zapsmtp.xyz/docs/stats/metrics/) aggregates live mail over a period you choose, up to 400 days back, and returns `totals`, a `series` by hour or day and, with a `dimension`, one row per value in `groups`, busiest (most `sent`) first and at most 1,000 rows; there is no pagination, so with many tags the quietest ones are left out. Metrics are kept for 400 days whatever your plan’s log retention, so they are the source for long-term reporting.

**Parameters**

- **`from`, `to`**: RFC 3339; default the last 7 days. `to` is exclusive; at most 400 days apart. Data is kept in UTC hours, so `from` is rounded down to the start of its hour.
- **`granularity`**: `hour` (ranges up to 31 days) or `day` (UTC days). Default: `hour` up to 48 hours, else `day`. Buckets with no events are left out of `series`.
- **`dimension`**: `domain` (the From domain), `stream`, `provider` (the recipient’s mailbox provider: Gmail, Microsoft, Yahoo, Apple or Other) or `tag` (each `name=value`).
- **`domain`, `stream`, `provider`**: Filters; they combine with each other and with any dimension except `tag`.
- **`tag`**: One tag as `name=value`. Cannot be combined with `domain`, `stream` or `provider`, and groups only by `tag`.

**Counts and rates**

- **`sent`**: Recipients accepted (`queued`).
- **`delivered`, `bounced`, `complained`, `suppressed`, `failed`**: Recipients with that event.
- **`delayed`, `opened`, `clicked`**: Unique emails with at least one such event: a message opened five times counts once.
- **`delivery_rate`**: `delivered / sent`
- **`bounce_rate`**: `bounced / sent`
- **`complaint_rate`**: `complained / delivered`
- **`open_rate`**: `opened / delivered`
- **`human_open_rate`**: `human_opened / delivered`: leaves out emails that only Apple Mail Privacy Protection’s proxy opened
- **`click_rate`**: `clicked / delivered`

Rates are non-negative fractions, cut (not rounded) to four decimals: `0.0077` is 0.77%. They are not capped at 1 (see below). A rate whose denominator is 0 is `0`.

> **Events count when they happen.** Every event is counted in the hour it occurred, not the hour its email was sent. An email sent at 23:50 and delivered at 00:05 adds to `sent` on one day and to `delivered` on the next, and an open three days later counts on that day. Over a day or longer this evens out; over an hour or two, rates can drift and even exceed 1. Events are also processed asynchronously, so one can be recorded after the hour it belongs to is over: a recent past day can still grow slightly.

A few details of the groups: with `dimension=tag` an email with several tags appears in each tag’s group, while `totals` and `series` still count it once. Out-of-band bounces (bounce emails that arrive after delivery) carry no sending domain and are grouped under an empty `value`. Opens and clicks are counted under their email’s domain, stream and tags, but an email whose encoded tags exceed 200 bytes has its opens and clicks left out of tag metrics.

## Deliverability by mailbox provider

`GET /v1/metrics`

Gmail, Microsoft, Yahoo, Apple and Other, busiest first, with a daily series.

Requires a full-access key.

Counts are recipients, except `delayed`, `opened` and `clicked`: unique emails. Delivery and bounce rates are of `sent`; complaint, open and click rates of `delivered`. Test-mode mail is excluded. Kept for 400 days.

An out-of-band bounce (a later bounce email from the remote server) has no sending domain: it is grouped under an empty `value`.

Totals and the series count each email once whatever the dimension; with `dimension=tag` an email with several tags appears in each of its tags' groups.

### Query parameters

- `from` (string): RFC 3339 start. At most 400 days before `to`. Default `7 days ago`.
- `to` (string): RFC 3339 end (exclusive). Default `now`.
- `granularity` (string): `hour` (ranges up to 31 days) or `day` for `series`. Default `hour up to 48 hours, else day`.
- `dimension` (string): `domain`, `stream`, `tag` or `provider`: adds `groups`, one row per value, busiest first.
- `domain` (string): Only this sending (From) domain.
- `stream` (string): `transactional` or `broadcast`.
- `provider` (string): Gmail, Microsoft, Yahoo, Apple or Other.
- `tag` (string): Only emails with this tag, as `name=value`. Cannot be combined with domain, stream or provider, and groups only by `tag`.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): Bad time, range, granularity or dimension, or a tag combined with another filter.

```bash
curl 'https://zapsmtp.xyz/v1/metrics?dimension=provider&from=2026-10-01T00%3A00%3A00Z&to=2026-10-26T00%3A00%3A00Z&granularity=day' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "metrics",
  "from": "2026-10-18T00:00:00Z",
  "to": "2026-10-25T00:00:00Z",
  "granularity": "day",
  "dimension": "domain",
  "totals": {
    "sent": 12400,
    "delivered": 12210,
    "bounced": 95,
    "delayed": 3,
    "complained": 4,
    "opened": 4380,
    "human_opened": 2409,
    "clicked": 912,
    "suppressed": 2,
    "failed": 0,
    "delivery_rate": 0.9847,
    "bounce_rate": 0.0077,
    "complaint_rate": 0.0003,
    "open_rate": 0.3587,
    "human_open_rate": 0.1972,
    "click_rate": 0.0747
  },
  "series": [
    {
      "time": "2026-10-18T00:00:00Z",
      "sent": 1700,
      "delivered": 1676,
      "bounced": 14,
      "delayed": 3,
      "complained": 1,
      "opened": 601,
      "human_opened": 331,
      "clicked": 120,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9859,
      "bounce_rate": 0.0082,
      "complaint_rate": 0.0006,
      "open_rate": 0.3586,
      "human_open_rate": 0.1974,
      "click_rate": 0.0716
    }
  ],
  "groups": [
    {
      "value": "acme.com",
      "sent": 9800,
      "delivered": 9668,
      "bounced": 70,
      "delayed": 3,
      "complained": 3,
      "opened": 3540,
      "human_opened": 1947,
      "clicked": 760,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9865,
      "bounce_rate": 0.0071,
      "complaint_rate": 0.0003,
      "open_rate": 0.3662,
      "human_open_rate": 0.2013,
      "click_rate": 0.0786
    },
    {
      "value": "news.acme.com",
      "sent": 2600,
      "delivered": 2542,
      "bounced": 25,
      "delayed": 3,
      "complained": 1,
      "opened": 840,
      "human_opened": 462,
      "clicked": 152,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9777,
      "bounce_rate": 0.0096,
      "complaint_rate": 0.0004,
      "open_rate": 0.3304,
      "human_open_rate": 0.1817,
      "click_rate": 0.0598
    }
  ]
}
```

## Metrics for one tag

`GET /v1/metrics`

tag=name=value. It cannot be combined with domain, stream or provider.

Requires a full-access key.

Counts are recipients, except `delayed`, `opened` and `clicked`: unique emails. Delivery and bounce rates are of `sent`; complaint, open and click rates of `delivered`. Test-mode mail is excluded. Kept for 400 days.

An out-of-band bounce (a later bounce email from the remote server) has no sending domain: it is grouped under an empty `value`.

Totals and the series count each email once whatever the dimension; with `dimension=tag` an email with several tags appears in each of its tags' groups.

### Query parameters

- `from` (string): RFC 3339 start. At most 400 days before `to`. Default `7 days ago`.
- `to` (string): RFC 3339 end (exclusive). Default `now`.
- `granularity` (string): `hour` (ranges up to 31 days) or `day` for `series`. Default `hour up to 48 hours, else day`.
- `dimension` (string): `domain`, `stream`, `tag` or `provider`: adds `groups`, one row per value, busiest first.
- `domain` (string): Only this sending (From) domain.
- `stream` (string): `transactional` or `broadcast`.
- `provider` (string): Gmail, Microsoft, Yahoo, Apple or Other.
- `tag` (string): Only emails with this tag, as `name=value`. Cannot be combined with domain, stream or provider, and groups only by `tag`.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): Bad time, range, granularity or dimension, or a tag combined with another filter.

```bash
curl 'https://zapsmtp.xyz/v1/metrics?tag=category%3Dinvoice&from=2026-10-19T00%3A00%3A00Z&to=2026-10-26T00%3A00%3A00Z' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "metrics",
  "from": "2026-10-18T00:00:00Z",
  "to": "2026-10-25T00:00:00Z",
  "granularity": "day",
  "dimension": "domain",
  "totals": {
    "sent": 12400,
    "delivered": 12210,
    "bounced": 95,
    "delayed": 3,
    "complained": 4,
    "opened": 4380,
    "human_opened": 2409,
    "clicked": 912,
    "suppressed": 2,
    "failed": 0,
    "delivery_rate": 0.9847,
    "bounce_rate": 0.0077,
    "complaint_rate": 0.0003,
    "open_rate": 0.3587,
    "human_open_rate": 0.1972,
    "click_rate": 0.0747
  },
  "series": [
    {
      "time": "2026-10-18T00:00:00Z",
      "sent": 1700,
      "delivered": 1676,
      "bounced": 14,
      "delayed": 3,
      "complained": 1,
      "opened": 601,
      "human_opened": 331,
      "clicked": 120,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9859,
      "bounce_rate": 0.0082,
      "complaint_rate": 0.0006,
      "open_rate": 0.3586,
      "human_open_rate": 0.1974,
      "click_rate": 0.0716
    }
  ],
  "groups": [
    {
      "value": "acme.com",
      "sent": 9800,
      "delivered": 9668,
      "bounced": 70,
      "delayed": 3,
      "complained": 3,
      "opened": 3540,
      "human_opened": 1947,
      "clicked": 760,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9865,
      "bounce_rate": 0.0071,
      "complaint_rate": 0.0003,
      "open_rate": 0.3662,
      "human_open_rate": 0.2013,
      "click_rate": 0.0786
    },
    {
      "value": "news.acme.com",
      "sent": 2600,
      "delivered": 2542,
      "bounced": 25,
      "delayed": 3,
      "complained": 1,
      "opened": 840,
      "human_opened": 462,
      "clicked": 152,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9777,
      "bounce_rate": 0.0096,
      "complaint_rate": 0.0004,
      "open_rate": 0.3304,
      "human_open_rate": 0.1817,
      "click_rate": 0.0598
    }
  ]
}
```

## Compare tags

`GET /v1/metrics`

One group per name=value pair, busiest first, up to 1,000 groups. An email with several tags counts in each of them.

Requires a full-access key.

Counts are recipients, except `delayed`, `opened` and `clicked`: unique emails. Delivery and bounce rates are of `sent`; complaint, open and click rates of `delivered`. Test-mode mail is excluded. Kept for 400 days.

An out-of-band bounce (a later bounce email from the remote server) has no sending domain: it is grouped under an empty `value`.

Totals and the series count each email once whatever the dimension; with `dimension=tag` an email with several tags appears in each of its tags' groups.

### Query parameters

- `from` (string): RFC 3339 start. At most 400 days before `to`. Default `7 days ago`.
- `to` (string): RFC 3339 end (exclusive). Default `now`.
- `granularity` (string): `hour` (ranges up to 31 days) or `day` for `series`. Default `hour up to 48 hours, else day`.
- `dimension` (string): `domain`, `stream`, `tag` or `provider`: adds `groups`, one row per value, busiest first.
- `domain` (string): Only this sending (From) domain.
- `stream` (string): `transactional` or `broadcast`.
- `provider` (string): Gmail, Microsoft, Yahoo, Apple or Other.
- `tag` (string): Only emails with this tag, as `name=value`. Cannot be combined with domain, stream or provider, and groups only by `tag`.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): Bad time, range, granularity or dimension, or a tag combined with another filter.

```bash
curl 'https://zapsmtp.xyz/v1/metrics?dimension=tag&from=2026-10-19T00%3A00%3A00Z&to=2026-10-26T00%3A00%3A00Z' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "metrics",
  "from": "2026-10-18T00:00:00Z",
  "to": "2026-10-25T00:00:00Z",
  "granularity": "day",
  "dimension": "domain",
  "totals": {
    "sent": 12400,
    "delivered": 12210,
    "bounced": 95,
    "delayed": 3,
    "complained": 4,
    "opened": 4380,
    "human_opened": 2409,
    "clicked": 912,
    "suppressed": 2,
    "failed": 0,
    "delivery_rate": 0.9847,
    "bounce_rate": 0.0077,
    "complaint_rate": 0.0003,
    "open_rate": 0.3587,
    "human_open_rate": 0.1972,
    "click_rate": 0.0747
  },
  "series": [
    {
      "time": "2026-10-18T00:00:00Z",
      "sent": 1700,
      "delivered": 1676,
      "bounced": 14,
      "delayed": 3,
      "complained": 1,
      "opened": 601,
      "human_opened": 331,
      "clicked": 120,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9859,
      "bounce_rate": 0.0082,
      "complaint_rate": 0.0006,
      "open_rate": 0.3586,
      "human_open_rate": 0.1974,
      "click_rate": 0.0716
    }
  ],
  "groups": [
    {
      "value": "acme.com",
      "sent": 9800,
      "delivered": 9668,
      "bounced": 70,
      "delayed": 3,
      "complained": 3,
      "opened": 3540,
      "human_opened": 1947,
      "clicked": 760,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9865,
      "bounce_rate": 0.0071,
      "complaint_rate": 0.0003,
      "open_rate": 0.3662,
      "human_open_rate": 0.2013,
      "click_rate": 0.0786
    },
    {
      "value": "news.acme.com",
      "sent": 2600,
      "delivered": 2542,
      "bounced": 25,
      "delayed": 3,
      "complained": 1,
      "opened": 840,
      "human_opened": 462,
      "clicked": 152,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9777,
      "bounce_rate": 0.0096,
      "complaint_rate": 0.0004,
      "open_rate": 0.3304,
      "human_open_rate": 0.1817,
      "click_rate": 0.0598
    }
  ]
}
```

## One domain, hour by hour, split by stream

`GET /v1/metrics`

Hourly series cover up to 31 days.

Requires a full-access key.

Counts are recipients, except `delayed`, `opened` and `clicked`: unique emails. Delivery and bounce rates are of `sent`; complaint, open and click rates of `delivered`. Test-mode mail is excluded. Kept for 400 days.

An out-of-band bounce (a later bounce email from the remote server) has no sending domain: it is grouped under an empty `value`.

Totals and the series count each email once whatever the dimension; with `dimension=tag` an email with several tags appears in each of its tags' groups.

### Query parameters

- `from` (string): RFC 3339 start. At most 400 days before `to`. Default `7 days ago`.
- `to` (string): RFC 3339 end (exclusive). Default `now`.
- `granularity` (string): `hour` (ranges up to 31 days) or `day` for `series`. Default `hour up to 48 hours, else day`.
- `dimension` (string): `domain`, `stream`, `tag` or `provider`: adds `groups`, one row per value, busiest first.
- `domain` (string): Only this sending (From) domain.
- `stream` (string): `transactional` or `broadcast`.
- `provider` (string): Gmail, Microsoft, Yahoo, Apple or Other.
- `tag` (string): Only emails with this tag, as `name=value`. Cannot be combined with domain, stream or provider, and groups only by `tag`.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): Bad time, range, granularity or dimension, or a tag combined with another filter.

```bash
curl 'https://zapsmtp.xyz/v1/metrics?domain=acme.com&dimension=stream&granularity=hour&from=2026-10-24T00%3A00%3A00Z&to=2026-10-26T00%3A00%3A00Z' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "metrics",
  "from": "2026-10-18T00:00:00Z",
  "to": "2026-10-25T00:00:00Z",
  "granularity": "day",
  "dimension": "domain",
  "totals": {
    "sent": 12400,
    "delivered": 12210,
    "bounced": 95,
    "delayed": 3,
    "complained": 4,
    "opened": 4380,
    "human_opened": 2409,
    "clicked": 912,
    "suppressed": 2,
    "failed": 0,
    "delivery_rate": 0.9847,
    "bounce_rate": 0.0077,
    "complaint_rate": 0.0003,
    "open_rate": 0.3587,
    "human_open_rate": 0.1972,
    "click_rate": 0.0747
  },
  "series": [
    {
      "time": "2026-10-18T00:00:00Z",
      "sent": 1700,
      "delivered": 1676,
      "bounced": 14,
      "delayed": 3,
      "complained": 1,
      "opened": 601,
      "human_opened": 331,
      "clicked": 120,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9859,
      "bounce_rate": 0.0082,
      "complaint_rate": 0.0006,
      "open_rate": 0.3586,
      "human_open_rate": 0.1974,
      "click_rate": 0.0716
    }
  ],
  "groups": [
    {
      "value": "acme.com",
      "sent": 9800,
      "delivered": 9668,
      "bounced": 70,
      "delayed": 3,
      "complained": 3,
      "opened": 3540,
      "human_opened": 1947,
      "clicked": 760,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9865,
      "bounce_rate": 0.0071,
      "complaint_rate": 0.0003,
      "open_rate": 0.3662,
      "human_open_rate": 0.2013,
      "click_rate": 0.0786
    },
    {
      "value": "news.acme.com",
      "sent": 2600,
      "delivered": 2542,
      "bounced": 25,
      "delayed": 3,
      "complained": 1,
      "opened": 840,
      "human_opened": 462,
      "clicked": 152,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9777,
      "bounce_rate": 0.0096,
      "complaint_rate": 0.0004,
      "open_rate": 0.3304,
      "human_open_rate": 0.1817,
      "click_rate": 0.0598
    }
  ]
}
```

## Quick stats

Three lighter endpoints answer “what happened in the last N hours” (1–720, default 24), within your plan’s retention. Unlike metrics, [GET /stats](https://www.zapsmtp.xyz/docs/stats/stats/) and [GET /stats/timeseries](https://www.zapsmtp.xyz/docs/stats/stats-timeseries/) count *events*, not unique emails: three opens of one email are 3 `opened`. The time series picks its bucket from the window: 1 minute up to 1 hour, 5 minutes up to 6 hours, 30 minutes up to 24 hours, 3 hours up to 7 days, 12 hours beyond.

[GET /stats/breakdown](https://www.zapsmtp.xyz/docs/stats/stats-breakdown/) adds delivery by mailbox provider (`delayed` there counts emails delayed at least once), bounce classes, engagement with both total and unique opens and clicks, and the most clicked links with total and unique clicks.

## Event counts for the last 24 hours

`GET /v1/stats`

Event counts by status over the last N hours (live traffic only).

Requires a full-access key.

Counts events (not unique emails), ordered by status name; test-mode traffic excluded.

### Query parameters

- `hours` (integer): 1-720; out-of-range falls back to 24. Default `24`.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/stats?hours=24' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "hours": 24,
  "data": [
    {
      "status": "bounced",
      "count": 12
    },
    {
      "status": "delivered",
      "count": 1840
    },
    {
      "status": "queued",
      "count": 1861
    }
  ]
}
```

## Events over the last 6 hours

`GET /v1/stats/timeseries`

5-minute buckets for windows up to 6 hours.

Requires a full-access key.

One point per (bucket, status); empty buckets are not emitted. Test-mode traffic excluded.

### Query parameters

- `hours` (integer): 1-720; out-of-range falls back to 24. Bucket size: <=1h → 60 s, <=6h → 300 s, <=24h → 1800 s, <=168h → 10800 s, otherwise 43200 s. Default `24`.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/stats/timeseries?hours=6' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "hours": 24,
  "bucket_seconds": 1800,
  "since": "2026-10-20T15:00:00Z",
  "data": [
    {
      "t": "2026-10-20T15:00:00Z",
      "status": "delivered",
      "count": 74
    },
    {
      "t": "2026-10-20T15:00:00Z",
      "status": "queued",
      "count": 75
    }
  ]
}
```

## Engagement and top links this week

`GET /v1/stats/breakdown`

Per-provider delivery, bounce classes, engagement and top clicked links.

Requires a full-access key.

Providers are Gmail, Microsoft, Yahoo, Apple and Other. `delayed` counts emails that were delayed at least once.

### Query parameters

- `hours` (integer): 1-720; out-of-range falls back to 24. Default `24`.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/stats/breakdown?hours=168' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "providers": [
    {
      "provider": "Gmail",
      "sent": 920,
      "delivered": 915,
      "bounced": 3,
      "delayed": 4,
      "complained": 1
    },
    {
      "provider": "Microsoft",
      "sent": 410,
      "delivered": 402,
      "bounced": 6,
      "delayed": 9,
      "complained": 0
    }
  ],
  "bounces": [
    {
      "classification": "InvalidRecipient",
      "count": 7
    }
  ],
  "engagement": {
    "delivered": 1840,
    "unique_opens": 702,
    "unique_clicks": 133,
    "opens": 1190,
    "clicks": 201,
    "human_unique_opens": 386,
    "machine_opens": 595
  },
  "top_links": [
    {
      "url": "https://acme.com/orders/A-1042",
      "clicks": 88,
      "unique": 80
    }
  ]
}
```

## Slice reports with tags and metadata

Both are set when you send and both come back on every webhook, but they serve different questions:

**Tags vs metadata**

- **`tags` ([{name, value}])**: Low-cardinality labels for **aggregates**: `category=receipt`, `campaign=oct-sale`, `template=welcome-v2`, `tenant=shop-17`. Names and values use letters, digits, `_` and `-`. Group by them with `/metrics?dimension=tag`, filter with `tag=name=value`. Webhooks carry them as `data.tags`.
- **`metadata` ({key: value})**: Your identifiers for **finding single emails**: `order_id`, `user_id`, `ticket`. Up to 10 keys, values up to 500 bytes (UTF-8). Filter with `/emails?metadata[key]=value`. Returned on `GET /emails`, `GET /emails/{id}` and webhooks.

Keep tag values to a bounded set: a tag per user or per order creates one metrics group per value and makes the breakdown useless. A good pattern is one tag for *what kind* of email it is and one for *which variant*, so an A/B test reads as two rows of `dimension=tag`.

## Webhooks: the real-time feed

Polling tells you what happened; webhooks tell you as it happens. Every event in the lifecycle table is delivered to your endpoint per recipient, signed, retried on failure, with the email’s tags, metadata and stream. Use them to update your own records (mark an address invalid on `email.bounced`, stop a drip on `email.complained`, credit a campaign on `email.clicked`) and to feed your own warehouse. Payloads, retries and signature verification are in [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/).

## Stream outcomes to your endpoint

`POST /v1/webhooks`

Pick the events your reports need; each one arrives per recipient within seconds.

Requires a full-access live key; test keys get 403 test_key_restricted.

The secret is also readable later via GET /webhooks/{id}.

To send clicks of one button to this endpoint: `{"events": ["email.clicked"], "filter": {"actions": ["confirm_order"]}}`. Endpoints always return `filter`, with an empty list when there is none.

### Body parameters

- `url` (string, required): Absolute https:// URL. Limits: 422 invalid_parameter "url must be an absolute https:// URL"
- `events` (string[]): Limits: unknown type → 422 invalid_parameter "unknown event type <x>; allowed: ..." One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `all event types`.
- `include_content` (boolean): `email.received` carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (`truncated: true`). Default `false`.
- `batch` (boolean): Send events up to 100 per request (or every second) as a JSON array, signed as one body; `Zap-Event-Id` is the batch id, each event keeps its own `id`. `email.received` with the full message still arrives alone. Default `false`.
- `filter` (object): Narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/); other event types are not affected. Empty or absent: every click. Default `{"actions": []}`.
  - `actions` (string[]): Action names (lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters). The endpoint then receives `email.clicked` only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/hooks/zapsmtp",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained",
    "email.opened",
    "email.clicked"
  ]
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-21T15:40:00Z",
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": []
  }
}
```

**Count events per tag as they arrive**

Node.js:

```javascript
// Count outcomes per tag and day from webhooks, in real time.
// Verify Zap-Signature first: see /docs/webhook-events/#signatures.
app.post('/hooks/zapsmtp', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verified(req)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  res.sendStatus(200); // answer fast, work afterwards

  if (event.data.test) return; // test keys
  const day = event.created_at.slice(0, 10);
  const tags = Object.entries(event.data.tags ?? {}).map(([k, v]) => `${k}=${v}`);
  for (const tag of tags.length ? tags : ['(none)']) {
    // dedupe on event.id: a retried delivery repeats it
    await db.query(
      `INSERT INTO webhook_counts (event_id, day, tag, type) VALUES ($1, $2, $3, $4)
       ON CONFLICT (event_id, tag) DO NOTHING`,
      [event.id, day, tag, event.type],
    );
  }
});
```

Python:

```python
# Count outcomes per tag and day from webhooks, in real time.
# Verify Zap-Signature first: see /docs/webhook-events/#signatures.
@app.post("/hooks/zapsmtp")
def zapsmtp():
    if not verified(request):
        abort(400)
    event = request.get_json()
    if event["data"].get("test"):  # test keys
        return "", 200
    day = event["created_at"][:10]
    tags = [f"{k}={v}" for k, v in (event["data"].get("tags") or {}).items()] or ["(none)"]
    with db:  # dedupe on event id: a retried delivery repeats it
        for tag in tags:
            db.execute("INSERT OR IGNORE INTO webhook_counts (event_id, day, tag, type) VALUES (?, ?, ?, ?)",
                       (event["id"], day, tag, event["type"]))
    return "", 200
```

## Build your own dashboard

The simplest durable setup is a daily job that pulls finished UTC days into your own store. Events count in the hour they happen, but a late-processed event can still land in a day that is already over, so don’t treat one pull as final: re-pull a rolling window of the last few days on every run and upsert by day. Re-runs are then safe and late events correct earlier rows. To backfill, run the same request for earlier days, up to 400 days back.

Store counts, not rates. A week’s bounce rate is `sum(bounced) / sum(sent)` over the week, not the average of seven daily rates. Summing days works for the additive counts (`sent`, `delivered`, `bounced`, `complained`, `suppressed`, `failed`) and the delivery, bounce and complaint rates built from them. `opened`, `clicked` and `delayed` are unique emails within the requested window: an email opened on Monday and again on Tuesday is in both daily rows, so summing days over-counts. For their weekly or monthly values, and for open and click rates over such a period, ask `/metrics` for the whole period at once.

**Upsert the last 3 days every day**

Node.js:

```javascript
// Run daily after 00:00 UTC, e.g. cron "15 0 * * *".
// Re-pulls the last 3 finished UTC days per tag (plus the total) and
// upserts them into Postgres, so late events correct earlier rows.
import pg from 'pg';

const API = 'https://zapsmtp.xyz/v1';
const headers = { Authorization: `Bearer ${process.env.ZAP_API_KEY}` };
const iso = (d) => d.toISOString().replace('.000Z', 'Z');
const LOOKBACK_DAYS = 3;
const db = new pg.Client(); // PG* environment variables
await db.connect();
await db.query(`CREATE TABLE IF NOT EXISTS zap_daily (
  day date, tag text, sent int, delivered int, bounced int, delayed int, complained int,
  opened int, clicked int, suppressed int, failed int, PRIMARY KEY (day, tag))`);

const today = new Date();
today.setUTCHours(0, 0, 0, 0);
for (let i = LOOKBACK_DAYS; i >= 1; i--) {
  const from = new Date(today.getTime() - i * 86_400_000);
  const to = new Date(from.getTime() + 86_400_000);
  const q = new URLSearchParams({ from: iso(from), to: iso(to), granularity: 'day', dimension: 'tag' });
  const res = await fetch(`${API}/metrics?${q}`, { headers });
  if (!res.ok) throw new Error(`metrics: ${res.status} ${await res.text()}`);
  const m = await res.json();
  // groups: at most 1,000, busiest first
  for (const [tag, c] of [['(all)', m.totals], ...m.groups.map((g) => [g.value, g])]) {
    await db.query(
      `INSERT INTO zap_daily VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
       ON CONFLICT (day, tag) DO UPDATE SET sent=$3, delivered=$4, bounced=$5, delayed=$6,
         complained=$7, opened=$8, clicked=$9, suppressed=$10, failed=$11`,
      [iso(from).slice(0, 10), tag, c.sent, c.delivered, c.bounced, c.delayed, c.complained,
       c.opened, c.clicked, c.suppressed, c.failed],
    );
  }
}
await db.end();
```

Python:

```python
# Run daily after 00:00 UTC. Re-pulls the last 3 finished UTC days per
# domain, stream, provider and tag and upserts them into SQLite (any SQL
# database works the same way), so late events correct earlier rows.
import datetime as dt, os, sqlite3, requests

API = "https://zapsmtp.xyz/v1"
H = {"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"}
fmt = lambda t: t.strftime("%Y-%m-%dT%H:%M:%SZ")
LOOKBACK_DAYS = 3

today = dt.datetime.now(dt.timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0)

db = sqlite3.connect("zapsmtp.db")
db.execute("""CREATE TABLE IF NOT EXISTS daily_metrics (
  day TEXT, dimension TEXT, value TEXT,
  sent INT, delivered INT, bounced INT, delayed INT, complained INT,
  opened INT, clicked INT, suppressed INT, failed INT,
  PRIMARY KEY (day, dimension, value))""")

cols = ("sent", "delivered", "bounced", "delayed", "complained", "opened", "clicked", "suppressed", "failed")
for i in range(LOOKBACK_DAYS, 0, -1):
    start = today - dt.timedelta(days=i)
    end = start + dt.timedelta(days=1)
    for dim in ("domain", "stream", "provider", "tag"):
        r = requests.get(f"{API}/metrics", headers=H, timeout=30,
                         params={"from": fmt(start), "to": fmt(end), "granularity": "day", "dimension": dim})
        r.raise_for_status()
        for g in r.json()["groups"]:  # at most 1,000 groups, busiest first
            db.execute("INSERT OR REPLACE INTO daily_metrics VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
                       (start.date().isoformat(), dim, g["value"], *(g[c] for c in cols)))
db.commit()
```

For a live view, combine the two sources: webhooks for the last minutes, the daily pull as the reconciled record. If a webhook was missed, the metrics still have the event.

## Alert on bounce and complaint rates

Mailbox providers judge you on bounces and spam complaints. Gmail and Yahoo ask bulk senders to keep the spam rate they see well below 0.3%, and a bounce rate above a few percent usually means a stale or bought list. The recipe below checks the last 24 hours per sending domain every hour and posts to a chat webhook of yours when a threshold is crossed. Tune the thresholds to your traffic; the minimum volume keeps a handful of emails from paging anyone.

**Hourly deliverability alert**

Node.js:

```javascript
// Run every hour. Alerts when a sending domain's bounce or complaint
// rate over the last 24 hours crosses a threshold.
const API = 'https://zapsmtp.xyz/v1';
const headers = { Authorization: `Bearer ${process.env.ZAP_API_KEY}` };
const MIN_SENT = 200;        // ignore tiny samples
const MAX_BOUNCE = 0.02;     // 2% of sent
const MAX_COMPLAINT = 0.001; // 0.1% of delivered

const to = new Date();
const from = new Date(to.getTime() - 24 * 3_600_000);
const q = new URLSearchParams({ dimension: 'domain', from: from.toISOString(), to: to.toISOString() });
const res = await fetch(`${API}/metrics?${q}`, { headers });
if (!res.ok) throw new Error(`metrics: ${res.status}`);
const { groups } = await res.json();

const problems = groups
  .filter((g) => g.value && g.sent >= MIN_SENT) // '' = out-of-band bounces with no domain
  .flatMap((g) => [
    g.bounce_rate > MAX_BOUNCE && `${g.value}: bounce rate ${(g.bounce_rate * 100).toFixed(2)}% (${g.bounced}/${g.sent})`,
    g.complaint_rate > MAX_COMPLAINT && `${g.value}: complaint rate ${(g.complaint_rate * 100).toFixed(3)}% (${g.complained}/${g.delivered})`,
  ])
  .filter(Boolean);

if (problems.length) {
  // your own chat webhook, pager or email
  await fetch(process.env.ALERT_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: 'ZapSMTP deliverability alert\n' + problems.join('\n') }),
  });
}
```

Python:

```python
# Run every hour. Alerts when a sending domain's bounce or complaint
# rate over the last 24 hours crosses a threshold.
import datetime as dt, os, requests

API = "https://zapsmtp.xyz/v1"
H = {"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"}
MIN_SENT, MAX_BOUNCE, MAX_COMPLAINT = 200, 0.02, 0.001

to = dt.datetime.now(dt.timezone.utc).replace(microsecond=0)
start = to - dt.timedelta(hours=24)
r = requests.get(f"{API}/metrics", headers=H, timeout=30, params={
    "dimension": "domain",
    "from": start.isoformat().replace("+00:00", "Z"),
    "to": to.isoformat().replace("+00:00", "Z"),
})
r.raise_for_status()

problems = []
for g in r.json()["groups"]:
    if not g["value"] or g["sent"] < MIN_SENT:  # '' = out-of-band bounces with no domain
        continue
    if g["bounce_rate"] > MAX_BOUNCE:
        problems.append(f"{g['value']}: bounce rate {g['bounce_rate']:.2%} ({g['bounced']}/{g['sent']})")
    if g["complaint_rate"] > MAX_COMPLAINT:
        problems.append(f"{g['value']}: complaint rate {g['complaint_rate']:.3%} ({g['complained']}/{g['delivered']})")

if problems:  # your own chat webhook, pager or email
    requests.post(os.environ["ALERT_WEBHOOK_URL"], timeout=10,
                  json={"text": "ZapSMTP deliverability alert\n" + "\n".join(problems)})
```

When an alert fires, narrow it down with `dimension=provider` for that domain (one provider rejecting you looks different from a bad list), list the bounced emails and read the `bounce_subtype` on their timelines, and check the domain’s [reputation](https://www.zapsmtp.xyz/docs/domains/domain-reputation/).

## Request logs

Events describe what happened to the mail; the request log describes what your code asked for. [GET /logs](https://www.zapsmtp.xyz/docs/logs/list-logs/) lists requests made with an API key that got past authentication. Not logged: the dashboard’s own calls, requests to `/logs` itself, and requests rejected before logging (an invalid key, or a test key attempting an account change). Each entry has method, path, status, duration, IP and user agent; [GET /logs/{id}](https://www.zapsmtp.xyz/docs/logs/get-log/) adds the request and response bodies. Every response carries `X-Request-Id`; for a logged request it is the id of its log entry: log it on your side and you can always find the exact request. Filter by exact status (`422`) or class (`4xx`), method, path prefix or API key.

## Send requests that failed validation

`GET /v1/logs`

Authenticated API-key requests; X-Request-Id on a logged response is its log id.

Requires a full-access key.

Requests made with API keys are logged; the dashboard’s own calls are not. The `X-Request-Id` header of every response is the id of its log entry.

### Query parameters

- `limit` (integer): 1–100. Default `20`.
- `before` (string): A log id: return older entries.
- `after` (string): A log id: return newer entries.
- `status` (string): An exact status (`422`) or a class: `2xx`, `4xx`, `5xx`.
- `method` (string): HTTP method.
- `path` (string): Path prefix, e.g. `/v1/emails`.
- `api_key_id` (string): Only requests made with this key.

### Errors

- `invalid_parameter` (HTTP 422): before or after is not a log id.

```bash
curl 'https://zapsmtp.xyz/v1/logs?status=422&method=POST&path=%2Fv1%2Femails&limit=20' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "log",
      "id": "019a1f31-5b2e-7c9d-8e4f-1a2b3c4d5e6f",
      "api_key_id": "019a1c11-2f3e-7a4b-9c5d-6e7f8a9b0c1d",
      "method": "POST",
      "path": "/v1/emails",
      "route": "/v1/emails",
      "status": 200,
      "duration_ms": 38,
      "ip": "203.0.113.7",
      "user_agent": "node-fetch/3.3",
      "created_at": "2026-10-22T15:04:10.902Z"
    }
  ]
}
```

## Usage

[GET /usage](https://www.zapsmtp.xyz/docs/logs/usage/) reports this month’s emails sent against your plan: `sent`, `included`, `limit` (`null` on paid plans without a spending cap), overage so far, and your plan with its `retention_days`, which bounds how far back the email list, timelines and `/stats` can see. The Free plan adds `daily_limit` and `sent_today`. Test-key mail does not count.

## This month’s usage

`GET /v1/usage`

This month’s sending against your plan: emails sent, included volume, limit, overage and, on the Free plan, today’s count.

Requires a full-access key.

`limit` is `null` on paid plans without a spending cap: email keeps flowing and extra volume is billed. The Free plan adds `daily_limit` and `sent_today`.

```bash
curl 'https://zapsmtp.xyz/v1/usage' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "usage",
  "month": "2026-10",
  "sent": 52310,
  "included": 50000,
  "limit": null,
  "overage_emails": 2310,
  "overage_cents": 196,
  "plan": {
    "id": "pro_50k",
    "name": "Pro 50k",
    "retention_days": 30
  }
}
```

---

# Receiving email

Source: https://www.zapsmtp.xyz/docs/inbound-guide/

Give your app an inbox. ZapSMTP accepts mail for your addresses, checks SPF, DKIM, DMARC and spam, strips the quoted reply, groups messages into conversations and tells your server with a signed `email.received` webhook. You answer through the API, from the right address, in the same thread.

![The Inbound page of the dashboard: receiving domains with their MX status, routes in priority order and the latest received emails with spam and authentication verdicts](https://www.zapsmtp.xyz/docs/img/inbound-light.webp)

Everything on this page is also in the dashboard under Inbound.

**The path of a received email**

- **1. Accept**: Mail for an unknown domain is refused during the SMTP conversation, so ZapSMTP never sends backscatter. On your domains every local part is accepted: `anything@`, `support+1234@`.
- **2. Check**: SPF, DKIM, DMARC and ARC are evaluated and the message gets a spam score. Clear spam is refused; likely spam is flagged (Spam).
- **3. Route**: Your routes decide: webhook, store, forward or reject.
- **4. Store**: The sender gets `250` only after the message is stored durably. Any trouble on our side answers with a temporary `451`, so the sending server retries and nothing is lost.
- **5. Notify**: `email.received`, plus `thread.created` or `thread.replied`, go to your webhook endpoints.

## Get an address

There are two kinds of inbound domain, and an account can have several of each.

> Setting up inbound changes your account, so the setup requests on this page (domains, routes, forward destinations, webhooks, `PATCH /threads`, spam reports, redeliver and erase) need a full-access live key. A test key gets `403 test_key_restricted` for them; it can still read and reply (test replies are never delivered).

**Inbound domains**

- **Managed**: A random name under `in.zapsmtp.xyz`, such as `k3f9x2m7q1.in.zapsmtp.xyz`. Ready the moment you create it, no DNS. Receive-only: you reply from one of your own sending domains.
- **Your own domain**: Any domain you verified for sending, or a subdomain of it (`support.acme.com`, `reply.acme.com`): that verification already proves you control its DNS. You add one MX record. Replies are checked against the exact From domain: to answer from `support@support.acme.com`, verify `support.acme.com` for sending too, or reply with a From on a domain you already verified, such as `support@acme.com`.

## Create a managed address

`POST /v1/inbound/domains`

An instant receiving domain on ZapSMTP: no DNS, every local part works.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `managed` (boolean): true: create an instant managed domain <10 random lowercase chars>.<inbound zone>; no DNS needed; name is ignored. Default `False`.
- `name` (string): Required unless managed is true. Your own domain. It (or a parent) must be verified for sending by the account. Then publish MX 10 <inbound host> and call verify. Limits: invalid → 422 invalid_parameter "invalid domain name"; ZapSMTP-owned names → 422 reserved_domain; not verified for sending → 403 domain_not_verified
- `reject_spam` (boolean): Refuse messages flagged as spam at SMTP time instead of delivering them with is_spam: true. Default `False`.
- `require_tls` (boolean): Accept encrypted mail only: senders without STARTTLS are refused with 530 5.7.0.

### Errors

- `domain_not_verified` (HTTP 403): verify <name> (or its parent domain) for sending first; inbound reuses that proof of ownership
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): this domain already receives mail on ZapSMTP
- `invalid_parameter` (HTTP 422): invalid domain name
- `reserved_domain` (HTTP 422): this domain is reserved by ZapSMTP; use a managed address or your own domain
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "managed": true
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f20-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
  "name": "k3f9x2m7q1.in.zapsmtp.xyz",
  "managed": true,
  "reject_spam": false,
  "mx_verified": true,
  "last_checked_at": "2026-10-21T15:00:00Z",
  "created_at": "2026-10-21T15:00:00Z",
  "records": [],
  "example_address": "anything@k3f9x2m7q1.in.zapsmtp.xyz"
}
```

## Receive on your own domain

`POST /v1/inbound/domains`

Use a domain (or subdomain) of a domain you already verified for sending, then publish the MX record from `records`.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `managed` (boolean): true: create an instant managed domain <10 random lowercase chars>.<inbound zone>; no DNS needed; name is ignored. Default `False`.
- `name` (string): Required unless managed is true. Your own domain. It (or a parent) must be verified for sending by the account. Then publish MX 10 <inbound host> and call verify. Limits: invalid → 422 invalid_parameter "invalid domain name"; ZapSMTP-owned names → 422 reserved_domain; not verified for sending → 403 domain_not_verified
- `reject_spam` (boolean): Refuse messages flagged as spam at SMTP time instead of delivering them with is_spam: true. Default `False`.
- `require_tls` (boolean): Accept encrypted mail only: senders without STARTTLS are refused with 530 5.7.0.

### Errors

- `domain_not_verified` (HTTP 403): verify <name> (or its parent domain) for sending first; inbound reuses that proof of ownership
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): this domain already receives mail on ZapSMTP
- `invalid_parameter` (HTTP 422): invalid domain name
- `reserved_domain` (HTTP 422): this domain is reserved by ZapSMTP; use a managed address or your own domain
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "support.acme.com",
  "reject_spam": true,
  "require_tls": false
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f20-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
  "name": "k3f9x2m7q1.in.zapsmtp.xyz",
  "managed": true,
  "reject_spam": false,
  "mx_verified": true,
  "last_checked_at": "2026-10-21T15:00:00Z",
  "created_at": "2026-10-21T15:00:00Z",
  "records": [],
  "example_address": "anything@k3f9x2m7q1.in.zapsmtp.xyz"
}
```

## The MX record

The response lists the record to publish under `records`. It is the only record inbound needs:

**DNS for support.acme.com**

- **Type**: `MX`
- **Name**: `support.acme.com` (in many DNS panels: `support`)
- **Priority**: `10`
- **Value**: `zapsmtp.xyz`

> Publishing an MX record moves all mail of that name to ZapSMTP. To keep your existing mailboxes on `acme.com`, receive on a subdomain such as `support.acme.com` or `reply.acme.com`.

Then ask for a check. `mx_verified` turns `true` as soon as any MX record of the name points to `zapsmtp.xyz`; `mx_found` shows what DNS returns today.

## Check the MX record

`POST /v1/inbound/domains/{id}/verify`

Check the domain's MX record now.

Requires a full-access live key; test keys get 403 test_key_restricted.

`mx_verified` becomes `true` as soon as any MX record of the domain points to our inbound host.

### Path parameters

- `id` (string (UUID), required): Inbound domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): inbound domain not found

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/domains/019a1f21-5d6e-7f80-9a1b-2c3d4e5f6a7b/verify' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "domain": {
    "id": "019a1f21-5d6e-7f80-9a1b-2c3d4e5f6a7b",
    "name": "reply.acme.com",
    "managed": false,
    "reject_spam": true,
    "mx_verified": true,
    "last_checked_at": "2026-10-21T15:05:00Z",
    "created_at": "2026-10-20T11:30:00Z",
    "records": [
      {
        "record": "MX",
        "type": "MX",
        "name": "reply.acme.com",
        "value": "10 zapsmtp.xyz",
        "required": true,
        "status": "verified"
      }
    ],
    "example_address": "anything@reply.acme.com"
  },
  "mx_found": [
    "zapsmtp.xyz"
  ]
}
```

## Routes

Routes are rules you set per account (up to 100). They are tried in `priority` order, lowest first, then oldest first; the first enabled route whose conditions all match decides. A message that matches no route takes the default path: it is stored and sent to every endpoint subscribed to `email.received`.

**Conditions (all must match; empty matches anything)**

- **`match_recipient`**: The receiving address, for example `support+*@acme.com`.
- **`match_sender`**: The envelope sender (`MAIL FROM`), which can differ from the From header.
- **`match_header` + `match_header_value`**: A header name (any case) and a pattern for its value. A message without that header does not match.

Patterns are case-insensitive globs where `*` is any run of characters and `?` one character, or a regular expression between slashes, such as `/^(sales|billing)@acme\.com$/`. Regular expressions use RE2 syntax, which runs in linear time; lookarounds and backreferences are not supported. Each pattern is at most 512 bytes (UTF-8) and must compile.

**Actions**

- **`webhook`**: Stored, and `email.received` goes only to `webhook_id`, even when that endpoint does not subscribe to it. Other endpoints do not see the message.
- **`store`**: Stored and readable through the API and the dashboard. No webhook.
- **`forward`**: Stored, and a copy is relayed to the confirmed destination `forward_id` (Forwarding). No webhook.
- **`reject`**: Refused during SMTP with `550 5.7.1`. Nothing is stored; the message is listed with `status: "rejected"`.

The received email records what happened in `route_id` and `action` (`default` when no route matched).

## Send support mail to one endpoint

`POST /v1/inbound/routes`

Every address `support+…@acme.com` goes to a single webhook endpoint, whatever events that endpoint subscribes to.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string): Label (trimmed).
- `priority` (integer): Lower runs first; first match wins. Default `100`.
- `match_recipient` (string): Glob (case-insensitive, * and ?) e.g. support+*@acme.com, or /regex/ (RE2, case-insensitive). Empty matches all. Limits: max 512 chars; must compile (422 invalid_parameter)
- `match_sender` (string): Same syntax, matched against the envelope sender. Limits: max 512 chars; must compile
- `match_header` (string): Header name to test.
- `match_header_value` (string): Glob or /regex/ for that header's value. Limits: max 512 chars; must compile
- `action` (string, required): webhook: deliver email.received only to webhook_id; store: keep without webhook; forward: keep and forward to forward_id (a confirmed forward destination); reject: refuse with 550 at SMTP time. Limits: 422 invalid_parameter "action must be webhook, store, reject or forward" One of `webhook`, `store`, `forward`, `reject`.
- `webhook_id` (string | null): Required when action is webhook. A webhook of this account. Cleared for store/reject. Limits: 422 "webhook_id is required for action webhook" / "webhook_id does not belong to this account"
- `forward_id` (string | null): A confirmed forward destination of this account (action forward). Cleared for other actions. Limits: 422 "forward_id is required for action forward" / "forward_id does not belong to this account" / "... is not confirmed yet"
- `enabled` (boolean): Default `True`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): validation failures or "at most 100 routes per account"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/routes' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Support tickets",
  "priority": 10,
  "match_recipient": "support+*@acme.com",
  "action": "webhook",
  "webhook_id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "name": "Support tickets",
  "priority": 10,
  "match_recipient": "support+*@acme.com",
  "match_sender": "",
  "match_header": "",
  "match_header_value": "",
  "action": "webhook",
  "webhook_id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "enabled": true,
  "created_at": "2026-10-21T15:20:00Z"
}
```

## Refuse a sender at SMTP time

`POST /v1/inbound/routes`

A `/regex/` on the envelope sender; matching mail is refused with 550 and never stored.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string): Label (trimmed).
- `priority` (integer): Lower runs first; first match wins. Default `100`.
- `match_recipient` (string): Glob (case-insensitive, * and ?) e.g. support+*@acme.com, or /regex/ (RE2, case-insensitive). Empty matches all. Limits: max 512 chars; must compile (422 invalid_parameter)
- `match_sender` (string): Same syntax, matched against the envelope sender. Limits: max 512 chars; must compile
- `match_header` (string): Header name to test.
- `match_header_value` (string): Glob or /regex/ for that header's value. Limits: max 512 chars; must compile
- `action` (string, required): webhook: deliver email.received only to webhook_id; store: keep without webhook; forward: keep and forward to forward_id (a confirmed forward destination); reject: refuse with 550 at SMTP time. Limits: 422 invalid_parameter "action must be webhook, store, reject or forward" One of `webhook`, `store`, `forward`, `reject`.
- `webhook_id` (string | null): Required when action is webhook. A webhook of this account. Cleared for store/reject. Limits: 422 "webhook_id is required for action webhook" / "webhook_id does not belong to this account"
- `forward_id` (string | null): A confirmed forward destination of this account (action forward). Cleared for other actions. Limits: 422 "forward_id is required for action forward" / "forward_id does not belong to this account" / "... is not confirmed yet"
- `enabled` (boolean): Default `True`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): validation failures or "at most 100 routes per account"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/routes' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Block a scraper",
  "priority": 1,
  "match_sender": "/@(.+\\.)?example\\.net$/",
  "action": "reject"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "name": "Support tickets",
  "priority": 10,
  "match_recipient": "support+*@acme.com",
  "match_sender": "",
  "match_header": "",
  "match_header_value": "",
  "action": "webhook",
  "webhook_id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "enabled": true,
  "created_at": "2026-10-21T15:20:00Z"
}
```

## Keep mailing-list mail without a webhook

`POST /v1/inbound/routes`

Match on any header: here mail that carries a `List-Id` is stored and stays readable through the API, but no webhook fires.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string): Label (trimmed).
- `priority` (integer): Lower runs first; first match wins. Default `100`.
- `match_recipient` (string): Glob (case-insensitive, * and ?) e.g. support+*@acme.com, or /regex/ (RE2, case-insensitive). Empty matches all. Limits: max 512 chars; must compile (422 invalid_parameter)
- `match_sender` (string): Same syntax, matched against the envelope sender. Limits: max 512 chars; must compile
- `match_header` (string): Header name to test.
- `match_header_value` (string): Glob or /regex/ for that header's value. Limits: max 512 chars; must compile
- `action` (string, required): webhook: deliver email.received only to webhook_id; store: keep without webhook; forward: keep and forward to forward_id (a confirmed forward destination); reject: refuse with 550 at SMTP time. Limits: 422 invalid_parameter "action must be webhook, store, reject or forward" One of `webhook`, `store`, `forward`, `reject`.
- `webhook_id` (string | null): Required when action is webhook. A webhook of this account. Cleared for store/reject. Limits: 422 "webhook_id is required for action webhook" / "webhook_id does not belong to this account"
- `forward_id` (string | null): A confirmed forward destination of this account (action forward). Cleared for other actions. Limits: 422 "forward_id is required for action forward" / "forward_id does not belong to this account" / "... is not confirmed yet"
- `enabled` (boolean): Default `True`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): validation failures or "at most 100 routes per account"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/routes' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Newsletters",
  "priority": 50,
  "match_header": "List-Id",
  "match_header_value": "*",
  "action": "store"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "name": "Support tickets",
  "priority": 10,
  "match_recipient": "support+*@acme.com",
  "match_sender": "",
  "match_header": "",
  "match_header_value": "",
  "action": "webhook",
  "webhook_id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "enabled": true,
  "created_at": "2026-10-21T15:20:00Z"
}
```

## Pause a route

`PATCH /v1/inbound/routes/{id}`

Disabled routes are skipped; the next matching route (or the default) handles the message.

Requires a full-access live key; test keys get 403 test_key_restricted.

Any subset of the POST /inbound/routes fields. Omitted fields keep their value; webhook_id: "" clears it. The resulting route must still be valid (e.g. action webhook needs webhook_id).

### Path parameters

- `id` (string (UUID), required): Route id

### Body parameters

- `name` (string): Label (trimmed).
- `priority` (integer): Lower runs first; first match wins.
- `match_recipient` (string): Glob (case-insensitive, * and ?) e.g. support+*@acme.com, or /regex/ (RE2, case-insensitive). Empty matches all. Limits: max 512 chars; must compile (422 invalid_parameter)
- `match_sender` (string): Same syntax, matched against the envelope sender. Limits: max 512 chars; must compile
- `match_header` (string): Header name to test.
- `match_header_value` (string): Glob or /regex/ for that header's value. Limits: max 512 chars; must compile
- `action` (string): webhook: deliver email.received only to webhook_id; store: keep without webhook; forward: keep and forward to forward_id (a confirmed forward destination); reject: refuse with 550 at SMTP time. Limits: 422 invalid_parameter "action must be webhook, store, reject or forward" One of `webhook`, `store`, `forward`, `reject`.
- `webhook_id` (string | null): A webhook of this account. Cleared for store/reject. Limits: 422 "webhook_id is required for action webhook" / "webhook_id does not belong to this account"
- `forward_id` (string | null): A confirmed forward destination of this account (action forward). Cleared for other actions. Limits: 422 "forward_id is required for action forward" / "forward_id does not belong to this account" / "... is not confirmed yet"
- `enabled` (boolean)

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): route not found
- `invalid_parameter` (HTTP 422)

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/inbound/routes/019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "name": "Support tickets",
  "priority": 5,
  "match_recipient": "support+*@acme.com",
  "match_sender": "",
  "match_header": "",
  "match_header_value": "",
  "action": "store",
  "webhook_id": null,
  "enabled": true,
  "created_at": "2026-10-20T12:00:00Z"
}
```

## Forwarding

To forward to an ordinary mailbox, add it as a forward destination first. ZapSMTP emails it a confirmation link; the page behind the link asks for a click, so link scanners cannot confirm on their own. Until then `verified_at` is `null` and no route may forward there. An account can have 20 destinations; a ZapSMTP receiving address cannot be one, because it would loop. A lost link can be sent again, at most once a minute, and the previous link stops working.

The forwarded copy is the original message byte for byte, so its From and DKIM signature stay intact. ZapSMTP adds an ARC seal with its authentication results and an `X-ZapSMTP-Forwarded-For` header naming the receiving address. Each forward counts as one sent email and appears in your email log. Spam is never forwarded, and neither is a message already forwarded several times or one that names the destination itself. Removing a destination makes its routes store only.

## Add a forward destination

`POST /v1/inbound/forward-destinations`

Add a forward destination: we email it a confirmation link; routes can forward there once its owner confirms.

Requires a full-access live key; test keys get 403 test_key_restricted.

The confirmation page asks for a click, so mail scanners that follow links cannot confirm. Forwarded mail keeps its original From and DKIM, is ARC-signed by us, counts as one sent email and appears in the email log; spam is never forwarded.

### Body parameters

- `email` (string, required): A plain address. Not a ZapSMTP receiving address (it would loop).

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): <email> is already a forward destination
- `invalid_parameter` (HTTP 422): "email must be a plain address (name@example.com)" | "cannot forward to a ZapSMTP receiving address (it would loop)"
- `limit_exceeded` (HTTP 422): at most 20 forward destinations per account
- `rate_limit_exceeded` (HTTP 429): at most 20 forward destinations can be added a day
- `service_unavailable` (HTTP 503): the destination was added but its confirmation email could not be sent; resend it

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/forward-destinations' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "oncall@acme.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "0199f0b2-0000-7000-8000-00000000f001",
  "email": "team@acme.com",
  "confirmation_sent_at": "2026-10-25T10:00:00Z",
  "verified_at": null,
  "created_at": "2026-10-25T10:00:00Z"
}
```

## Forward to a confirmed destination

`POST /v1/inbound/routes`

Keep the message and relay a copy to the destination once its owner has confirmed it.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string): Label (trimmed).
- `priority` (integer): Lower runs first; first match wins. Default `100`.
- `match_recipient` (string): Glob (case-insensitive, * and ?) e.g. support+*@acme.com, or /regex/ (RE2, case-insensitive). Empty matches all. Limits: max 512 chars; must compile (422 invalid_parameter)
- `match_sender` (string): Same syntax, matched against the envelope sender. Limits: max 512 chars; must compile
- `match_header` (string): Header name to test.
- `match_header_value` (string): Glob or /regex/ for that header's value. Limits: max 512 chars; must compile
- `action` (string, required): webhook: deliver email.received only to webhook_id; store: keep without webhook; forward: keep and forward to forward_id (a confirmed forward destination); reject: refuse with 550 at SMTP time. Limits: 422 invalid_parameter "action must be webhook, store, reject or forward" One of `webhook`, `store`, `forward`, `reject`.
- `webhook_id` (string | null): Required when action is webhook. A webhook of this account. Cleared for store/reject. Limits: 422 "webhook_id is required for action webhook" / "webhook_id does not belong to this account"
- `forward_id` (string | null): A confirmed forward destination of this account (action forward). Cleared for other actions. Limits: 422 "forward_id is required for action forward" / "forward_id does not belong to this account" / "... is not confirmed yet"
- `enabled` (boolean): Default `True`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): validation failures or "at most 100 routes per account"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/routes' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Billing to on-call",
  "priority": 20,
  "match_recipient": "billing@acme.com",
  "action": "forward",
  "forward_id": "0199f0b2-0000-7000-8000-00000000f001"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "name": "Support tickets",
  "priority": 10,
  "match_recipient": "support+*@acme.com",
  "match_sender": "",
  "match_header": "",
  "match_header_value": "",
  "action": "webhook",
  "webhook_id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "enabled": true,
  "created_at": "2026-10-21T15:20:00Z"
}
```

## The email.received webhook

One event per received message and receiving address: mail sent to two of your addresses arrives as two emails, each with its own `email_id`. Events are signed and retried like every other event ([Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/)); the event id is in the `Zap-Event-Id` header and stays the same across retries.

By default the event carries metadata only, so a 40 MB message never hits a request size limit on your side. Fetch the body when you need it, or turn on `include_content` for the endpoint.

## Subscribe an endpoint

`POST /v1/webhooks`

Ask for `email.received` and the conversation events. `include_content` adds the message itself to `email.received`.

Requires a full-access live key; test keys get 403 test_key_restricted.

The secret is also readable later via GET /webhooks/{id}.

To send clicks of one button to this endpoint: `{"events": ["email.clicked"], "filter": {"actions": ["confirm_order"]}}`. Endpoints always return `filter`, with an empty list when there is none.

### Body parameters

- `url` (string, required): Absolute https:// URL. Limits: 422 invalid_parameter "url must be an absolute https:// URL"
- `events` (string[]): Limits: unknown type → 422 invalid_parameter "unknown event type <x>; allowed: ..." One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `all event types`.
- `include_content` (boolean): `email.received` carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (`truncated: true`). Default `false`.
- `batch` (boolean): Send events up to 100 per request (or every second) as a JSON array, signed as one body; `Zap-Event-Id` is the batch id, each event keeps its own `id`. `email.received` with the full message still arrives alone. Default `false`.
- `filter` (object): Narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/); other event types are not affected. Empty or absent: every click. Default `{"actions": []}`.
  - `actions` (string[]): Action names (lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters). The endpoint then receives `email.clicked` only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/hooks/inbound",
  "events": [
    "email.received",
    "thread.created",
    "thread.replied"
  ],
  "include_content": true
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-21T15:40:00Z",
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": []
  }
}
```

## Payload

```json
{
  "type": "email.received",
  "created_at": "2026-10-21T15:10:03.418Z",
  "data": {
    "email_id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
    "created_at": "2026-10-21T15:10:02.904Z",
    "from": "jane@example.org",
    "from_name": "Jane Doe",
    "to": [
      "support+1234@acme.com"
    ],
    "cc": [],
    "bcc": [],
    "reply_to": [],
    "received_for": [
      "support+1234@acme.com"
    ],
    "message_id": "<CAF=abc123@mail.example.org>",
    "subject": "Re: Ticket #1234",
    "attachments": [
      {
        "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
        "filename": "screenshot.png",
        "content_type": "image/png",
        "content_disposition": "attachment",
        "content_id": null,
        "size": 48213
      }
    ],
    "envelope": {
      "from": "jane@example.org",
      "to": "support+1234@acme.com"
    },
    "mailbox_hash": "1234",
    "reply_text": "Thanks, that fixed it!",
    "in_reply_to_email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
    "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
    "automated": null,
    "authentication": {
      "spf": "pass",
      "dkim": "pass",
      "dmarc": "pass",
      "arc": "gray"
    },
    "spam": {
      "score": 1.2,
      "is_spam": false
    },
    "route_id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
    "size": 61877
  }
}
```

**data**

- **`email_id`**: The received email: `GET /emails/receiving/{id}`.
- **`from`, `from_name`**: The From header’s address and display name.
- **`to`, `cc`, `reply_to`**: As written in the headers. `bcc` is always empty: Bcc never appears in a delivered message.
- **`received_for`**: The one address of yours this copy was delivered to; it may not appear in `to` (a Bcc, a mailing list).
- **`envelope`**: The SMTP envelope: `from` is the return path, `to` the receiving address.
- **`mailbox_hash`**: The part after `+` in the receiving address: `support+1234@acme.com` gives `1234`. Put a ticket or order id there in the Reply-To of what you send.
- **`reply_text`**: Only the new text of a reply (below).
- **`in_reply_to_email_id`**: The email you sent through ZapSMTP that this message answers, or `null`.
- **`thread_id`**: The conversation.
- **`automated`**: `null` when a person wrote it, otherwise `{type, reason}` (below).
- **`authentication`**: SPF, DKIM, DMARC and ARC verdicts (below).
- **`spam`**: `score` and `is_spam`.
- **`attachments`**: Metadata of every part that is not the text or HTML body, inline images included.
- **`route_id`, `size`**: The route that matched (empty for none) and the message size in bytes.

### With include_content

The same event also carries the message. Text and HTML share a 1 MB budget after the headers; beyond it they are cut on a character boundary and `truncated` is `true`, and the API still serves them whole. Download links in the webhook work for 24 hours, so they survive every retry. If the message cannot be read at delivery time, `content_error` says to fetch it from the API instead.

```json
{
  "text": "Thanks, that fixed it!\n\nOn Tue, Oct 21, 2026 Acme Support <support@acme.com> wrote:\n> ...",
  "html": "<p>Thanks, that fixed it!</p><blockquote>...</blockquote>",
  "headers": {
    "from": "Jane Doe <jane@example.org>",
    "to": "support+1234@acme.com",
    "subject": "Re: Ticket #1234",
    "in-reply-to": "<019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23@…>"
  },
  "truncated": false,
  "attachments": [
    {
      "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
      "filename": "screenshot.png",
      "content_type": "image/png",
      "content_disposition": "attachment",
      "content_id": null,
      "size": 48213,
      "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi....aGk",
      "expires_at": "2026-10-22T15:10:03Z"
    }
  ],
  "raw": {
    "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi....Qm9n",
    "expires_at": "2026-10-22T15:10:03Z"
  }
}
```

## Conversation events

Subscribe to `thread.created` to hear about new conversations (a message that answers nothing) and to `thread.replied` for answers in an existing one. Both skip bounces, out-of-office notices, auto-replies and notifications, and both are skipped when you redeliver. They use the same endpoints as `email.received`: messages handled by a `store`, `forward` or `reject` route produce none, and a `webhook` route sends them only to its endpoint, if that endpoint subscribes.

```json
{
  "type": "thread.replied",
  "created_at": "2026-10-21T15:10:03.420Z",
  "data": {
    "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
    "email_id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
    "created_at": "2026-10-21T15:10:02.904Z",
    "from": "jane@example.org",
    "from_name": "Jane Doe",
    "to": [
      "support+1234@acme.com"
    ],
    "subject": "Re: Ticket #1234",
    "received_for": [
      "support+1234@acme.com"
    ],
    "mailbox_hash": "1234",
    "reply_text": "Thanks, that fixed it!",
    "in_reply_to_email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
    "automated": null
  }
}
```

## Send a test email.received

`POST /v1/webhooks/{id}/test`

Send a signed sample event to the endpoint now and report the result.

Requires a full-access live key; test keys get 403 test_key_restricted.

Test events are not retried. delivery.error is present when the attempt failed (e.g. "HTTP 500"); status_code is 0 on network errors. The test attempt is recorded in the delivery log.

### Path parameters

- `id` (string, required): Webhook id

### Body parameters

- `type` (string): Limits: 422 invalid_parameter "unknown event type" One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `email.delivered`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): webhook not found
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks/019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b/test' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "email.received"
}'
```

**Response `200 OK`**

```json
{
  "ok": true,
  "delivery": {
    "event_id": "evt_test_9Gk2Lq7Xv1Rb4Tz8",
    "event_type": "email.delivered",
    "attempt": 1,
    "status_code": 200,
    "duration_ms": 143,
    "at": "2026-10-21T15:50:00.123Z",
    "body": {
      "id": "evt_test_9Gk2Lq7Xv1Rb4Tz8",
      "type": "email.delivered",
      "created_at": "2026-10-21T15:50:00.120Z",
      "data": {
        "email_id": "00000000-0000-0000-0000-000000000000",
        "from": "Test <test@example.com>",
        "to": "recipient@example.com",
        "subject": "ZapSMTP webhook test",
        "response": {
          "code": 250,
          "message": "OK (test event)"
        }
      }
    }
  },
  "payload": {
    "id": "evt_test_9Gk2Lq7Xv1Rb4Tz8",
    "type": "email.delivered",
    "created_at": "2026-10-21T15:50:00.120Z",
    "data": {
      "email_id": "00000000-0000-0000-0000-000000000000",
      "from": "Test <test@example.com>",
      "to": "recipient@example.com",
      "subject": "ZapSMTP webhook test",
      "response": {
        "code": 250,
        "message": "OK (test event)"
      }
    }
  }
}
```

## Read the message

The API returns the parsed message with its bodies, headers and verdicts, plus a link to the original. `html_format` picks how inline images come back: `data_uri` (the default) embeds them as `data:` URIs so the HTML renders on its own, `cid` keeps the `cid:` references as received. When the inline images are larger than 2 MB together they stay `cid` and the response says so in `html_format`.

## Retrieve the whole message

`GET /v1/emails/receiving/{id}`

Retrieve a received email with bodies, headers, authentication results and download links.

Requires a full-access key.

`automated` is null for mail a person wrote, else `{type, reason}`: `bounce` (delivery status notification), `out_of_office`, `auto_reply`, `auto_generated` (notifications, null sender) or `bulk` (mailing lists). Detected from Auto-Submitted, X-Autoreply, Precedence, List-Id, multipart/report and well-known subjects; `reason` names the evidence.

`tls`: the TLS version the sending server used (e.g. `TLSv1_3`); empty when the message was not encrypted.

### Path parameters

- `id` (string (UUID), required): Received email id

### Query parameters

- `html_format` (string): cid: return html as received (cid: references to inline parts). Any other value: inline images are embedded as data: URIs (html_format in the response reports what was returned). One of `data_uri`, `cid`. Default `data_uri`.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): unknown/non-UUID id or past plan retention
- `inbound_not_configured` (HTTP 503)

```bash
curl 'https://zapsmtp.xyz/v1/emails/receiving/019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
  "created_at": "2026-10-21T15:10:02.904Z",
  "from": "jane@example.org",
  "to": [
    "support@acme.com"
  ],
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "received_for": [
    "support+1234@acme.com"
  ],
  "subject": "Re: Ticket #1234",
  "message_id": "<CAF=abc123@mail.example.org>",
  "html": "<p>Thanks, that fixed it!</p><blockquote>...</blockquote>",
  "html_format": "data_uri",
  "text": "Thanks, that fixed it!\n\nOn Tue, Oct 21, 2026 Acme wrote:\n> ...",
  "headers": {
    "Subject": "Re: Ticket #1234",
    "From": "Jane Doe <jane@example.org>",
    "To": "support@acme.com"
  },
  "authentication": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass"
  },
  "raw": {
    "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi....Qm9n",
    "expires_at": "2026-10-21T16:12:00Z"
  },
  "attachments": [
    {
      "object": "attachment",
      "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
      "filename": "screenshot.png",
      "content_type": "image/png",
      "content_disposition": "attachment",
      "content_id": null,
      "size": 48213
    }
  ],
  "from_name": "Jane Doe",
  "reply_text": "Thanks, that fixed it!",
  "mailbox_hash": "1234",
  "in_reply_to_email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
  "automated": null,
  "envelope": {
    "from": "jane@example.org",
    "to": "support+1234@acme.com"
  },
  "spam": {
    "score": 1.2,
    "is_spam": false,
    "action": "no action"
  },
  "arc": "unknown",
  "route_id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "action": "webhook",
  "status": "received",
  "size": 61877,
  "peer_ip": "198.51.100.7",
  "helo": "mail.example.org"
}
```

## Reply text

`reply_text` is the text body with the quoted original and the signature removed: everything from the quote header on (“On … wrote:”, “-----Original Message-----”, Outlook’s From/Sent block, and the German, French, Spanish and Russian equivalents), lines starting with `>`, and everything after a `-- ` signature line. It is a heuristic, because mail clients quote in many ways; `text` and `html` always hold the full message. In the webhook `reply_text` is at most 16 KB.

**Example**

- **`text`**: `Thanks, that fixed it!-- JaneOn Tue, Oct 21, 2026 Acme Support <support@acme.com> wrote:> Please try again now.`
- **`reply_text`**: `Thanks, that fixed it!`

## Headers

`headers` is an object of every header with lower-case names. A header that appears more than once (`received`, for example) has its values joined with `", "`. For the exact original, download the raw message.

## Authentication

Each check reports one of these values. The API returns `arc` next to `authentication`; the webhook has it inside. A From address is only trustworthy when DMARC is `pass`: SPF and DKIM alone can pass for a different domain than the one in From.

**spf, dkim, dmarc, arc**

- **`pass`**: The check passed.
- **`fail`**: The check failed (for DMARC: the sender’s policy said reject, quarantine or fail).
- **`gray`**: No verdict: SPF softfail or neutral, or nothing to check (no SPF record, no signature, no DMARC policy).
- **`processing_failed`**: A temporary or permanent DNS error stopped the check.
- **`unknown`**: The message could not be scanned; it was accepted anyway.

The API also returns `tls`, the TLS version the sending server used (for example `TLSv1_3`, empty when the message was not encrypted), and the sender’s `peer_ip` and `helo`.

## Automated mail

ZapSMTP recognises mail no person wrote from the standard headers (Auto-Submitted, X-Autoreply, Precedence, List-Id, multipart/report, a null sender) and from well-known subjects. `reason` names the evidence, for example `Auto-Submitted: auto-replied`. Never auto-answer these: two auto-responders replying to each other is a mail loop.

**automated.type**

- **`bounce`**: A delivery status notification (multipart/report, or a mailer-daemon with a bounce subject).
- **`out_of_office`**: An out-of-office notice.
- **`auto_reply`**: Any other automatic reply (Auto-Submitted: auto-replied, X-Autoreply…).
- **`auto_generated`**: Notifications and mail with a null envelope sender.
- **`bulk`**: Mailing lists and bulk mail (List-Id, Precedence: bulk/list). Unlike the others, you may reply to it without allow_automated, and it opens or continues conversations.

## List what people wrote

`GET /v1/emails/receiving`

Received emails, newest first, without bounces, out-of-office notices and other automated mail.

Requires a full-access key.

`action` is `default`, `webhook`, `store`, `reject` or `spam_reject`. `in_reply_to_email_id` appears only when the message replies to an email you sent through ZapSMTP.

### Query parameters

- `limit` (integer): 1-100; out-of-range falls back to 20. Default `20`.
- `before` (string): Cursor: an email id or RFC 3339 time; returns messages received before it. An email id gives an exact page boundary. Limits: 422 invalid_parameter "before must be an email id or RFC 3339 time"
- `after` (string): Email id or RFC 3339 time. Limits: 422 invalid_parameter "after must be an email id or RFC 3339 time"
- `q` (string): Case-insensitive substring of sender, recipient or subject, or an exact id.
- `status` (string): One of `received`, `rejected`.
- `domain` (string): Inbound domain name (exact).
- `thread_id` (string (UUID)): Only emails of this conversation (see `GET /threads/{id}`).
- `automated` (string): `false`: only emails a person wrote; `true`: only automated ones; or one type: `bounce`, `out_of_office`, `auto_reply`, `auto_generated`, `bulk`. Limits: 422 invalid_parameter for other values.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422)
- `inbound_not_configured` (HTTP 503): inbound email is not enabled on this deployment

```bash
curl 'https://zapsmtp.xyz/v1/emails/receiving?automated=false&domain=acme.com&limit=20' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "email",
      "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
      "from": "jane@example.org",
      "from_name": "Jane Doe",
      "to": [
        "support@acme.com"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "received_for": [
        "support+1234@acme.com"
      ],
      "subject": "Re: Ticket #1234",
      "message_id": "<CAF=abc123@mail.example.org>",
      "created_at": "2026-10-21T15:10:02.904Z",
      "attachments": [
        {
          "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
          "filename": "screenshot.png",
          "content_type": "image/png",
          "content_disposition": "attachment",
          "content_id": null,
          "size": 48213
        }
      ],
      "status": "received",
      "action": "webhook",
      "is_spam": false,
      "spam_score": 1.2,
      "size": 61877,
      "in_reply_to_email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    }
  ]
}
```

## Attachments

Every part that is not the text or HTML body is an attachment, inline images included (they have a `content_id` and usually `content_disposition: "inline"`). A part without a file name is called `attachment-1`, `attachment-2` and so on. Attachment ids are stable: the same message always gives the same ids.

The listing adds a signed `download_url` to each. It needs no API key, so you can hand it to a browser or a background job, and it works for one hour (`expires_at`); list again for a fresh link. Files are always served as downloads, and HTML, SVG, XML and JavaScript as binary, so they never run in a browser.

## List attachments with download links

`GET /v1/emails/receiving/{id}/attachments`

List a received email's attachments with signed download links.

Requires a full-access key.

Each `download_url` works for one hour without an API key. Files are always served as downloads; HTML, SVG, XML and JavaScript are served as binary so they can never run in a browser.

### Path parameters

- `id` (string (UUID), required): Received email id

### Query parameters

- `limit` (integer): 1-100; when omitted or out of range all attachments are returned.
- `after` (string): Attachment id; returns attachments after it (ignored if unknown).
- `before` (string): Attachment id; returns attachments before it (used only when after is absent).

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found
- `inbound_not_configured` (HTTP 503)

```bash
curl 'https://zapsmtp.xyz/v1/emails/receiving/019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d/attachments' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "attachment",
      "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
      "filename": "screenshot.png",
      "content_type": "image/png",
      "content_disposition": "attachment",
      "content_id": null,
      "size": 48213,
      "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi....aGk",
      "expires_at": "2026-10-21T16:12:00Z"
    }
  ]
}
```

## Raw message

`raw.download_url` on the received email is the original `.eml` exactly as it arrived, with the same one-hour link rules. Keep it for archiving, or parse it with your own MIME library when you need something the parsed fields do not give.

**Download attachments and the .eml**

Node.js:

```javascript
// download_url needs no API key and works for an hour (24 hours in a webhook)
const res = await fetch(API + '/emails/receiving/' + emailId + '/attachments', {
  headers: { Authorization: 'Bearer ' + process.env.ZAP_API_KEY },
});
const { data } = await res.json();
for (const a of data) {
  const file = await fetch(a.download_url);
  await fs.promises.writeFile('./files/' + a.id, Buffer.from(await file.arrayBuffer()));
}
```

Python:

```python
# download_url needs no API key and works for an hour (24 hours in a webhook)
r = requests.get(f"{API}/emails/receiving/{email_id}/attachments",
                 headers={"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"})
for a in r.json()["data"]:
    with requests.get(a["download_url"], stream=True) as f, open(f"files/{a['id']}", "wb") as out:
        for chunk in f.iter_content(65536):
            out.write(chunk)
```

Shell:

```
# the original message, byte for byte, as an .eml file
curl -s 'https://zapsmtp.xyz/v1/emails/receiving/019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d' \
  -H "Authorization: Bearer $ZAP_API_KEY" | jq -r .raw.download_url \
  | xargs curl -s -o message.eml
```

## Conversations

Every received email, every `email.received` event and every send response carries a `thread_id`. It comes from the standard `Message-ID`, `In-Reply-To` and `References` headers, so there is nothing to set up: a customer’s first message starts a conversation, your reply joins it, and their answer joins it too. The Message-ID of every email you send names its conversation, so an answer threads correctly even from a mail client that keeps only `In-Reply-To`. A conversation you start by sending an email appears in the inbox once the customer answers.

![A conversation in the dashboard: the customer's messages and the team's replies in order, with the reply box below](https://www.zapsmtp.xyz/docs/img/thread-light.webp)

The dashboard shows each conversation with both sides of it.

**Conversation state**

- **`awaiting_reply`**: The customer wrote last: the latest email that is not automated mail is an inbound one. An incoming out-of-office or bounce never changes it. Any email you send in the conversation clears it, including an acknowledgement sent with `auto_reply: true`.
- **`unread`, `read_at`**: Something arrived after your read mark. Set or clear the mark with `PATCH /threads/{id}`.
- **`metadata`**: Your own key-value pairs, such as a ticket or CRM id: up to 20 keys of letters, digits, `_` and `-` (40 characters at most), values up to 500 bytes of UTF-8. A PATCH replaces them all.
- **Counts and times**: `message_count`, `inbound_count`, `outbound_count`, `has_attachments`, `first_message_at`, `last_message_at`, `last_inbound_at`, `last_message`.

## Your helpdesk inbox

`GET /v1/threads`

Conversations waiting for an answer, most recently active first.

Requires a full-access key.

Served from a per-conversation summary kept up to date as emails arrive: a page costs the same however much email you have.

A conversation you started (your first email) is counted once the customer answers it.

### Query parameters

- `limit` (integer): 1-100; out-of-range falls back to 20. Default `20`.
- `before` (string): Cursor: the `last_message_at` of the last conversation you have (RFC 3339). Limits: 422 invalid_parameter otherwise.
- `before_id` (string): With before: the id of the last conversation you have, so conversations active at the same instant are neither skipped nor repeated.
- `awaiting_reply` (boolean): `true`: only conversations whose last human email came in.
- `unread` (boolean): `true`: only conversations with an email received after their read mark.
- `participant` (string): Only conversations this address took part in (case-insensitive).

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): before must be an RFC 3339 time

```bash
curl 'https://zapsmtp.xyz/v1/threads?awaiting_reply=true&limit=25' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "thread",
      "id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
      "subject": "Where is my order?",
      "participants": [
        "jane@example.org",
        "support@acme.com"
      ],
      "message_count": 3,
      "inbound_count": 2,
      "outbound_count": 1,
      "has_attachments": false,
      "first_message_at": "2026-10-21T15:10:02.904Z",
      "last_message_at": "2026-10-21T16:02:13.540Z",
      "last_inbound_at": "2026-10-21T16:02:13.540Z",
      "last_message": {
        "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
        "direction": "inbound",
        "from": "jane@example.org",
        "subject": "Re: Where is my order?"
      },
      "awaiting_reply": true,
      "unread": true,
      "read_at": null,
      "metadata": {
        "ticket": "T-1042"
      }
    }
  ]
}
```

## Open a conversation

`GET /v1/threads/{id}`

A conversation: its state (participants, counts, last message, awaiting_reply, unread, metadata) and its received and sent emails, oldest first.

Requires a full-access key.

`awaiting_reply`: the last email a person wrote came in (automated mail does not count). `unread`: something was received after `read_at` (set with `PATCH /threads/{id}`).

Threads are derived from the standard In-Reply-To / References headers: no setup. Every received email, webhook `email.received` and send response carries its `thread_id`.

Refused messages are not part of a thread. At most 500 emails are listed (`has_more`); fetch bodies with `GET /emails/receiving/{id}` and `GET /emails/{id}/content`.

Emails received before 2026-10-23 have a thread id but are not listed here.

### Path parameters

- `id` (string (UUID), required): Thread id (`thread_id` of any email in it)

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): thread not found (or past your plan's log retention)

```bash
curl 'https://zapsmtp.xyz/v1/threads/3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "thread",
  "id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
  "subject": "Where is my order?",
  "participants": [
    "jane@example.org",
    "support@acme.com"
  ],
  "message_count": 3,
  "inbound_count": 2,
  "outbound_count": 1,
  "has_attachments": false,
  "first_message_at": "2026-10-21T15:10:02.904Z",
  "last_message_at": "2026-10-21T16:02:13.540Z",
  "last_inbound_at": "2026-10-21T16:02:13.540Z",
  "last_message": {
    "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
    "direction": "inbound",
    "from": "jane@example.org",
    "subject": "Re: Where is my order?"
  },
  "awaiting_reply": true,
  "unread": true,
  "read_at": null,
  "metadata": {
    "ticket": "T-1042"
  },
  "has_more": false,
  "data": [
    {
      "object": "email",
      "direction": "inbound",
      "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
      "created_at": "2026-10-21T15:10:02.904Z",
      "from": "jane@example.org",
      "to": [
        "support@acme.com"
      ],
      "cc": [],
      "subject": "Where is my order?",
      "message_id": "<CAF=abc123@mail.example.org>"
    },
    {
      "object": "email",
      "direction": "outbound",
      "id": "019a1f41-8b2c-7e3d-9f40-5a6b7c8d9e0f",
      "created_at": "2026-10-21T15:20:41.112Z",
      "from": "Acme Support <support@acme.com>",
      "to": [
        "jane@example.org"
      ],
      "cc": [],
      "subject": "Re: Where is my order?"
    },
    {
      "object": "email",
      "direction": "inbound",
      "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
      "created_at": "2026-10-21T16:02:13.540Z",
      "from": "jane@example.org",
      "to": [
        "support@acme.com"
      ],
      "cc": [],
      "subject": "Automatic reply: Where is my order?",
      "message_id": "<CAF=def456@mail.example.org>",
      "automated": "out_of_office"
    }
  ]
}
```

## Mark read and link your ticket

`PATCH /v1/threads/{id}`

Mark a conversation read or unread and set its metadata.

Requires a full-access live key; test keys get 403 test_key_restricted.

Omitted fields are kept.

### Path parameters

- `id` (string (UUID), required): Thread id

### Body parameters

- `read` (boolean): `true` sets `read_at` to now (unread again once a new email arrives); `false` clears it.
- `metadata` (object): Your own key-value pairs (a ticket id, a CRM deal), replacing the previous ones. Limits: at most 20 keys matching [A-Za-z0-9_-]{1,40}, values up to 500 bytes (UTF-8) (422 invalid_parameter).

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): thread not found
- `invalid_parameter` (HTTP 422): metadata limits

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/threads/3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "read": true,
  "metadata": {
    "ticket": "T-1042",
    "assignee": "ann"
  }
}'
```

**Response `200 OK`**

```json
{
  "object": "thread",
  "id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
  "subject": "Where is my order?",
  "participants": [
    "jane@example.org",
    "support@acme.com"
  ],
  "message_count": 3,
  "inbound_count": 2,
  "outbound_count": 1,
  "has_attachments": false,
  "first_message_at": "2026-10-21T15:10:02.904Z",
  "last_message_at": "2026-10-21T16:02:13.540Z",
  "last_inbound_at": "2026-10-21T16:02:13.540Z",
  "last_message": {
    "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
    "direction": "inbound",
    "from": "jane@example.org",
    "subject": "Re: Where is my order?"
  },
  "awaiting_reply": true,
  "unread": false,
  "read_at": "2026-10-21T16:05:00.000Z",
  "metadata": {
    "ticket": "T-1042"
  }
}
```

## Reply

`POST /emails/receiving/{id}/reply` fills in everything a mail client would, so the answer lands in the customer’s conversation:

**Defaults**

- **`to`**: The email’s Reply-To, otherwise its From. `reply_all: true` also copies its To and Cc, except the receiving address, the `from` you reply from, the original sender and anyone already in your `to` or `cc`. Other addresses of yours on the email are copied.
- **`from`**: The address that received the email, for example `support+1234@acme.com`. Its exact domain must be verified for sending: a receiving subdomain such as `support.acme.com` is not covered by verifying `acme.com`. Otherwise pass a `from` on a verified domain. Managed addresses only receive, so with them `from` is required.
- **`reply_to`**: When you reply from another address (`support@acme.com`), the receiving address, so the customer’s next answer comes back to the same inbox and keeps its `mailbox_hash`.
- **`subject`**: `Re: ` plus the email’s subject, unless it already starts with Re:.
- **`In-Reply-To`, `References`**: Set from the email’s Message-ID and References. A value you pass in `headers` wins.

Everything else works as in [POST /emails](https://www.zapsmtp.xyz/docs/emails/send-email/): templates, attachments, tags, scheduling, suppressions, test keys. The response has the new email’s `id` and its `thread_id`. Use an `Idempotency-Key` so a retried request never answers twice.

> Loop protection: a reply to a bounce, out-of-office notice, auto-reply or notification is refused with `422 automated_message` unless you pass `allow_automated: true`, and one conversation takes at most 20 replies an hour (`429 thread_reply_limit`). Mark your own acknowledgements with `auto_reply: true`: they then carry `Auto-Submitted: auto-replied` so other auto-responders stay quiet.

## Reply in the same conversation

`POST /v1/emails/receiving/{id}/reply`

Reply to a received email: recipients, subject, sender and threading headers default to the email's, so the answer lands in the sender's conversation.

Requires a full-access key. Live keys: the From domain must be verified for sending.

Our Message-ID of the reply names its thread, so the customer's answer joins the conversation even from a mail client that keeps only `In-Reply-To`.

Every other rule of `POST /emails` applies: suppressions, quotas, tracking, test keys.

Loop protection: replies to automated email need `allow_automated`, and one conversation takes at most 20 replies an hour.

### Path parameters

- `id` (string (UUID), required): Received email id

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `text` (string): Plain-text body. Either text or html (or a template) is required.
- `html` (string): HTML body.
- `from` (string): Default: the address that received the email (e.g. `support@acme.com`), which must be on a verified sending domain. Required when the email came to a managed `*.in.zapsmtp.xyz` address (those only receive): 422 missing_required_field.
- `to` (string | string[]): Default: the email's Reply-To, else its From. Limits: 422 missing_required_field when the email has neither.
- `reply_all` (boolean): Also copy everyone on the email's To and Cc, except the receiving address, the sender you reply from and anyone already addressed. Default `false`.
- `allow_automated` (boolean): Answer an automated email anyway (see `automated` on the received email). Without it a reply to a bounce, out-of-office, auto-reply or notification is refused with 422 automated_message: two auto-responders answering each other is a mail loop. Bulk mail can be answered without it. Default `false`.
- `auto_reply` (boolean): This answer is itself automatic (an acknowledgement, a ticket receipt): adds `Auto-Submitted: auto-replied` and `X-Auto-Response-Suppress: All` (RFC 3834), so other auto-responders do not answer it. Default `false`.
- `cc` (string | string[]): Added to the Cc (reply_all adds the email's recipients after these).
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Default: the receiving address when you reply from another one, so the customer's answer comes back to the same inbox.
- `subject` (string): Default: `Re: ` + the email's subject (kept as is when it already starts with Re:).
- `headers` (object): Custom headers. `In-Reply-To` and `References` are set for you (RFC 5322 threading); a value you give wins.
- `attachments, tags, metadata, stream, tracking, template, scheduled_at`: As in [POST /emails](https://www.zapsmtp.xyz/docs/emails/send-email/).

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `missing_required_field` (HTTP 422): from (managed receiving address), to (no sender on the email), or the body
- `automated_message` (HTTP 422): the email is a bounce, out-of-office, auto-reply or notification; pass allow_automated: true
- `rate_limit_exceeded` (HTTP 429)
- `thread_reply_limit` (HTTP 429): too many replies in this conversation in the last hour (a mail loop?); at most 20 per hour; Retry-After: 3600
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/receiving/019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d/reply' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: reply-T-1042-1' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme Support <support@acme.com>",
  "text": "Hi Jane,\n\nGlad it works now. Your order ships today.\n\nAnn, Acme Support",
  "html": "<p>Hi Jane,</p><p>Glad it works now. Your order ships today.</p><p>Ann, Acme Support</p>"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f41-8b2c-7e3d-9f40-5a6b7c8d9e0f",
  "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13"
}
```

## Replies to what you send

Customers often answer your transactional email: a receipt, a shipping notice. With reply tracking, each email sent from a domain carries its own signed Reply-To on an inbound domain of yours, such as `r1-…@reply.acme.com`. An answer to it is tied to that exact email, whatever its headers say: `in_reply_to_email_id` and the conversation come from the address. These replies skip your routes, still fire `email.received` and the conversation events, and add an `email.replied` event to the original email. A reply address works for 30 days and takes up to 100 replies a day; a forged or expired one is refused.

The reply domain must be MX-verified on the same account and equal to the sending domain or a subdomain of it. `reply_forward_to` optionally sends replies a person wrote on to a mailbox of yours. A single email can opt in or out with `"tracking": {"replies": true}` on `POST /emails`.

## Track replies to what you send

`PATCH /v1/domains/{id}`

Give every email sent from `acme.com` its own signed Reply-To on your inbound domain, so each answer is tied to the exact email.

Requires a full-access live key; test keys get 403 test_key_restricted.

Fields left out keep their value. The response is the domain, as in `GET /domains/{id}`.

Reply tracking: each tracked email gets its own signed Reply-To, e.g. `r1-<email id>.<signature>@reply.acme.com`, so replies come back tied to the exact email. Each reply fires `email.replied` (classified as a person, out-of-office, unsubscribe request, bounce…) and arrives as a received email; only replies a person wrote are forwarded. The display name is kept (the Reply-To’s name, else the From name). One reply address takes at most 100 replies a day.

### Path parameters

- `id` (string, required): Domain id

### Body parameters

- `open_tracking` (boolean): Default open tracking for emails from this domain.
- `click_tracking` (boolean): Default click tracking for emails from this domain.
- `tls` (string): Outbound encryption: `opportunistic` (default: encrypt whenever offered), `required` (TLS or no delivery) or `verified` (TLS with a valid certificate). Limits: other values → 422 invalid_parameter "tls must be opportunistic, required or verified"
- `reply_tracking` (boolean): Default reply tracking for emails from this domain (override per email with `tracking.replies`). Limits: true without a reply_domain → 422 invalid_parameter "reply_tracking needs a reply_domain: add an inbound domain such as reply.<domain> first"
- `reply_domain` (string): Where tracked reply addresses live: one of your inbound domains, MX-verified, equal to this domain or a subdomain of it (e.g. `reply.acme.com`). `""` clears it. Limits: otherwise 422 invalid_parameter
- `reply_forward_to` (string): Where replies a person wrote are forwarded: a plain address on one of your verified domains, or a confirmed forward destination; never a receiving address. `""` (default) forwards to the email’s first Reply-To, else its From. Limits: otherwise 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `invalid_parameter` (HTTP 422): bad tls; reply_domain not one of your inbound domains, not this domain or a subdomain of it, or without a verified MX record; reply_forward_to not a plain address, a receiving address, or not on a verified domain / confirmed forward destination; reply_tracking without a reply_domain

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "reply_domain": "reply.acme.com",
  "reply_tracking": true
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": true,
  "open_tracking": true,
  "click_tracking": true,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": true,
  "reply_domain": "reply.acme.com",
  "reply_forward_to": "support@acme.com",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T14:05:00Z",
  "verified_at": "2026-10-21T14:05:00Z",
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "verified"
    }
  ]
}
```

## Spam

Every message gets a spam `score`. At 15 or more it is refused during SMTP with `550 5.7.1`. From 6 it is accepted with `is_spam: true`, so you can filter it in your handler, or refused as well when the domain has `reject_spam` on. Spam is never forwarded. The API’s `spam.action` shows the scanner’s decision: `no action`, `add header`, `rewrite subject`, `reject`, or `unknown` when the message could not be scanned (it is accepted rather than lost).

Reporting messages trains a spam filter of your own account: each account learns separately, so your reports never change anyone else’s filter. It starts scoring after it has learned 20 messages of each kind; until then reports have no effect on scores. Report spam that got through with `spam: true` and wanted mail that was flagged with `spam: false`. `learned: false` means the message has too few words to learn from.

## Teach your spam filter

`POST /v1/emails/receiving/{id}/spam`

Report a received email as spam or not spam: your account's spam filter learns from it.

Requires a full-access live key; test keys get 403 test_key_restricted.

Each account has its own statistics: your reports never change another account's filter. The filter starts scoring once it has learned 20 emails of each kind. Reporting the same email twice is harmless. `learned` is false when the email has too few words to learn from.

### Path parameters

- `id` (string): Received email id.

### Body parameters

- `spam` (boolean, required): true: mail like this is spam; false: it is wanted. Limits: missing → 422 missing_required_field

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): Unknown email or past your plan's retention.
- `service_unavailable` (HTTP 503): The spam filter could not learn right now; retry.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/receiving/019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d/spam' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "spam": false
}'
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "01a17204-bd5b-7691-9fca-52161a26e6d7",
  "spam": true,
  "learned": true
}
```

## Refuse spam instead of storing it

`PATCH /v1/inbound/domains/{id}`

Update an inbound domain's spam policy.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string (UUID), required): Inbound domain id

### Body parameters

- `reject_spam` (boolean): Refuse flagged spam (550) instead of delivering it with is_spam: true.
- `require_tls` (boolean): Accept encrypted mail only: senders without STARTTLS are refused with 530 5.7.0.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): inbound domain not found

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/inbound/domains/019a1f21-5d6e-7f80-9a1b-2c3d4e5f6a7b' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "reject_spam": true,
  "require_tls": true
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f21-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "name": "reply.acme.com",
  "managed": false,
  "reject_spam": true,
  "mx_verified": true,
  "last_checked_at": "2026-10-21T15:05:00Z",
  "created_at": "2026-10-20T11:30:00Z",
  "records": [
    {
      "record": "MX",
      "type": "MX",
      "name": "reply.acme.com",
      "value": "10 zapsmtp.xyz",
      "required": true,
      "status": "verified"
    }
  ],
  "example_address": "anything@reply.acme.com"
}
```

## Redeliver and erase

Lost a webhook while your endpoint was down? Redeliver queues `email.received` again for your endpoints (not the conversation events, and nothing is forwarded again). To find what came in, list with `status`, `domain`, `q` or `thread_id`. Erasing removes the message, its attachments and its metadata for good, for example for a GDPR request.

## Redeliver to your webhooks

`POST /v1/emails/receiving/{id}/redeliver`

Re-send the email.received webhook for a stored message.

Requires a full-access live key; test keys get 403 test_key_restricted.

The event is re-queued asynchronously (hence 202).

### Path parameters

- `id` (string (UUID), required): Received email id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): email not found
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/receiving/019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d/redeliver' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `202 `**

```json
{
  "object": "email",
  "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
  "redelivered": true
}
```

## Erase a message

`DELETE /v1/emails/receiving/{id}`

Permanently erase a received email's content and metadata (GDPR erasure).

Requires a full-access live key; test keys get 403 test_key_restricted.

Idempotent: deleting an id that does not exist (but is a valid UUID) still returns 200 deleted:true.

### Path parameters

- `id` (string (UUID), required): Received email id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): id is not a UUID
- `not_ready` (HTTP 409): this email is still being stored; retry the erasure in a few seconds (Retry-After: 5)
- `inbound_not_configured` (HTTP 503)

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/emails/receiving/019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
  "deleted": true
}
```

## Limits

**Inbound limits**

- **Message size**: 40 MB, headers and attachments included.
- **Structure**: At most 1,000 MIME parts and 100 multipart sections. A message the parser cannot read is refused with `550 5.6.0`.
- **Retention**: Your plan’s log retention: 3 days on Free, 30 on Pro, 90 on Scale. Older messages answer 404.
- **Routes**: 100 per account; patterns up to 512 bytes (UTF-8).
- **Forward destinations**: 20 per account; confirmation resent at most once a minute.
- **Webhook content**: Text and HTML share 1 MB with `include_content`; `reply_text` is cut at 16 KB in the webhook.
- **Download links**: 1 hour from the API, 24 hours in a webhook.
- **Replies**: 20 per conversation per hour.
- **Reply addresses**: 30 days, 100 replies a day each.
- **Encryption**: Optional per domain: with `require_tls`, senders that do not use STARTTLS get `530 5.7.0`.

## Walk-through: a support inbox

Put it together: customers write to `support@support.acme.com`, every conversation becomes a ticket, new tickets get an acknowledgement, and agents answer from the app.

1. Add `support.acme.com` as an inbound domain, publish its MX record and verify it (above).
2. Create an endpoint for `email.received` and keep its `whsec_…` secret as `ZAP_WEBHOOK_SECRET`.
3. Optionally route `support*@support.acme.com` to that endpoint only, and `store` mailing-list mail.
4. Deploy the handler below. It checks the signature on the raw body, skips duplicates by `Zap-Event-Id` and spam, files the message under the ticket of its `thread_id`, and acknowledges new tickets a person wrote, marked as an auto-reply and made idempotent by the email id.

**Support inbox webhook**

Node.js:

```javascript
import crypto from 'node:crypto';
import express from 'express';
import { db } from './db.js'; // your storage

const API = 'https://zapsmtp.xyz/v1';

async function zap(method, path, body, idempotencyKey) {
  const headers = { Authorization: 'Bearer ' + process.env.ZAP_API_KEY };
  if (body) headers['Content-Type'] = 'application/json';
  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
  const res = await fetch(API + path, { method, headers, body: body && JSON.stringify(body) });
  if (!res.ok) throw new Error(method + ' ' + path + ': ' + res.status + ' ' + (await res.text()));
  return res.json();
}

function verified(req) {
  const parts = (req.get('Zap-Signature') ?? '').split(',').map((p) => p.split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  const expected = crypto.createHmac('sha256', process.env.ZAP_WEBHOOK_SECRET)
    .update(t + '.' + req.body).digest('hex');
  return Math.abs(Date.now() / 1000 - Number(t)) < 300 &&
    parts.some(([k, v]) => k === 'v1' && v.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
}

const app = express();
app.post('/hooks/inbound', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verified(req)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  const eventId = req.get('Zap-Event-Id');
  if (event.type !== 'email.received' || await db.seen(eventId)) return res.sendStatus(200);

  const m = event.data;
  if (m.spam.is_spam) return res.sendStatus(200);

  // 1. find or open the ticket for this conversation
  let ticket = await db.ticketByThread(m.thread_id);
  const isNew = !ticket;
  if (isNew) ticket = await db.createTicket({ threadId: m.thread_id, customer: m.from, subject: m.subject });

  // 2. store the message: the full body comes from the API
  const email = await zap('GET', '/emails/receiving/' + m.email_id);
  await db.addMessage(ticket.id, {
    emailId: m.email_id, from: m.from, text: m.reply_text || email.text, html: email.html,
    attachments: email.attachments.map((a) => ({ id: a.id, name: a.filename, size: a.size })),
    automated: m.automated?.type ?? null,
  });

  // 3. acknowledge new tickets that a person wrote
  if (isNew && !m.automated) {
    await zap('POST', '/emails/receiving/' + m.email_id + '/reply', {
      from: 'Acme Support <support@acme.com>',
      text: 'Thanks, we got your message. Your ticket number is ' + ticket.number + '.',
      auto_reply: true,
    }, 'ack-' + m.email_id);
  }
  await db.markSeen(eventId);
  res.sendStatus(200);
});
app.listen(3000);
```

Python:

```python
import hashlib, hmac, json, os, time
import requests
from flask import Flask, request
from myapp import db  # your storage

API = "https://zapsmtp.xyz/v1"
app = Flask(__name__)

def zap(method, path, body=None, idempotency_key=None):
    headers = {"Authorization": f"Bearer {os.environ['ZAP_API_KEY']}"}
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    r = requests.request(method, API + path, json=body, headers=headers, timeout=30)
    r.raise_for_status()
    return r.json()

def verified(raw: bytes) -> bool:
    parts = [p.split("=", 1) for p in request.headers.get("Zap-Signature", "").split(",") if "=" in p]
    t = next((v for k, v in parts if k == "t"), "0")
    expected = hmac.new(os.environ["ZAP_WEBHOOK_SECRET"].encode(),
                        f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(t)) < 300
    return fresh and any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)

@app.post("/hooks/inbound")
def inbound():
    raw = request.get_data()
    if not verified(raw):
        return "", 400
    event = json.loads(raw)
    event_id = request.headers["Zap-Event-Id"]
    if event["type"] != "email.received" or db.seen(event_id):
        return "", 200

    m = event["data"]
    if m["spam"]["is_spam"]:
        return "", 200

    # 1. find or open the ticket for this conversation
    ticket = db.ticket_by_thread(m["thread_id"])
    is_new = ticket is None
    if is_new:
        ticket = db.create_ticket(thread_id=m["thread_id"], customer=m["from"], subject=m["subject"])

    # 2. store the message: the full body comes from the API
    email = zap("GET", f"/emails/receiving/{m['email_id']}")
    db.add_message(ticket.id, email_id=m["email_id"], sender=m["from"],
                   text=m["reply_text"] or email["text"], html=email["html"],
                   attachments=[(a["id"], a["filename"], a["size"]) for a in email["attachments"]],
                   automated=(m["automated"] or {}).get("type"))

    # 3. acknowledge new tickets that a person wrote
    if is_new and m["automated"] is None:
        zap("POST", f"/emails/receiving/{m['email_id']}/reply", {
            "from": "Acme Support <support@acme.com>",
            "text": f"Thanks, we got your message. Your ticket number is {ticket.number}.",
            "auto_reply": True,
        }, idempotency_key=f"ack-{m['email_id']}")
    db.mark_seen(event_id)
    return "", 200
```

Go:

```go
package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const api = "https://zapsmtp.xyz/v1"

type received struct {
	Type string `json:"type"`
	Data struct {
		EmailID   string `json:"email_id"`
		From      string `json:"from"`
		Subject   string `json:"subject"`
		ThreadID  string `json:"thread_id"`
		ReplyText string `json:"reply_text"`
		Automated *struct{ Type, Reason string } `json:"automated"`
		Spam      struct{ IsSpam bool `json:"is_spam"` } `json:"spam"`
	} `json:"data"`
}

func zap(method, path string, body any, idemKey string, out any) error {
	var rd io.Reader
	if body != nil {
		b, _ := json.Marshal(body)
		rd = bytes.NewReader(b)
	}
	req, _ := http.NewRequest(method, api+path, rd)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("ZAP_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	if idemKey != "" {
		req.Header.Set("Idempotency-Key", idemKey)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		return fmt.Errorf("%s %s: %d %s", method, path, res.StatusCode, msg)
	}
	if out == nil {
		return nil
	}
	return json.NewDecoder(res.Body).Decode(out)
}

func verified(header string, body []byte) bool {
	var t string
	var sigs []string
	for _, part := range strings.Split(header, ",") {
		k, v, _ := strings.Cut(part, "=")
		switch k {
		case "t":
			t = v
		case "v1":
			sigs = append(sigs, v)
		}
	}
	mac := hmac.New(sha256.New, []byte(os.Getenv("ZAP_WEBHOOK_SECRET")))
	mac.Write([]byte(t + "."))
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))
	ts, _ := strconv.ParseInt(t, 10, 64)
	if time.Since(time.Unix(ts, 0)).Abs() > 5*time.Minute {
		return false
	}
	for _, s := range sigs {
		if hmac.Equal([]byte(s), []byte(expected)) {
			return true
		}
	}
	return false
}

func inbound(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	if !verified(r.Header.Get("Zap-Signature"), body) {
		http.Error(w, "bad signature", http.StatusBadRequest)
		return
	}
	var ev received
	eventID := r.Header.Get("Zap-Event-Id")
	if json.Unmarshal(body, &ev) != nil || ev.Type != "email.received" || db.Seen(eventID) {
		w.WriteHeader(http.StatusOK)
		return
	}
	m := ev.Data
	if m.Spam.IsSpam {
		w.WriteHeader(http.StatusOK)
		return
	}

	// 1. find or open the ticket for this conversation
	ticket, isNew := db.TicketByThread(m.ThreadID), false
	if ticket == nil {
		ticket, isNew = db.CreateTicket(m.ThreadID, m.From, m.Subject), true
	}

	// 2. store the message: the full body comes from the API
	var email struct {
		Text, HTML  *string
		Attachments []struct {
			ID       string `json:"id"`
			Filename string `json:"filename"`
			Size     int    `json:"size"`
		}
	}
	if err := zap("GET", "/emails/receiving/"+m.EmailID, nil, "", &email); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError) // retried by ZapSMTP
		return
	}
	db.AddMessage(ticket.ID, m.EmailID, m.From, m.ReplyText, email.Text, email.HTML)

	// 3. acknowledge new tickets that a person wrote
	if isNew && m.Automated == nil {
		ack := map[string]any{
			"from":       "Acme Support <support@acme.com>",
			"text":       fmt.Sprintf("Thanks, we got your message. Your ticket number is %d.", ticket.Number),
			"auto_reply": true,
		}
		if err := zap("POST", "/emails/receiving/"+m.EmailID+"/reply", ack, "ack-"+m.EmailID, nil); err != nil {
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
	}
	db.MarkSeen(eventID)
	w.WriteHeader(http.StatusOK)
}
```

PHP:

```php
<?php
// your storage: $db->seen(), ticketByThread(), createTicket(), addMessage(), markSeen()
require __DIR__ . '/db.php';

const API = 'https://zapsmtp.xyz/v1';

function zap(string $method, string $path, ?array $body = null, ?string $idemKey = null): array {
    $headers = ['Authorization: Bearer ' . getenv('ZAP_API_KEY'), 'Content-Type: application/json'];
    if ($idemKey) $headers[] = 'Idempotency-Key: ' . $idemKey;
    $ch = curl_init(API . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),
    ]);
    $out = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($status >= 300) throw new RuntimeException("$method $path: $status $out");
    return json_decode($out, true);
}

$raw = file_get_contents('php://input');
$t = null; $sigs = [];
foreach (explode(',', $_SERVER['HTTP_ZAP_SIGNATURE'] ?? '') as $part) {
    [$k, $v] = array_pad(explode('=', $part, 2), 2, '');
    if ($k === 't') $t = $v;
    if ($k === 'v1') $sigs[] = $v;
}
$expected = hash_hmac('sha256', $t . '.' . $raw, getenv('ZAP_WEBHOOK_SECRET'));
$valid = abs(time() - (int) $t) < 300
    && count(array_filter($sigs, fn ($s) => hash_equals($expected, $s))) > 0;
if (!$valid) { http_response_code(400); exit; }

$event = json_decode($raw, true);
$eventId = $_SERVER['HTTP_ZAP_EVENT_ID'] ?? '';
if ($event['type'] !== 'email.received' || $db->seen($eventId)) { http_response_code(200); exit; }

$m = $event['data'];
if ($m['spam']['is_spam']) { http_response_code(200); exit; }

// 1. find or open the ticket for this conversation
$ticket = $db->ticketByThread($m['thread_id']);
$isNew = $ticket === null;
if ($isNew) $ticket = $db->createTicket($m['thread_id'], $m['from'], $m['subject']);

// 2. store the message: the full body comes from the API
$email = zap('GET', '/emails/receiving/' . $m['email_id']);
$db->addMessage($ticket['id'], $m['email_id'], $m['from'], $m['reply_text'] ?: $email['text'], $email['html'],
    array_map(fn ($a) => [$a['id'], $a['filename'], $a['size']], $email['attachments']));

// 3. acknowledge new tickets that a person wrote
if ($isNew && $m['automated'] === null) {
    zap('POST', '/emails/receiving/' . $m['email_id'] . '/reply', [
        'from' => 'Acme Support <support@acme.com>',
        'text' => 'Thanks, we got your message. Your ticket number is ' . $ticket['number'] . '.',
        'auto_reply' => true,
    ], 'ack-' . $m['email_id']);
}
$db->markSeen($eventId);
http_response_code(200);
```

When an agent answers, call reply with the id of the customer’s latest email, `from: "Acme Support <support@acme.com>"` and the agent’s text, then mark the conversation read. Build the agents’ queue from GET /threads?awaiting_reply=true: it drops a conversation as soon as you send anything in it (the acknowledgement included) and brings it back when the customer writes again. To keep new tickets in the queue until an agent answers, track that in your own ticket state or in the conversation's `metadata`.

> Answer the webhook within a few seconds. If your handler does slow work (large attachments, an AI summary), store the event and do it in a background job: a timed-out delivery is retried, and the stable `Zap-Event-Id` plus the reply’s `Idempotency-Key` keep a retry from filing or answering twice.

---

# Deliverability guide

Source: https://www.zapsmtp.xyz/docs/deliverability/

What mailbox providers require from senders today, what ZapSMTP already does for you, and what is still yours to do: authentication, unsubscribe, warm-up, list hygiene, content and monitoring, with the API calls for each step.

## Sender requirements

Since February 2024 Gmail and Yahoo enforce rules for everyone who sends to their users, with stricter rules for bulk senders (Google counts a sender as bulk after close to 5,000 messages a day to Gmail addresses). Since May 2025 Outlook.com applies similar rules to senders above 5,000 messages a day. Mail that does not meet them is deferred, sent to spam or rejected.

**Requirements and how ZapSMTP covers them**

- **SPF and DKIM (All senders: at least one. Bulk: both.)**: Every verified domain has its own 2048-bit DKIM key and ZapSMTP signs every message with it. SPF passes for the Return-Path, which is a ZapSMTP bounce domain. **Yours:** publish the DKIM record (required to verify) and the SPF include.
- **DMARC (Bulk senders. `p=none` is enough.)**: ZapSMTP suggests a record and collects aggregate reports for you (DMARC reports). **Yours:** publish `_dmarc` on your domain.
- **Alignment (Bulk: the From domain matches the SPF or DKIM domain.)**: DKIM is signed with `d=` your exact From domain, so DMARC passes through DKIM alignment, even with `adkim=s`. See Alignment.
- **One-click unsubscribe (Bulk, for marketing and subscribed mail. RFC 8058. Honour within 2 days.)**: On the `broadcast` stream ZapSMTP adds `List-Unsubscribe` and `List-Unsubscribe-Post`; a click stops broadcast mail to the address at once. **Yours:** send marketing on `broadcast` and put a visible link in the body.
- **Spam rate (Below 0.3% in Google Postmaster Tools; aim below 0.1%.)**: Complaints from feedback loops suppress the address automatically. **Yours:** consent, expected content, and watching complaint rates.
- **PTR (reverse DNS) (All senders.)**: ZapSMTP’s sending IPs have reverse DNS names; each dedicated IP lists its `hostname`. Nothing for you to do.
- **TLS (All senders.)**: STARTTLS whenever the receiver offers it; receivers with MTA-STS or DANE are only reached over a verified connection. `tls: "required"` or `"verified"` per domain or email raises the bar.
- **RFC 5322 format (All senders.)**: ZapSMTP builds the message: one From, Date, Message-ID, MIME structure. Reserved headers cannot be overridden through the API.

## Authenticate your domain

Add each domain you send from. ZapSMTP matches the From domain exactly: `news.acme.com` is a separate domain from `acme.com`, with its own key. A domain counts as verified once its DKIM record is found; SPF and DMARC are checked and reported but not required to send.

- **DKIM.** A TXT record at `<selector>._domainkey.<domain>`. Copy it exactly: one changed character makes every signature fail.
- **SPF.** A domain may have only *one* `v=spf1` record. Two records are a permanent error at receivers; `verify` warns about it. Add the include to your existing record instead. Keep the record under 10 DNS lookups.
- **DMARC.** Start with `p=none` and a `rua` address so you see who sends as your domain. Move to `quarantine` and `reject` once every legitimate source passes. A DMARC record on `acme.com` also covers subdomains unless they publish their own or you set `sp=`.

**DNS records**

Zone file:

```
; DKIM: required. Selector and key come from GET /domains/{id}
<selector>._domainkey.news.acme.com.  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkq..."

; SPF: one record per name. Merge the include into an existing record
news.acme.com.                       TXT  "v=spf1 include:<value from your records> ~all"

; DMARC: start with p=none and the rua from GET /domains/{id}/dmarc
_dmarc.news.acme.com.                TXT  "v=DMARC1; p=none; rua=<your rua>"
```

DMARC stages:

```
; 1. Monitor (2-4 weeks): read reports, fix every legitimate source
_dmarc.acme.com.  TXT  "v=DMARC1; p=none; rua=<your rua>"

; 2. Quarantine a share of failing mail, then raise pct to 100
_dmarc.acme.com.  TXT  "v=DMARC1; p=quarantine; pct=25; rua=<your rua>"

; 3. Reject everything that fails
_dmarc.acme.com.  TXT  "v=DMARC1; p=reject; rua=<your rua>"
```

## Add a subdomain for marketing mail

`POST /v1/domains`

Every From domain is verified on its own: `news.acme.com` gets its own DKIM key and records, and its reputation is tracked separately from `acme.com`.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string, required): Domain name (lowercased, trailing dot removed). Limits: valid hostname <=253 chars, else 422 invalid_parameter "invalid domain name"

### Errors

- `plan_limit_reached` (HTTP 403): the <Plan> plan includes <n> domains; upgrade your plan to add more
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): domain already added
- `invalid_parameter` (HTTP 422): invalid domain name

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "news.acme.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "pending",
  "dkim_selector": "zap",
  "dkim_verified": false,
  "spf_verified": false,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": null,
  "verified_at": null,
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "pending"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "pending"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ]
}
```

## Verify the records

`POST /v1/domains/{id}/verify`

Checks DKIM, SPF and DMARC live. The domain becomes `verified` once DKIM matches; `warnings` point out problems such as two SPF records.

Requires a full-access live key; test keys get 403 test_key_restricted.

`found` shows, per DNS name, what is published right now. For the root domain only SPF-type TXT values are listed; a DMARC policy inherited from the parent domain is marked “(inherited from _dmarc.<domain>)”.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `conflict` (HTTP 409): this domain is already verified by another account

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/verify' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T14:02:11Z",
  "verified_at": "2026-10-21T14:02:11Z",
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ],
  "found": {
    "zap._domainkey.acme.com": [
      "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
    ],
    "acme.com": [
      "v=spf1 include:_spf.zapsmtp.xyz ~all"
    ]
  }
}
```

## Alignment, with examples

DMARC passes when SPF or DKIM passes *and* the domain it passed for is aligned with the domain in the visible From header. Relaxed alignment (the default, `adkim=r` / `aspf=r`) accepts any domain under the same organisational domain; strict (`=s`) needs the exact domain.

**From: news@news.acme.com**

- **DKIM `d=news.acme.com`**: Aligned, relaxed and strict. This is what ZapSMTP signs, because the key belongs to the exact From domain.
- **DKIM `d=acme.com`**: Aligned in relaxed mode (same organisational domain), not in strict mode.
- **DKIM `d=mailer-provider.example`**: Not aligned. Typical for a service that signs with its own domain; DMARC fails unless SPF aligns.
- **SPF for Return-Path `bounces.acme.com`**: Aligned in relaxed mode.
- **SPF for a ZapSMTP bounce domain**: Passes, but not aligned with your From domain. ZapSMTP keeps the Return-Path on its own domain so it can process bounces for you; DMARC relies on DKIM alignment, which is always present.

> Forwarding and mailing lists often break SPF but keep DKIM intact. Mail that is aligned through DKIM, as ZapSMTP mail is, survives forwarding better than mail that relies on SPF alone.

## Read your DMARC reports

`GET /v1/domains/{id}/dmarc`

Aggregate reports from Gmail, Yahoo, Microsoft and other receivers, summed per day and per sending IP. `record` is a suggested DMARC record that already contains your `rua` address.

Requires a full-access key.

Add `rua` to your DMARC record (keep your policy). Providers send one report a day; reports are kept 400 days. `ours` marks ZapSMTP sending IPs: another IP that fails DMARC is a service you have not set up (add its DKIM/SPF) or someone spoofing your domain.

### Path parameters

- `id` (string): Domain id.

### Query parameters

- `days` (integer): 1-180; out-of-range falls back to 30. Default `30`.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): Not a domain of this account.

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/dmarc?days=30' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "dmarc_summary",
  "domain": "acme.com",
  "days": 30,
  "since": "2026-09-26T00:00:00Z",
  "rua": "mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz",
  "record": {
    "type": "TXT",
    "name": "_dmarc.acme.com",
    "value": "v=DMARC1; p=none; rua=mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz"
  },
  "reports": 42,
  "totals": {
    "messages": 18240,
    "passed": 18015,
    "dkim_passed": 18001,
    "spf_passed": 17890,
    "quarantined": 190,
    "rejected": 35
  },
  "sources": [
    {
      "ip": "192.0.2.10",
      "messages": 18000,
      "passed": 17990,
      "dkim_passed": 17985,
      "spf_passed": 17880,
      "quarantined": 10,
      "rejected": 0,
      "reporters": [
        "Yahoo",
        "google.com"
      ],
      "ours": true
    },
    {
      "ip": "203.0.113.5",
      "messages": 240,
      "passed": 25,
      "dkim_passed": 16,
      "spf_passed": 10,
      "quarantined": 180,
      "rejected": 35,
      "reporters": [
        "google.com"
      ],
      "ours": false
    }
  ],
  "reporters": [
    {
      "org": "google.com",
      "reports": 30,
      "messages": 15400
    },
    {
      "org": "Yahoo",
      "reports": 12,
      "messages": 2840
    }
  ],
  "series": [
    {
      "day": "2026-10-24T00:00:00Z",
      "messages": 640,
      "passed": 632,
      "dkim_passed": 632,
      "spf_passed": 628,
      "quarantined": 6,
      "rejected": 2
    }
  ]
}
```

## One-click unsubscribe

Gmail and Yahoo require RFC 8058 one-click unsubscribe on marketing and subscribed mail from bulk senders: a `List-Unsubscribe` header with an HTTPS URL plus `List-Unsubscribe-Post: List-Unsubscribe=One-Click`. The provider shows an Unsubscribe button and sends a POST to the URL; you must stop mailing within two days. Transactional mail (receipts, password resets) does not need it.

**What ZapSMTP does**

- **`stream: "broadcast"`**: Adds both headers with a URL signed for the recipient, when the email has exactly one recipient (after suppressed addresses are dropped) and you did not set `List-Unsubscribe` yourself. Send one recipient per email; use [batch](https://www.zapsmtp.xyz/docs/emails/send-batch/) for up to 100 at a time.
- **`{{{zap:unsubscribe_url}}}`**: In `html` or `text`, templated or not, on any stream: replaced at send time with the recipient’s signed unsubscribe link. It is never wrapped by click tracking.
- **One-click POST**: Adds the address to your suppressions with reason `unsubscribe`, immediately. Later `broadcast` mail to it is suppressed; transactional mail still goes out.
- **Link opened in a browser**: Shows a confirmation page with an Unsubscribe button, so link scanners that only follow links cannot unsubscribe anyone.
- **SMTP relay**: Headers are not added and the tag is not replaced: set `List-Unsubscribe` and `List-Unsubscribe-Post` in your mailer.

> An unsubscribe stops `broadcast` mail only. Someone who unsubscribes through a ZapSMTP link (or whom you add with reason `unsubscribe`) no longer gets your marketing mail, but receipts, password resets and other `transactional` mail still reach them, so send marketing on `broadcast`. Hard bounces, complaints and `manual` suppressions stop every stream. Unsubscribes are account-wide: if you need opt-outs per list, set your own `List-Unsubscribe` headers that point at your endpoint, and keep the preference in your own database.

## Send a newsletter with one-click unsubscribe

`POST /v1/emails`

On the `broadcast` stream ZapSMTP adds `List-Unsubscribe` and `List-Unsubscribe-Post`, and `{{{zap:unsubscribe_url}}}` in the body becomes the same signed link for this recipient.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme News <news@news.acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "October product update",
  "stream": "broadcast",
  "html": "<p>Hi Ann, here is what shipped in October.</p><p><a href=\"{{{zap:unsubscribe_url}}}\">Unsubscribe</a></p>",
  "text": "Hi Ann, here is what shipped in October.\n\nUnsubscribe: {{{zap:unsubscribe_url}}}",
  "tags": [
    {
      "name": "campaign",
      "value": "october-update"
    }
  ]
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Use your own unsubscribe endpoint

`POST /v1/emails`

When you set `List-Unsubscribe` yourself, ZapSMTP keeps your headers and adds nothing. Your endpoint must accept the one-click POST.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme News <news@news.acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "October product update",
  "stream": "broadcast",
  "html": "<p>Hi Ann, here is what shipped in October.</p><p><a href=\"https://acme.com/u/8f3a2c\">Unsubscribe</a></p>",
  "text": "Hi Ann, here is what shipped in October.\n\nUnsubscribe: https://acme.com/u/8f3a2c",
  "headers": {
    "List-Unsubscribe": "<https://acme.com/u/8f3a2c>, <mailto:unsubscribe@acme.com?subject=8f3a2c>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Separate transactional and marketing mail

A complaint about a newsletter should never delay a password reset. Separate them on three levels:

- **Stream.** `stream: "transactional"` (the default) or `"broadcast"` on the API, `X-Zap-Stream` on SMTP. On shared IPs each stream has its own pool, so marketing reputation does not spill into transactional delivery. Accounts with dedicated IPs send both streams from them.
- **Subdomain.** Send marketing from `news.acme.com` and transactional from `acme.com` or `notify.acme.com`. Providers track reputation per domain as well, and [metrics](https://www.zapsmtp.xyz/docs/stats/metrics/) group by From domain.
- **API keys.** Restrict each key to a stream and a domain, so the marketing system cannot send as the transactional domain by mistake (`403 restricted_api_key`).

## Warm up a new domain or IP

Providers judge new domains and IPs by their first weeks of traffic. Start with your most engaged recipients (people who signed up or opened recently), raise volume gradually, and only increase when bounce and complaint rates stay low and deferrals are rare.

### A new domain on shared IPs

Shared IPs are already warm, but your domain is not. ZapSMTP does not cap a new domain, so pace it yourself. A typical plan for a list of 100,000:

**Suggested domain ramp**

- **Days 1–3**: 500–1,000 a day, recipients active in the last 30 days.
- **Days 4–7**: 2,000–5,000 a day, active in the last 60 days.
- **Week 2**: 10,000–20,000 a day, active in the last 90 days.
- **Week 3**: 30,000–50,000 a day.
- **Week 4**: Full list, if the previous week was clean. Hold or step back at the first wave of deferrals.

### Dedicated IPs

ZapSMTP warms dedicated IPs for you over 30 days. Each day the IP takes up to that day’s cap; anything above it goes out through the stream’s shared pool, so your email is never delayed. After day 30 the IP becomes `active` with no cap.

**Daily cap per dedicated IP (messages)**

- **Days 1–7**: 50 · 100 · 200 · 400 · 700 · 1,000 · 1,500
- **Days 8–14**: 2,000 · 3,000 · 4,000 · 5,000 · 7,000 · 9,000 · 12,000
- **Days 15–21**: 15,000 · 20,000 · 25,000 · 30,000 · 40,000 · 50,000 · 60,000
- **Days 22–28**: 75,000 · 90,000 · 110,000 · 130,000 · 150,000 · 175,000 · 200,000
- **Days 29–30**: 250,000 · 300,000

While an IP warms up, ZapSMTP checks it every 10 minutes against its last 6 hours of traffic (once it has at least 50 attempts) and pauses it when more than 5% bounce or more than 30% are deferred. A paused IP sends nothing; its traffic goes through the shared pool.

## Follow a dedicated IP’s warm-up

`GET /v1/dedicated-ips`

Each dedicated IP shows its status, warm-up day, today’s cap and current blocklist listings.

Requires a full-access key.

`status` is `warming`, `active` or `paused`. During warm-up, `warmup_day` and `daily_cap` show the current day and today’s volume limit. `blocklists` lists current listings of the IP.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/dedicated-ips' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "address": "203.0.113.25",
      "hostname": "mta25.zapsmtp.com",
      "status": "warming",
      "warmup_day": 9,
      "warmup_days": 30,
      "warmup_progress": 0.3,
      "daily_cap": 3000,
      "blocklists": []
    }
  ]
}
```

## Keep bounces and complaints low

ZapSMTP suppresses addresses automatically. A suppressed address is skipped on every later send it applies to, reported as `email.suppressed`, and not charged. An `unsubscribe` applies to the `broadcast` stream only; every other reason applies to both streams. A later bounce, complaint or `manual` suppression replaces an `unsubscribe` entry for the same address (an unsubscribe never replaces a stronger one), and removing an address clears it entirely.

**What adds an address to suppressions**

- **`hard_bounce`**: A permanent bounce with subType `MailboxDoesNotExist`, `DomainDoesNotExist` or `MailboxInactive`.
- **`complaint`**: A spam report delivered through a provider’s feedback loop.
- **`unsubscribe`**: A one-click unsubscribe or the confirmation button, or an address you add with this reason. Stops `broadcast` mail only.
- **`manual`**: Added by you, with this reason (the default).
- **Never**: Full mailboxes, temporary failures, and rejections caused by the sender side (`SpamBlocked`, `IPBlocked`, `PolicyRejected`): the recipient is valid, so it is not suppressed.

- **Collect consent properly.** Use double opt-in for marketing lists: it removes typos and spam traps before they cost you. Never buy or rent lists.
- **Sunset inactive recipients.** Stop marketing to people who have not opened or clicked in 6–12 months, or send them one re-engagement email first. Apple Mail Privacy Protection inflates opens (its proxy opens are flagged with `open.machine: true` on `email.opened` and left out of `human_open_rate`), so use human opens or, better, clicks for this.
- **Act on reply opt-outs.** With reply tracking, a reply that only says “unsubscribe” or “stop” arrives as `email.replied` with `reply.type: "unsubscribe"`. It is reported, not applied: add the address to suppressions yourself.
- **Migrating?** Import your previous provider’s bounces and unsubscribes before the first send.

> Gmail does not report individual complaints to senders, so ZapSMTP cannot see or suppress them. Your Gmail spam rate is only visible in [Google Postmaster Tools](https://postmaster.google.com/): add your domains there.

## List suppressed addresses

`GET /v1/suppressions`

Every address ZapSMTP will not send to, with the reason and the email that caused it.

Requires a full-access key.

`reason` is `hard_bounce`, `complaint`, `unsubscribe` or `manual`; `source_id` is the email that caused it (`null` when added by hand). Pass `next_cursor` as `after` for the next page.

`unsubscribe` stops only broadcast email (`stream: broadcast`); transactional email to the address still goes out. Every other reason stops all email to it.

### Query parameters

- `limit` (integer): 1-1000; out-of-range falls back to 100. Default `100`.
- `after` (string): Opaque cursor from next_cursor. Limits: 422 invalid_parameter "invalid after cursor"
- `before` (string): Legacy: RFC 3339 timestamp; returns entries created before it. Ignored when after is set. Limits: 422 invalid_parameter "before must be RFC3339"

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422)

```bash
curl 'https://zapsmtp.xyz/v1/suppressions?limit=100' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "email": "old@example.org",
      "reason": "hard_bounce",
      "source_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "created_at": "2026-10-21T15:04:13Z"
    },
    {
      "email": "angry@example.net",
      "reason": "complaint",
      "source_id": "019a1f2a-1b2c-7d3e-8f4a-5b6c7d8e9f00",
      "created_at": "2026-10-21T11:20:40Z"
    }
  ],
  "next_cursor": "MTc2MTA0NzI0MDAwMDAwMDAwMHxhbmdyeUBleGFtcGxlLm5ldA"
}
```

## Suppress an address yourself

`POST /v1/suppressions`

For opt-outs you collect elsewhere (a preference centre, a support request, a reply that says “stop”). Reason `unsubscribe` stops broadcast mail only; `manual` stops every stream.

Requires a full-access live key; test keys get 403 test_key_restricted.

Idempotent: an existing entry keeps its reason, except that an `unsubscribe` entry becomes `manual` when you add it as manual (a later bounce or complaint upgrades it the same way). The response echoes the requested reason with 201.

### Body parameters

- `email` (string, required): Address (stored lowercased). Limits: 422 invalid_parameter "invalid email"
- `reason` (string): `manual`: no email at all; `unsubscribe`: no broadcast email (transactional email still goes out). Limits: 422 invalid_parameter "reason must be manual or unsubscribe" One of `manual`, `unsubscribe`. Default `manual`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/suppressions' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "former-customer@example.com",
  "reason": "unsubscribe"
}'
```

**Response `201 Created`**

```json
{
  "email": "someone@example.org",
  "reason": "manual"
}
```

## Import your old provider’s suppressions

`POST /v1/suppressions/batch`

Up to 1,000 addresses per call. Import past bounces and unsubscribes before the first send, so you do not mail them again.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `emails` (string[], required): 1–1,000 addresses.
- `reason` (string): `manual`: no email at all; `unsubscribe`: no broadcast email (transactional email still goes out). One of `manual`, `unsubscribe`. Default `manual`.

### Errors

- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): Empty or over 1,000 addresses, an invalid address, or an unknown reason.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/suppressions/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "ann@example.com",
    "bob@example.com"
  ],
  "reason": "unsubscribe"
}'
```

**Response `201 Created`**

```json
{
  "object": "suppression_batch",
  "added": 2,
  "reason": "manual",
  "emails": [
    "ann@example.com",
    "bob@example.com"
  ]
}
```

## Receive bounces and complaints

`POST /v1/webhooks`

Sync suppressions into your own database so your app stops queueing mail to addresses that will never receive it.

Requires a full-access live key; test keys get 403 test_key_restricted.

The secret is also readable later via GET /webhooks/{id}.

To send clicks of one button to this endpoint: `{"events": ["email.clicked"], "filter": {"actions": ["confirm_order"]}}`. Endpoints always return `filter`, with an empty list when there is none.

### Body parameters

- `url` (string, required): Absolute https:// URL. Limits: 422 invalid_parameter "url must be an absolute https:// URL"
- `events` (string[]): Limits: unknown type → 422 invalid_parameter "unknown event type <x>; allowed: ..." One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `all event types`.
- `include_content` (boolean): `email.received` carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (`truncated: true`). Default `false`.
- `batch` (boolean): Send events up to 100 per request (or every second) as a JSON array, signed as one body; `Zap-Event-Id` is the batch id, each event keeps its own `id`. `email.received` with the full message still arrives alone. Default `false`.
- `filter` (object): Narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/); other event types are not affected. Empty or absent: every click. Default `{"actions": []}`.
  - `actions` (string[]): Action names (lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters). The endpoint then receives `email.clicked` only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/hooks/zapsmtp",
  "events": [
    "email.bounced",
    "email.complained",
    "email.suppressed"
  ]
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-21T15:40:00Z",
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": []
  }
}
```

**Mirror suppressions in your app**

Node.js:

```javascript
// After verifying Zap-Signature (see Webhook events):
app.post('/hooks/zapsmtp', express.json(), async (req, res) => {
  const { type, data } = req.body;
  if (type === 'email.complained') {
    await db.contacts.update({ email: data.to }, { marketing: false, reason: 'complaint' });
  }
  if (type === 'email.bounced' && data.bounce?.suppressed) {
    await db.contacts.update({ email: data.to }, { status: 'invalid' });
  }
  res.sendStatus(200);
});
```

Python:

```python
# After verifying Zap-Signature (see Webhook events):
@app.post("/hooks/zapsmtp")
def zapsmtp_hook():
    event = request.get_json()
    data = event["data"]
    if event["type"] == "email.complained":
        contacts.update(data["to"], marketing=False, reason="complaint")
    if event["type"] == "email.bounced" and (data.get("bounce") or {}).get("suppressed"):
        contacts.update(data["to"], status="invalid")
    return "", 200
```

## Content guidelines

- **Always send a text part.** HTML-only mail costs points with spam filters (`MIME_HTML_ONLY`). An API send with `html` and no `text` gets a text part generated from the HTML; write your own `text` when you want to control it. SMTP relay messages are sent exactly as given, so add the text part in your mailer.
- **Keep the HTML under 102 KB.** Gmail clips larger messages and hides the rest, including your unsubscribe link and the open-tracking pixel.
- **Balance text and images.** A single large image with little text looks like spam. Give every image `alt` text; many clients block images by default.
- **Link to your own domains.** Links should point at the domain in From or one you clearly own. Do not use public URL shorteners: they are shared with spammers and often listed on domain blocklists.
- **Click tracking rewrites links** to ZapSMTP’s link host. Where link domains matter more than click data, turn it off per email with `tracking: {"clicks": false}` or per domain.
- **Write like a person.** A recognisable From name, an honest subject, no ALL CAPS or strings of exclamation marks. Put the physical address and the unsubscribe link in marketing footers.
- **Attachments.** Prefer links over large attachments in bulk mail; executables and macro documents are rejected by many providers (`AttachmentRejected`).

## Spam-check before you send

The spam check runs SpamAssassin (headline `score`, spam at 5) and a second spam filter, and returns `verdict`: `good`, `needs_work`, `spam` or `rejected`, the worse of the two. Infrastructure problems come back separately in `issues`, so you do not rewrite good copy because of an IP listing:

**issues[].kind**

- **`not_signed`**: The From domain is not verified, so the message is not DKIM-signed and fails DMARC.
- **`ip_listed`**: The checked sending IP (a representative IP of your account) is on a blocklist.
- **`domain_listed`**: A domain in the message (sender or links) is on a domain blocklist.
- **`new_domain`**: A domain in the message was registered recently; it has no reputation yet.

## Spam-check a draft before a campaign

`POST /v1/emails/spam-check`

Scores the message as a receiving server sees it: DKIM-signed with your key, from a representative IP of your account (a dedicated IP first, else the stream’s shared pool), against live blocklists. Nothing is sent.

Requires a full-access or sending-access key.

Body: from missing or both html and text empty → 422 missing_required_field "from and html or text are required". Only these six fields are accepted (others → 400).

### Body parameters

- `from` (string, required): From address; when its domain is verified by the account the draft is DKIM-signed with the real key.
- `to` (string | string[]): Recipient(s); the first is used as envelope recipient. Limits: 422 invalid_parameter "to must be a string or an array of strings" Default `recipient@example.com`.
- `subject` (string)
- `html` (string): At least one of html and text is required.
- `text` (string)
- `stream` (string): Selects the shared pool used to pick the egress IP when the account has no dedicated IP. Default `transactional`.

### Errors

- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422)
- `rate_limit_exceeded` (HTTP 429): spam checks are limited to 30 per minute
- `service_unavailable` (HTTP 503): spam checks are busy, try again shortly
- `scanner_unavailable` (HTTP 503): the spam scanners are temporarily unavailable, try again

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/spam-check' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme News <news@news.acme.com>",
  "subject": "October product update",
  "stream": "broadcast",
  "html": "<p>Hi Ann, here is what shipped in October.</p><p><a href=\"https://acme.com/changelog\">Read the changelog</a></p>",
  "text": "Hi Ann, here is what shipped in October.\n\nRead the changelog: https://acme.com/changelog"
}'
```

**Response `200 OK`**

```json
{
  "object": "spam_check",
  "score": 1.3,
  "threshold": 5,
  "verdict": "good",
  "engines": [
    {
      "engine": "spamassassin",
      "score": 1.3,
      "threshold": 5,
      "verdict": "good",
      "rules": [
        {
          "name": "HTML_MESSAGE",
          "score": 0.001,
          "description": "HTML included in message"
        },
        {
          "name": "MIME_HTML_ONLY",
          "score": 1.1,
          "description": "Message only has text/html MIME parts"
        }
      ]
    }
  ],
  "dkim_signed": true,
  "sending_ip": "203.0.113.25",
  "issues": [],
  "note": "Scored as a receiving server sees it: DKIM-signed with your key, from a representative egress IP of your account, checked against live DNS blocklists. SpamAssassin is the headline score (≥ 5 = spam); a second filter is shown alongside."
}
```

## Spam-check an email that was already sent

`POST /v1/emails/{id}/spam-check`

Re-scores a sent email from its stored content (within your plan’s log retention), useful when one message landed in spam.

Requires a full-access key.

Always scored with the transactional pool's IP when the account has no dedicated IP. Availability follows GET /emails/{id}/content (plan log retention), although the 404 message says 7 days.

### Path parameters

- `id` (string, required): Email id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): content not available (kept for 7 days)
- `rate_limit_exceeded` (HTTP 429)
- `service_unavailable` (HTTP 503)
- `scanner_unavailable` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/spam-check' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "spam_check",
  "score": 6.2,
  "threshold": 5,
  "verdict": "spam",
  "engines": [
    {
      "engine": "spamassassin",
      "score": 6.2,
      "threshold": 5,
      "verdict": "spam",
      "rules": [
        {
          "name": "URIBL_BLOCKED",
          "score": 0.001,
          "description": "ADMINISTRATOR NOTICE: The query to URIBL was blocked"
        }
      ]
    }
  ],
  "dkim_signed": false,
  "sending_ip": "203.0.113.25",
  "issues": [
    {
      "kind": "not_signed",
      "message": "The From domain is not verified, so the message is not DKIM-signed and fails DMARC. Verify the domain before sending."
    }
  ],
  "note": "Scored as a receiving server sees it: DKIM-signed with your key, from a representative egress IP of your account, checked against live DNS blocklists. SpamAssassin is the headline score (≥ 5 = spam); a second filter is shown alongside.",
  "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Monitor

**Thresholds to watch**

- **`complaint_rate`**: Aim below 0.1%; act above 0.1%; never reach 0.3% (Gmail and Yahoo limit). Rate of delivered mail.
- **`bounce_rate`**: Healthy below 2%; above 5% means a list problem. Rate of sent mail.
- **`delayed`**: A sudden rise at one provider means throttling: lower volume there.
- **DMARC `passed`**: Close to 100% of messages from `ours: true` sources. Failing unknown sources mean an unconfigured service or spoofing.
- **Blocklists**: Should be empty. ZapSMTP checks its sending IPs every 15 minutes and verified domains every 6 hours.

Metrics are kept for 400 days and exclude test-mode mail. The [dashboard](https://www.zapsmtp.xyz/docs/dashboard/) shows the same numbers.

## Bounce and complaint rates per provider

`GET /v1/metrics`

Rates per mailbox provider for the broadcast stream over the last 7 days. `bounce_rate` is of sent, `complaint_rate` of delivered.

Requires a full-access key.

Counts are recipients, except `delayed`, `opened` and `clicked`: unique emails. Delivery and bounce rates are of `sent`; complaint, open and click rates of `delivered`. Test-mode mail is excluded. Kept for 400 days.

An out-of-band bounce (a later bounce email from the remote server) has no sending domain: it is grouped under an empty `value`.

Totals and the series count each email once whatever the dimension; with `dimension=tag` an email with several tags appears in each of its tags' groups.

### Query parameters

- `from` (string): RFC 3339 start. At most 400 days before `to`. Default `7 days ago`.
- `to` (string): RFC 3339 end (exclusive). Default `now`.
- `granularity` (string): `hour` (ranges up to 31 days) or `day` for `series`. Default `hour up to 48 hours, else day`.
- `dimension` (string): `domain`, `stream`, `tag` or `provider`: adds `groups`, one row per value, busiest first.
- `domain` (string): Only this sending (From) domain.
- `stream` (string): `transactional` or `broadcast`.
- `provider` (string): Gmail, Microsoft, Yahoo, Apple or Other.
- `tag` (string): Only emails with this tag, as `name=value`. Cannot be combined with domain, stream or provider, and groups only by `tag`.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): Bad time, range, granularity or dimension, or a tag combined with another filter.

```bash
curl 'https://zapsmtp.xyz/v1/metrics?dimension=provider&stream=broadcast' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "metrics",
  "from": "2026-10-18T00:00:00Z",
  "to": "2026-10-25T00:00:00Z",
  "granularity": "day",
  "dimension": "domain",
  "totals": {
    "sent": 12400,
    "delivered": 12210,
    "bounced": 95,
    "delayed": 3,
    "complained": 4,
    "opened": 4380,
    "human_opened": 2409,
    "clicked": 912,
    "suppressed": 2,
    "failed": 0,
    "delivery_rate": 0.9847,
    "bounce_rate": 0.0077,
    "complaint_rate": 0.0003,
    "open_rate": 0.3587,
    "human_open_rate": 0.1972,
    "click_rate": 0.0747
  },
  "series": [
    {
      "time": "2026-10-18T00:00:00Z",
      "sent": 1700,
      "delivered": 1676,
      "bounced": 14,
      "delayed": 3,
      "complained": 1,
      "opened": 601,
      "human_opened": 331,
      "clicked": 120,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9859,
      "bounce_rate": 0.0082,
      "complaint_rate": 0.0006,
      "open_rate": 0.3586,
      "human_open_rate": 0.1974,
      "click_rate": 0.0716
    }
  ],
  "groups": [
    {
      "value": "acme.com",
      "sent": 9800,
      "delivered": 9668,
      "bounced": 70,
      "delayed": 3,
      "complained": 3,
      "opened": 3540,
      "human_opened": 1947,
      "clicked": 760,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9865,
      "bounce_rate": 0.0071,
      "complaint_rate": 0.0003,
      "open_rate": 0.3662,
      "human_open_rate": 0.2013,
      "click_rate": 0.0786
    },
    {
      "value": "news.acme.com",
      "sent": 2600,
      "delivered": 2542,
      "bounced": 25,
      "delayed": 3,
      "complained": 1,
      "opened": 840,
      "human_opened": 462,
      "clicked": 152,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9777,
      "bounce_rate": 0.0096,
      "complaint_rate": 0.0004,
      "open_rate": 0.3304,
      "human_open_rate": 0.1817,
      "click_rate": 0.0598
    }
  ]
}
```

## Compare your sending domains

`GET /v1/metrics`

One row per From domain, so a problem on `news.acme.com` does not hide inside your total.

Requires a full-access key.

Counts are recipients, except `delayed`, `opened` and `clicked`: unique emails. Delivery and bounce rates are of `sent`; complaint, open and click rates of `delivered`. Test-mode mail is excluded. Kept for 400 days.

An out-of-band bounce (a later bounce email from the remote server) has no sending domain: it is grouped under an empty `value`.

Totals and the series count each email once whatever the dimension; with `dimension=tag` an email with several tags appears in each of its tags' groups.

### Query parameters

- `from` (string): RFC 3339 start. At most 400 days before `to`. Default `7 days ago`.
- `to` (string): RFC 3339 end (exclusive). Default `now`.
- `granularity` (string): `hour` (ranges up to 31 days) or `day` for `series`. Default `hour up to 48 hours, else day`.
- `dimension` (string): `domain`, `stream`, `tag` or `provider`: adds `groups`, one row per value, busiest first.
- `domain` (string): Only this sending (From) domain.
- `stream` (string): `transactional` or `broadcast`.
- `provider` (string): Gmail, Microsoft, Yahoo, Apple or Other.
- `tag` (string): Only emails with this tag, as `name=value`. Cannot be combined with domain, stream or provider, and groups only by `tag`.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): Bad time, range, granularity or dimension, or a tag combined with another filter.

```bash
curl 'https://zapsmtp.xyz/v1/metrics?dimension=domain&granularity=day' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "metrics",
  "from": "2026-10-18T00:00:00Z",
  "to": "2026-10-25T00:00:00Z",
  "granularity": "day",
  "dimension": "domain",
  "totals": {
    "sent": 12400,
    "delivered": 12210,
    "bounced": 95,
    "delayed": 3,
    "complained": 4,
    "opened": 4380,
    "human_opened": 2409,
    "clicked": 912,
    "suppressed": 2,
    "failed": 0,
    "delivery_rate": 0.9847,
    "bounce_rate": 0.0077,
    "complaint_rate": 0.0003,
    "open_rate": 0.3587,
    "human_open_rate": 0.1972,
    "click_rate": 0.0747
  },
  "series": [
    {
      "time": "2026-10-18T00:00:00Z",
      "sent": 1700,
      "delivered": 1676,
      "bounced": 14,
      "delayed": 3,
      "complained": 1,
      "opened": 601,
      "human_opened": 331,
      "clicked": 120,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9859,
      "bounce_rate": 0.0082,
      "complaint_rate": 0.0006,
      "open_rate": 0.3586,
      "human_open_rate": 0.1974,
      "click_rate": 0.0716
    }
  ],
  "groups": [
    {
      "value": "acme.com",
      "sent": 9800,
      "delivered": 9668,
      "bounced": 70,
      "delayed": 3,
      "complained": 3,
      "opened": 3540,
      "human_opened": 1947,
      "clicked": 760,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9865,
      "bounce_rate": 0.0071,
      "complaint_rate": 0.0003,
      "open_rate": 0.3662,
      "human_open_rate": 0.2013,
      "click_rate": 0.0786
    },
    {
      "value": "news.acme.com",
      "sent": 2600,
      "delivered": 2542,
      "bounced": 25,
      "delayed": 3,
      "complained": 1,
      "opened": 840,
      "human_opened": 462,
      "clicked": 152,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9777,
      "bounce_rate": 0.0096,
      "complaint_rate": 0.0004,
      "open_rate": 0.3304,
      "human_open_rate": 0.1817,
      "click_rate": 0.0598
    }
  ]
}
```

## Check your domain against blocklists

`GET /v1/domains/{id}/reputation`

The domain’s status on Spamhaus DBL, SURBL and URIBL, with listing and delisting events. `worst` is empty when nothing is listed.

Requires a full-access key.

Customer domains are checked automatically every 6 hours (operator-configurable). The exact JSON for codes/labels when empty (null vs []) depends on the stored arrays; not verified.

### Path parameters

- `id` (string (UUID), required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): domain not found

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/reputation' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "domain_reputation",
  "domain": "acme.com",
  "worst": "",
  "lists": [
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "spamhaus-dbl",
      "name": "Spamhaus DBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://check.spamhaus.org/"
    },
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "surbl",
      "name": "SURBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://www.surbl.org/surbl-analysis"
    },
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "uribl",
      "name": "URIBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://admin.uribl.com/"
    }
  ],
  "events": [
    {
      "id": "019a1e00-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "target": "acme.com",
      "kind": "domain",
      "list": "uribl",
      "name": "URIBL",
      "event": "delisted",
      "severity": null,
      "codes": [],
      "detail": "",
      "at": "2026-10-19T06:00:02Z"
    }
  ]
}
```

## Re-check right after a delisting

`POST /v1/domains/{id}/reputation/check`

Runs the domain lookups now instead of waiting for the next scheduled check. At most once a minute.

Requires a full-access live key; test keys get 403 test_key_restricted.

At most once per minute per domain name. No Retry-After header is set.

### Path parameters

- `id` (string (UUID), required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `rate_limit_exceeded` (HTTP 429): this domain was checked less than a minute ago

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/reputation/check' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `200`.

## Troubleshooting

**Symptom, likely cause, what to do**

- **Bounces with subType `PolicyRejected`, replies mention DMARC, SPF or “unauthenticated”**: The From domain is not verified, DKIM is missing, or a strict DMARC policy rejects mail from a source you have not set up.Run verify and check `warnings`. In the DMARC summary, look for sources with `ours: false`.
- **Gmail replies `421 4.7.28` or `550 5.7.28`, Yahoo defers with `TSS04`**: Volume rose faster than the domain’s or IP’s reputation allows, or recipients complain.Slow down and follow the warm-up curve. ZapSMTP keeps retrying deferrals. Send only to engaged recipients until the deferrals stop.
- **Bounces with subType `IPBlocked`**: The provider refuses the sending IP (for example Microsoft S3150 or a blocklist).The recipient is not suppressed. A permanent refusal from a major provider pauses the IP at once; temporary refusals pause it after 5 within an hour; refusals from other destinations need several destinations of several accounts within the hour. The last sending IP of a shared pool is not paused. Mail from a paused IP moves to other IPs. Check dedicated IPs for listings.
- **Bounces with subType `SpamBlocked` or `ContentRejected`**: The content or a linked domain is filtered.Run a spam check on the sent email. Remove listed or shortened links, add a text part, reduce images.
- **Delivered, but lands in the spam folder**: Content, low engagement or a new domain without reputation.Spam-check the message. Look at `issues`: `new_domain` fades with steady clean volume. Check Google Postmaster Tools.
- **`complaint_rate` above 0.1%**: Recipients do not expect the mail: old list, unclear sender, no visible unsubscribe link.Pause the campaign, send to recent openers and clickers only, add a visible unsubscribe link and name the brand in From.
- **`bounce_rate` above 2%**: An old or purchased list, or typos at signup.Stop importing the list. Use double opt-in. Hard bounces are suppressed automatically; do not remove them from suppressions.
- **Recipients get `email.suppressed` instead of mail**: The address bounced hard or complained earlier (every stream), or unsubscribed (broadcast mail only).Look it up. Remove it only when the person asked you to, for example after they re-subscribed.
- **Gmail shows “[Message clipped]”**: The HTML is over about 102 KB.Inline less CSS, remove comments and hidden blocks, link to long content.
- **Unsubscribe link opens “invalid unsubscribe link”**: The link was altered (for example cut off or rewritten by another tool), so its signature no longer checks.Use `{{{zap:unsubscribe_url}}}` unchanged. The link is signed for one recipient: a forwarded or copied link stays valid, but it always unsubscribes the original recipient, not the person who opens it.
- **A dedicated IP is `paused`**: During warm-up: more than 5% bounces or 30% deferrals over 6 hours. Any time: a provider block or a critical blocklist listing.Mail continues through other IPs. Fix the list or content first; contact support to resume the IP.

Bounce subtypes are listed in [Bounce classification](https://www.zapsmtp.xyz/docs/testing/#bounces). Every recipient’s exact SMTP reply is in [GET /emails/{id}](https://www.zapsmtp.xyz/docs/emails/get-email/).

## Pre-launch checklist

- Each From domain is added and `verified`; `verify` returns no `warnings`.
- SPF has one record per name with the ZapSMTP include, under 10 lookups.
- DMARC is published with the `rua` from the DMARC summary; a plan exists to move to `quarantine`.
- Marketing goes out on `stream: "broadcast"` from its own subdomain, one recipient per email.
- Every marketing email has a visible `{{{zap:unsubscribe_url}}}` link, or your own `List-Unsubscribe` and `List-Unsubscribe-Post` headers.
- API keys are restricted per stream and domain.
- Suppressions from your previous provider are imported.
- A webhook receives `email.bounced`, `email.complained` and `email.suppressed` and your app records them.
- The campaign draft scores `good` in the spam check with empty `issues`, has a text part and is under 102 KB.
- The domains are registered in Google Postmaster Tools.
- The first sends follow the warm-up ramp, starting with your most engaged recipients.
- Someone watches `complaint_rate`, `bounce_rate` and blocklists during the first weeks.

---

# Testing and simulator

Source: https://www.zapsmtp.xyz/docs/testing/

Exercise the failure paths before your users do. Simulator addresses never leave ZapSMTP, work with live and test keys, never touch your suppression list or reputation, and accept `+labels` such as `delivered+signup@simulator.zapsmtp.xyz`.

**Simulator addresses**

- **`delivered@` (email.delivered)**: 250 accepted by the mailbox
- **`bounced@` (email.bounced)**: 550 5.1.1 Permanent / MailboxDoesNotExist
- **`full@` (email.bounced)**: 552 5.2.2 Permanent / MailboxFull
- **`blocked@` (email.bounced)**: 554 5.7.1 Permanent / SpamBlocked
- **`delayed@` (email.delivery_delayed → email.delivered)**: 451 on the first attempt, delivered ~20 s later
- **`complained@` (email.delivered → email.complained)**: delivered, then an ARF abuse complaint
- **`suppressed@` (email.suppressed)**: treated as on your suppression list; not sent
- **`bounce+421+4.7.0+try-later@` (email.delivery_delayed)**: any reply you need: bounce+<code>[+<x.y.z>][+<words-with-dashes>]

## Try every scenario at once

`POST /v1/emails`

One email to several simulator addresses: each recipient produces its own events and webhooks within seconds.

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz",
    "bounced@simulator.zapsmtp.xyz",
    "complained@simulator.zapsmtp.xyz",
    "bounce+421+4.7.0+try-later@simulator.zapsmtp.xyz"
  ],
  "subject": "Scenario test",
  "text": "Testing every path."
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

## Test keys

Keys that start with `zap_test_` run validation, the email log, events and webhooks exactly as live keys do, accept any From domain and never deliver. They do not count against your monthly plan. Filter their traffic with `GET /emails?mode=test`; their events carry `test: true`.

## Bounce classification

Bounced, delayed, failed and suppressed events carry a `bounce` object: `type` is `Permanent`, `Transient` or `Undetermined`, `subType` says why, `message` is the receiver’s reply and `suppressed` tells whether the address was added to your suppressions. Only permanent mailbox- or domain-level failures suppress an address; a rejection caused by the sender side never does.

**subType**

- **`MailboxDoesNotExist`**: The address does not exist. Suppressed.
- **`DomainDoesNotExist`**: The domain has no mail server. Suppressed.
- **`MailboxInactive`**: The mailbox is disabled. Suppressed.
- **`MailboxFull`**: Over quota at the receiver.
- **`MessageTooLarge`**: Rejected for size.
- **`ContentRejected`**: Rejected for its content.
- **`AttachmentRejected`**: Rejected for an attachment.
- **`SpamBlocked`**: Filtered as spam. The recipient is not suppressed.
- **`IPBlocked`**: The provider refuses the sending IP (e.g. Yahoo TSS, Microsoft S3150). The IP is paused and your mail moves to other IPs; the recipient is not suppressed.
- **`PolicyRejected`**: Sender policy (SPF, DMARC, PTR). The recipient is not suppressed.
- **`RelayDenied`**: The receiver refused to relay.
- **`DNSFailure`**: DNS lookup failed.
- **`ConnectionFailed`**: Could not connect.
- **`Expired`**: Retries ran out.
- **`Suppressed`**: Skipped: the address is on your suppression list.
- **`AutoReply`**: An out-of-office or similar reply.
- **`General`**: Anything else.

## Spam checks

Score a draft with [POST /emails/spam-check](https://www.zapsmtp.xyz/docs/emails/spam-check-draft/) or a sent email with [POST /emails/{id}/spam-check](https://www.zapsmtp.xyz/docs/emails/spam-check-email/). The message is DKIM-signed with your real key and checked as if it arrived from your real sending IP, with two spam engines and live blocklists. The response lists the rules that fired and infrastructure issues, such as a listed IP, separately from content problems.

---

# Errors, limits and paging

Source: https://www.zapsmtp.xyz/docs/conventions/

The rules every endpoint shares. Base URL `https://zapsmtp.xyz/v1`, JSON in and out, timestamps in RFC 3339 (UTC), ids are time-ordered UUIDv7 strings.

## API keys

Send the key as `Authorization: Bearer <key>`. The full key is shown once, when you create it; we store only a hash.

**Key types**

- **`zap_…` (live)**: Delivers email. The From domain must be verified in your account.
- **`zap_test_…` (test)**: Full validation, email log, events and webhooks, but nothing is delivered and the monthly quota is not charged (the per-second limit still applies). Any From domain is accepted. Events carry `test: true`; list them with `GET /emails?mode=test`.
- **`full_access` (permission)**: Every endpoint.
- **`sending_access` (permission)**: Only sending: `POST /emails`, `/emails/batch`, `/emails/spam-check`, rescheduling and canceling. Can also be limited to one domain and one stream.

## Errors

Errors use HTTP status codes and always carry both a flat shape (`statusCode`, `name`, `message`) and a nested one. `name` equals `error.code`. Every response has an `X-Request-Id` header; include it when you contact support.

```json
{
  "statusCode": 422,
  "name": "missing_required_field",
  "message": "subject is required",
  "error": {
    "code": "missing_required_field",
    "message": "subject is required",
    "type": "invalid_request_error"
  }
}
```

**Codes**

- **`validation_error` (HTTP 400)**: Malformed JSON or a field the endpoint does not know (unknown fields are rejected, so typos never pass silently).
- **`invalid_idempotency_key` (HTTP 400)**: Idempotency-Key longer than 256 bytes.
- **`missing_api_key` (HTTP 401)**: No Authorization header.
- **`invalid_api_key` (HTTP 401)**: Unknown, revoked or expired key.
- **`restricted_api_key` (HTTP 403)**: The key has sending access only, or is limited to another domain or stream.
- **`domain_not_verified` (HTTP 403)**: Live key sending from a domain that is not verified.
- **`account_suspended` (HTTP 403)**: The account is suspended.
- **`plan_limit_reached` (HTTP 403)**: Your plan’s limit for domains or SMTP credentials is reached.
- **`test_key_restricted` (HTTP 403)**: A test key (`zap_test_…`) tried to change the account: test keys may send test email, render templates and read. Use a live key.
- **`key_restricted` (HTTP 403)**: A restricted key creating or changing keys tried to give them more than it has: an expiry later than its own, or another stream.
- **`email_unverified` (HTTP 403)**: Confirm your account email address first; we sent a link to it.
- **`session_required` (HTTP 403)**: Team and account management needs a dashboard session, not an API key.
- **`not_found` (HTTP 404)**: No such resource in your account (or outside your plan’s log retention).
- **`method_not_allowed` (HTTP 405)**: The path exists, but not with this HTTP method.
- **`idempotency_key_reused` (HTTP 409)**: The Idempotency-Key was used with a different body.
- **`idempotency_request_in_progress` (HTTP 409)**: The first request with this key is still running.
- **`not_cancellable` (HTTP 409)**: The scheduled email was already dispatched or canceled.
- **`conflict` (HTTP 409)**: The resource already exists.
- **`not_ready` (HTTP 409)**: The received email is still being stored; retry the erasure in a few seconds.
- **`link_expired` (HTTP 410)**: The download link has expired; request a new one from the API.
- **`payload_too_large` (HTTP 413)**: Body over 40 MB.
- **`misdirected_cell` (HTTP 421)**: Your account is served by another cell of ZapSMTP. The message names the cell and its URL, and the Zap-Cell header names the cell. Send to that URL; retrying here fails the same way.
- **`missing_required_field` (HTTP 422)**: A required field is missing.
- **`invalid_parameter` (HTTP 422)**: A field has an invalid value; the message says which.
- **`invalid_attachment` (HTTP 422)**: An attachment could not be decoded or fetched.
- **`template_render_error` (HTTP 422)**: A template variable is missing, the template is invalid, or (on save) a tag is not a variable name.
- **`template_variables_missing` (HTTP 422)**: A send with a template lacks required variables that have no default; the message lists them (see [Variables](https://www.zapsmtp.xyz/docs/templating/#variable-errors)).
- **`template_variables_invalid` (HTTP 422)**: A send with a template gives variables of the wrong type for the template’s variable schema; the message lists them.
- **`reserved_domain` (HTTP 422)**: The domain is reserved and cannot be added.
- **`invalid_logo` (HTTP 422)**: The brand logo SVG could not be used (PUT /domains/{id}/brand); the message says why.
- **`invalid_certificate` (HTTP 422)**: The brand certificate (VMC) PEM is not valid (PUT /domains/{id}/brand).
- **`automated_message` (HTTP 422)**: The email you reply to is automated (an auto-reply, a bounce, a list); answering it can start a mail loop. Pass `allow_automated: true` to reply anyway.
- **`limit_exceeded` (HTTP 422)**: A per-account limit is reached, such as 20 forward destinations.
- **`quota_exceeded` (HTTP 422)**: The image library is full (2,000 images or 1 GB): delete unused images first.
- **`invalid_image` (HTTP 422)**: An uploaded image could not be used; the message says why.
- **`rejected` (HTTP 422)**: The MTA refused the message; the message gives its reason. Not retryable as is.
- **`rate_limit_exceeded` (HTTP 429)**: Over the per-second limit (Retry-After: 1), or too many failed authentications.
- **`monthly_quota_exceeded` (HTTP 429)**: Free plan or spending cap reached for this month.
- **`daily_quota_exceeded` (HTTP 429)**: Daily limit reached (Free plan: 100 emails a day, resets at 00:00 UTC).
- **`overloaded` (HTTP 429)**: The server is at capacity (Retry-After: 1), or a send could not be taken because the event pipeline is backed up (Retry-After: 5). Nothing was sent; retry after Retry-After with the same Idempotency-Key.
- **`thread_reply_limit` (HTTP 429)**: Too many replies in one conversation in the last hour (a mail loop?). Retry-After: 3600.
- **`internal_error` (HTTP 500)**: Something failed on our side. Safe to retry with the same Idempotency-Key.
- **`service_unavailable` (HTTP 503)**: Temporarily unable to accept, for example while a backing service fails over after a node loss (Retry-After: 2), or while the MTA is unavailable, the suppression list is loading or too many large bodies are in flight (Retry-After: 5). Safe to retry with the same Idempotency-Key.
- **`scanner_unavailable` (HTTP 503)**: The spam checkers are temporarily unavailable (spam checks); try again.
- **`storage_unavailable` (HTTP 503)**: Object storage is not configured on this deployment, so images cannot be uploaded.
- **`inbound_not_configured` (HTTP 503)**: Inbound email is not enabled on this deployment.

## Rate limits and quotas

Sending responses report your budget in headers. Back off on `429` and honor `Retry-After`.

**Response headers on sends**

- **`RateLimit-Limit`**: Recipients per second for your account.
- **`RateLimit-Remaining`**: Recipients left in the current second.
- **`RateLimit-Reset`**: Seconds until the budget refills (always `1`).
- **`Zap-Quota-Monthly-Limit`**: Emails included this month, or `unlimited` on paid plans without a spending cap (extra email is billed as overage).
- **`Zap-Quota-Monthly-Remaining`**: Emails left this month; omitted when the limit is `unlimited`.

**Limits**

- **Recipients per email**: 50 across to, cc and bcc
- **Emails per batch**: 100
- **Request size**: 40 MB, attachments included
- **Free plan**: 3,000 emails a month, at most 100 a day
- **Spam checks**: 30 a minute per account

## Idempotency

Send `Idempotency-Key: <1–256 bytes>` with `POST /emails` and `POST /emails/batch` to retry without sending twice. Keys belong to the API key and are kept for 24 hours together with a fingerprint of the request.

**What happens on a retry**

- **Same key, same body, finished**: The original response is returned with `Idempotent-Replayed: true`.
- **Same key, different body**: `409 idempotency_key_reused`
- **Same key, first request still running**: `409 idempotency_request_in_progress`
- **First attempt got 429 or 5xx**: The key is released; retry with the same key.

## Pagination

Lists return `{"object": "list", "has_more": false, "data": [...]}`, newest first.

- `GET /emails` and `GET /emails/receiving`: `limit` 1–100 (default 20); pass the last id (or an RFC 3339 time) as `before` for older items, `after` for newer ones.
- `GET /suppressions`: `limit` 1–1000 (default 100); pass `next_cursor` back as `after` while `has_more` is true.
- Other lists return every item in one response.

## Email statuses

An email’s `status` is the latest event: `queued`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `failed`, `opened`, `clicked`, `replied` (reply tracking) or `suppressed`. Scheduled emails show `scheduled` until they are sent, or `canceled`.

## Streams

`transactional` (default) and `broadcast` leave from separate IP pools, so a newsletter never slows down a password reset. Broadcast emails to one recipient get RFC 8058 one-click unsubscribe headers automatically; an unsubscribe adds the address to your suppressions and stops broadcast mail to it, while transactional mail still goes out. Bounces, complaints and manual suppressions stop both streams.

---

# Teams and client accounts

Source: https://www.zapsmtp.xyz/docs/teams/

One login, many accounts. An agency or a freelance automation specialist keeps each client in its own account, with its own domains, keys, logs, reputation and billing, and switches between them in the dashboard. Clients and teammates get their own logins with a role.

## Client accounts

Open the account menu at the bottom of the dashboard sidebar and choose *Create account*. You become its owner. Each account is fully separate: its own sending domains, API keys, SMTP credentials, webhooks, suppressions, logs and plan. An API key always belongs to exactly one account, so a client’s integration can never send from another client’s domains.

You can own up to three accounts on the Free plan; accounts on a paid plan do not count towards that limit. The dashboard remembers the account you used last and opens it at your next sign-in.

## Inviting people

Owners and admins invite people from *Team* in the dashboard: enter their email and pick a role. ZapSMTP creates an invite link to send them. The link works once, only for that email address, and expires after 7 days. Pending invites can be revoked at any time.

A person who is new to ZapSMTP sets a password on the invite page and lands straight in your account. Someone who already uses ZapSMTP signs in with that email and accepts; the account is added to their account menu next to their own.

![The Team page: an owner, an admin, a developer and an agency viewer, with a pending invite](https://www.zapsmtp.xyz/docs/img/team-light.webp)

## Roles

**What each role can do**

- **Owner**: Everything: sending, domains, keys, webhooks, the team and billing. Only an owner makes or removes owners, and every account keeps at least one.
- **Admin**: Everything except billing, including inviting people and changing their roles (not owners).
- **Developer**: Domains, API keys, SMTP credentials, webhooks, templates, inbound and sending. No billing, no team management.
- **Viewer**: Read-only: emails, events, logs, statistics and settings.

Roles apply to dashboard sessions. API keys act for the account, not a person; billing changes always need an owner’s dashboard session, so a key a developer created can never change the plan.

## Removing access

Removing a member, or a member leaving, takes effect on their next request; their open dashboard stops working at once. Keys they created keep working, since keys belong to the account: revoke them in *API keys* if needed. Their other accounts are not affected.

---

# Emails API

Source: https://www.zapsmtp.xyz/docs/emails/

Send one email or up to 100 in a batch, schedule them, and follow every recipient from acceptance to the remote server’s reply. Sending to `…@simulator.zapsmtp.xyz` with a test key runs the whole pipeline without delivering anything.

- [Send an email](https://www.zapsmtp.xyz/docs/emails/send-email/): POST
- [Send a batch](https://www.zapsmtp.xyz/docs/emails/send-batch/): POST
- [List emails](https://www.zapsmtp.xyz/docs/emails/list-emails/): GET
- [Retrieve an email](https://www.zapsmtp.xyz/docs/emails/get-email/): GET
- [Retrieve email content](https://www.zapsmtp.xyz/docs/emails/get-email-content/): GET
- [Reschedule an email](https://www.zapsmtp.xyz/docs/emails/reschedule-email/): PATCH
- [Cancel a scheduled email](https://www.zapsmtp.xyz/docs/emails/cancel-email/): POST
- [Spam-check a draft](https://www.zapsmtp.xyz/docs/emails/spam-check-draft/): POST
- [Spam-check a sent email](https://www.zapsmtp.xyz/docs/emails/spam-check-email/): POST
- [List attachments](https://www.zapsmtp.xyz/docs/emails/list-sent-attachments/): GET
- [Retrieve an attachment](https://www.zapsmtp.xyz/docs/emails/get-sent-attachment/): GET
- [Share an email](https://www.zapsmtp.xyz/docs/emails/share-email/): POST

---

# Domains API

Source: https://www.zapsmtp.xyz/docs/domains/

Add the domain you send from, publish the DNS records it returns (DKIM, SPF, DMARC) and verify it. Live keys can only send from verified domains.

- [List domains](https://www.zapsmtp.xyz/docs/domains/list-domains/): GET
- [Add a domain](https://www.zapsmtp.xyz/docs/domains/create-domain/): POST
- [Retrieve a domain](https://www.zapsmtp.xyz/docs/domains/get-domain/): GET
- [Verify a domain](https://www.zapsmtp.xyz/docs/domains/verify-domain/): POST
- [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/): PATCH
- [Domain reputation](https://www.zapsmtp.xyz/docs/domains/domain-reputation/): GET
- [DMARC reports](https://www.zapsmtp.xyz/docs/domains/domain-dmarc/): GET
- [Check reputation now](https://www.zapsmtp.xyz/docs/domains/check-domain-reputation/): POST
- [Retrieve brand settings](https://www.zapsmtp.xyz/docs/domains/get-brand/): GET
- [Update brand settings](https://www.zapsmtp.xyz/docs/domains/update-brand/): PUT
- [Delete a domain](https://www.zapsmtp.xyz/docs/domains/delete-domain/): DELETE

---

# Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/

Register an HTTPS endpoint and choose events. Every request is signed; see [Webhook events](https://www.zapsmtp.xyz/docs/webhook-events/) for payloads and signature verification. `filter.actions` narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/).

- [List webhooks](https://www.zapsmtp.xyz/docs/webhooks/list-webhooks/): GET
- [Create a webhook](https://www.zapsmtp.xyz/docs/webhooks/create-webhook/): POST
- [Retrieve a webhook](https://www.zapsmtp.xyz/docs/webhooks/get-webhook/): GET
- [Update a webhook](https://www.zapsmtp.xyz/docs/webhooks/update-webhook/): PATCH
- [Send a test event](https://www.zapsmtp.xyz/docs/webhooks/test-webhook/): POST
- [List delivery attempts](https://www.zapsmtp.xyz/docs/webhooks/webhook-deliveries/): GET
- [List events](https://www.zapsmtp.xyz/docs/webhooks/list-webhook-events/): GET
- [Retrieve an event](https://www.zapsmtp.xyz/docs/webhooks/get-webhook-event/): GET
- [Replay an event](https://www.zapsmtp.xyz/docs/webhooks/replay-event/): POST
- [Rotate the signing secret](https://www.zapsmtp.xyz/docs/webhooks/rotate-secret/): POST
- [Delete a webhook](https://www.zapsmtp.xyz/docs/webhooks/delete-webhook/): DELETE

---

# Click actions API

Source: https://www.zapsmtp.xyz/docs/actions/

Mark a link with `data-zap-action="confirm_order"` and its clicks arrive as `email.clicked` with `click.action`; a webhook can take only the actions you list in `filter.actions`. Declaring an action here is optional: it gives it a description. The catalogue also lists the actions links used without one. See the [Click actions guide](https://www.zapsmtp.xyz/docs/click-actions/).

- [List actions](https://www.zapsmtp.xyz/docs/actions/list-actions/): GET
- [Declare an action](https://www.zapsmtp.xyz/docs/actions/create-action/): POST
- [Retrieve an action](https://www.zapsmtp.xyz/docs/actions/get-action/): GET
- [Describe an action](https://www.zapsmtp.xyz/docs/actions/update-action/): PATCH
- [Delete an action](https://www.zapsmtp.xyz/docs/actions/delete-action/): DELETE

---

# Templates API

Source: https://www.zapsmtp.xyz/docs/templates/

Edit a draft, then publish it: sends always use the published version, so changes go live only when you say so. Templates use logic-less Mustache: `{{name}}` is escaped, `{{{html}}}` is raw, sections repeat over lists. Send with `template: {id, variables}` on [Send an email](https://www.zapsmtp.xyz/docs/emails/send-email/); `variable_schema` declares each variable’s type, whether a send must give it and its default (see [Variables](https://www.zapsmtp.xyz/docs/templating/#variables)). Every save is kept in the version history (the newest 50), ready to restore.

- [List templates](https://www.zapsmtp.xyz/docs/templates/list-templates/): GET
- [Create a template](https://www.zapsmtp.xyz/docs/templates/create-template/): POST
- [Retrieve a template](https://www.zapsmtp.xyz/docs/templates/get-template/): GET
- [Update a template](https://www.zapsmtp.xyz/docs/templates/update-template/): PATCH
- [Publish a template](https://www.zapsmtp.xyz/docs/templates/publish-template/): POST
- [Duplicate a template](https://www.zapsmtp.xyz/docs/templates/duplicate-template/): POST
- [Render a template](https://www.zapsmtp.xyz/docs/templates/render-template/): POST
- [Render unsaved source](https://www.zapsmtp.xyz/docs/templates/render-source/): POST
- [List versions](https://www.zapsmtp.xyz/docs/templates/list-template-versions/): GET
- [Retrieve a version](https://www.zapsmtp.xyz/docs/templates/get-template-version/): GET
- [Restore a version](https://www.zapsmtp.xyz/docs/templates/restore-template-version/): POST
- [Delete a template](https://www.zapsmtp.xyz/docs/templates/delete-template/): DELETE

---

# Variables API

Source: https://www.zapsmtp.xyz/docs/variables/

One list of every variable your templates can use: ZapSMTP’s own (`{{{zap:unsubscribe_url}}}`), the account’s global ones (`{{global.company_name}}`, set here and never by a send) and each template’s own, with where each is used. See [Variables](https://www.zapsmtp.xyz/docs/templating/#variables) in the templates guide.

- [List variables](https://www.zapsmtp.xyz/docs/variables/list-variables/): GET
- [Set a global variable](https://www.zapsmtp.xyz/docs/variables/put-global-variable/): PUT
- [Delete a global variable](https://www.zapsmtp.xyz/docs/variables/delete-global-variable/): DELETE

---

# Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/

What the visual editor shares across templates: modules (saved rows any template can insert), images hosted on a public URL, and countdown timer images. All of it works through the API too.

- [List modules](https://www.zapsmtp.xyz/docs/template-library/list-template-modules/): GET
- [Save a module](https://www.zapsmtp.xyz/docs/template-library/create-template-module/): POST
- [Retrieve a module](https://www.zapsmtp.xyz/docs/template-library/get-template-module/): GET
- [Update a module](https://www.zapsmtp.xyz/docs/template-library/update-template-module/): PATCH
- [Delete a module](https://www.zapsmtp.xyz/docs/template-library/delete-template-module/): DELETE
- [List images](https://www.zapsmtp.xyz/docs/template-library/list-template-assets/): GET
- [Upload an image](https://www.zapsmtp.xyz/docs/template-library/upload-template-asset/): POST
- [Delete an image](https://www.zapsmtp.xyz/docs/template-library/delete-template-asset/): DELETE
- [Create a countdown timer](https://www.zapsmtp.xyz/docs/template-library/create-template-timer/): POST

---

# Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/

Messages sent to your inbound addresses land here. The `email.received` webhook carries metadata only; fetch bodies and attachments with these endpoints.

- [List received emails](https://www.zapsmtp.xyz/docs/receiving/list-received/): GET
- [Retrieve a received email](https://www.zapsmtp.xyz/docs/receiving/get-received/): GET
- [List attachments](https://www.zapsmtp.xyz/docs/receiving/list-received-attachments/): GET
- [Retrieve an attachment](https://www.zapsmtp.xyz/docs/receiving/get-received-attachment/): GET
- [Redeliver to webhooks](https://www.zapsmtp.xyz/docs/receiving/redeliver-received/): POST
- [Report spam / not spam](https://www.zapsmtp.xyz/docs/receiving/report-received-spam/): POST
- [Reply to a received email](https://www.zapsmtp.xyz/docs/receiving/reply-received/): POST
- [List conversations](https://www.zapsmtp.xyz/docs/receiving/list-threads/): GET
- [Retrieve a conversation](https://www.zapsmtp.xyz/docs/receiving/get-thread/): GET
- [Mark read, set metadata](https://www.zapsmtp.xyz/docs/receiving/update-thread/): PATCH
- [Delete a received email](https://www.zapsmtp.xyz/docs/receiving/delete-received/): DELETE

---

# Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/

Get an instant managed address or receive on your own domain, then route messages by recipient, sender or header to a webhook, storage or rejection.

- [List inbound domains](https://www.zapsmtp.xyz/docs/inbound/list-inbound-domains/): GET
- [Add an inbound domain](https://www.zapsmtp.xyz/docs/inbound/create-inbound-domain/): POST
- [Retrieve an inbound domain](https://www.zapsmtp.xyz/docs/inbound/get-inbound-domain/): GET
- [Update an inbound domain](https://www.zapsmtp.xyz/docs/inbound/update-inbound-domain/): PATCH
- [Verify MX records](https://www.zapsmtp.xyz/docs/inbound/verify-inbound-domain/): POST
- [Delete an inbound domain](https://www.zapsmtp.xyz/docs/inbound/delete-inbound-domain/): DELETE
- [List routes](https://www.zapsmtp.xyz/docs/inbound/list-routes/): GET
- [Create a route](https://www.zapsmtp.xyz/docs/inbound/create-route/): POST
- [Retrieve a route](https://www.zapsmtp.xyz/docs/inbound/get-route/): GET
- [Update a route](https://www.zapsmtp.xyz/docs/inbound/update-route/): PATCH
- [Delete a route](https://www.zapsmtp.xyz/docs/inbound/delete-route/): DELETE
- [List forward destinations](https://www.zapsmtp.xyz/docs/inbound/list-forward-destinations/): GET
- [Add a forward destination](https://www.zapsmtp.xyz/docs/inbound/create-forward-destination/): POST
- [Resend the confirmation](https://www.zapsmtp.xyz/docs/inbound/resend-forward-confirmation/): POST
- [Remove a forward destination](https://www.zapsmtp.xyz/docs/inbound/delete-forward-destination/): DELETE
- [Inbound stats](https://www.zapsmtp.xyz/docs/inbound/inbound-stats/): GET

---

# Suppressions API

Source: https://www.zapsmtp.xyz/docs/suppressions/

Permanent mailbox or domain failures, complaints and one-click unsubscribes add an address here automatically. Sends to a suppressed address are skipped and reported as `email.suppressed`. An unsubscribe stops only broadcast email; transactional email to that address still goes out.

- [List suppressions](https://www.zapsmtp.xyz/docs/suppressions/list-suppressions/): GET
- [Retrieve a suppression](https://www.zapsmtp.xyz/docs/suppressions/get-suppression/): GET
- [Add a suppression](https://www.zapsmtp.xyz/docs/suppressions/add-suppression/): POST
- [Add suppressions in bulk](https://www.zapsmtp.xyz/docs/suppressions/add-suppressions/): POST
- [Remove suppressions in bulk](https://www.zapsmtp.xyz/docs/suppressions/remove-suppressions/): POST
- [Remove a suppression](https://www.zapsmtp.xyz/docs/suppressions/delete-suppression/): DELETE

---

# Statistics API

Source: https://www.zapsmtp.xyz/docs/stats/

Counts for the window you ask for, limited to your plan’s log retention.

- [Totals](https://www.zapsmtp.xyz/docs/stats/stats/): GET
- [Time series](https://www.zapsmtp.xyz/docs/stats/stats-timeseries/): GET
- [Breakdown](https://www.zapsmtp.xyz/docs/stats/stats-breakdown/): GET
- [Metrics by domain, stream, tag or provider](https://www.zapsmtp.xyz/docs/stats/metrics/): GET

---

# API keys & SMTP credentials API

Source: https://www.zapsmtp.xyz/docs/keys/

Use separate keys per application and environment. Test keys (`zap_test_…`) run the full pipeline without delivering. SMTP credentials have their own username and password and never authorize the HTTP API.

- [List API keys](https://www.zapsmtp.xyz/docs/keys/list-api-keys/): GET
- [Create an API key](https://www.zapsmtp.xyz/docs/keys/create-api-key/): POST
- [Update an API key](https://www.zapsmtp.xyz/docs/keys/update-api-key/): PATCH
- [Revoke an API key](https://www.zapsmtp.xyz/docs/keys/revoke-api-key/): DELETE
- [List SMTP credentials](https://www.zapsmtp.xyz/docs/keys/list-smtp-credentials/): GET
- [Create SMTP credentials](https://www.zapsmtp.xyz/docs/keys/create-smtp-credential/): POST
- [Revoke SMTP credentials](https://www.zapsmtp.xyz/docs/keys/revoke-smtp-credential/): DELETE

---

# Logs & usage API

Source: https://www.zapsmtp.xyz/docs/logs/

Find out exactly what your code sent and what we answered. Every response’s `X-Request-Id` is the id of its log entry.

- [List logs](https://www.zapsmtp.xyz/docs/logs/list-logs/): GET
- [Retrieve a log](https://www.zapsmtp.xyz/docs/logs/get-log/): GET
- [Retrieve usage](https://www.zapsmtp.xyz/docs/logs/usage/): GET

---

# Simulator & dedicated IPs API

Source: https://www.zapsmtp.xyz/docs/platform/

List the simulator scenarios and your dedicated IPs with their warm-up and blocklist status.

- [List simulator addresses](https://www.zapsmtp.xyz/docs/platform/simulator/): GET
- [List dedicated IPs](https://www.zapsmtp.xyz/docs/platform/dedicated-ips/): GET

---

# Declare an action — Click actions API

Source: https://www.zapsmtp.xyz/docs/actions/create-action/

`POST /v1/actions`

Declare an action and describe it. Optional: links work with any valid name, declared or not.

Requires a full-access live key; test keys get 403 test_key_restricted.

The response does not count activity: the stats are zero and `templates` is 0 here. Read them with `GET /actions/{name}`.

### Body parameters

- `name` (string, required): The name links carry in `data-zap-action`: lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters. Limits: other names → 422 invalid_parameter
- `description` (string): What the button does, for your team. Limits: at most 500 bytes → 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): an action with this name exists
- `invalid_parameter` (HTTP 422): bad name or description

```bash
curl -X POST 'https://zapsmtp.xyz/v1/actions' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "confirm_order",
  "description": "Customer confirms the order from the receipt"
}'
```

**Response `201 Created`**

```json
{
  "object": "action",
  "name": "confirm_order",
  "description": "Customer confirms the order from the receipt",
  "declared": true,
  "created_at": "2026-10-24T09:12:00Z",
  "updated_at": "2026-10-24T09:12:00Z",
  "clicks_7d": 0,
  "clicks_30d": 0,
  "unique_clickers_30d": 0,
  "last_click_at": null,
  "templates": 0,
  "webhooks": []
}
```

---

# Delete an action — Click actions API

Source: https://www.zapsmtp.xyz/docs/actions/delete-action/

`DELETE /v1/actions/{name}`

Delete an action’s declaration. Links that name it keep working: clicks are still tracked and still reach webhooks filtered on it.

Requires a full-access live key; test keys get 403 test_key_restricted.

While links or webhooks still use it, the action stays in the catalogue with `declared: false`.

### Path parameters

- `name` (string, required): Action name, as written in `data-zap-action`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): action not found (not declared)

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/actions/confirm_order' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "action",
  "name": "confirm_order",
  "deleted": true
}
```

---

# Retrieve an action — Click actions API

Source: https://www.zapsmtp.xyz/docs/actions/get-action/

`GET /v1/actions/{name}`

Retrieve one action from the catalogue, with its activity and where it is used.

Requires a full-access key.

### Path parameters

- `name` (string, required): Action name, as written in `data-zap-action`.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): action not found: not declared, not clicked in 30 days and used by no template or webhook

```bash
curl 'https://zapsmtp.xyz/v1/actions/confirm_order' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "action",
  "name": "confirm_order",
  "description": "Customer confirms the order from the receipt",
  "declared": true,
  "created_at": "2026-10-24T09:12:00Z",
  "updated_at": "2026-10-24T09:12:00Z",
  "clicks_7d": 42,
  "clicks_30d": 180,
  "unique_clickers_30d": 171,
  "last_click_at": "2026-10-27T08:41:05Z",
  "templates": 1,
  "webhooks": [
    "019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10"
  ]
}
```

---

# List actions — Click actions API

Source: https://www.zapsmtp.xyz/docs/actions/list-actions/

`GET /v1/actions`

List every action of the account: the ones you declared, the ones links named in the last 30 days, and the ones templates and webhook filters use. Sorted by name.

Requires a full-access key.

`declared` is `false` for an action that links use but nobody described; `created_at` and `updated_at` are then `null`.

`clicks_7d`, `clicks_30d` and `unique_clickers_30d` (distinct email and recipient pairs) count the last 7 and 30 days; `last_click_at` is `null` without a click in 30 days. `templates` counts the templates whose draft or published HTML names the action; `webhooks` lists the ids of the endpoints filtered on it.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/actions' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "action",
      "name": "confirm_order",
      "description": "Customer confirms the order from the receipt",
      "declared": true,
      "created_at": "2026-10-24T09:12:00Z",
      "updated_at": "2026-10-24T09:12:00Z",
      "clicks_7d": 42,
      "clicks_30d": 180,
      "unique_clickers_30d": 171,
      "last_click_at": "2026-10-27T08:41:05Z",
      "templates": 1,
      "webhooks": [
        "019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10"
      ]
    },
    {
      "object": "action",
      "name": "track_parcel",
      "description": "",
      "declared": false,
      "created_at": null,
      "updated_at": null,
      "clicks_7d": 12,
      "clicks_30d": 64,
      "unique_clickers_30d": 60,
      "last_click_at": "2026-10-26T19:02:44Z",
      "templates": 2,
      "webhooks": []
    }
  ]
}
```

---

# Describe an action — Click actions API

Source: https://www.zapsmtp.xyz/docs/actions/update-action/

`PATCH /v1/actions/{name}`

Change an action’s description. An action that links use but nobody declared is declared by this call.

Requires a full-access live key; test keys get 403 test_key_restricted.

Like create, the response carries zero stats; read them with `GET /actions/{name}`.

### Path parameters

- `name` (string, required): Action name, as written in `data-zap-action`.

### Body parameters

- `description` (string): The new description; leaving it out sets it to empty. Limits: at most 500 bytes → 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): action not found (the name is not a valid action name)
- `invalid_parameter` (HTTP 422): description: at most 500 bytes

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/actions/confirm_order' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Customer confirms an order from the receipt email"
}'
```

**Response `200 OK`**

```json
{
  "object": "action",
  "name": "confirm_order",
  "description": "Customer confirms an order from the receipt email",
  "declared": true,
  "created_at": "2026-10-24T09:12:00Z",
  "updated_at": "2026-10-27T10:05:00Z",
  "clicks_7d": 0,
  "clicks_30d": 0,
  "unique_clickers_30d": 0,
  "last_click_at": null,
  "templates": 0,
  "webhooks": []
}
```

---

# Check reputation now — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/check-domain-reputation/

`POST /v1/domains/{id}/reputation/check`

Run a blocklist check of the domain now and return its reputation.

Requires a full-access live key; test keys get 403 test_key_restricted.

At most once per minute per domain name. No Retry-After header is set.

### Path parameters

- `id` (string (UUID), required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `rate_limit_exceeded` (HTTP 429): this domain was checked less than a minute ago

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/reputation/check' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `200`.

---

# Add a domain — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/create-domain/

`POST /v1/domains`

Add a sending domain; returns the DNS records to publish.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string, required): Domain name (lowercased, trailing dot removed). Limits: valid hostname <=253 chars, else 422 invalid_parameter "invalid domain name"

### Errors

- `plan_limit_reached` (HTTP 403): the <Plan> plan includes <n> domains; upgrade your plan to add more
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): domain already added
- `invalid_parameter` (HTTP 422): invalid domain name

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "mail.acme.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "pending",
  "dkim_selector": "zap",
  "dkim_verified": false,
  "spf_verified": false,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": null,
  "verified_at": null,
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "pending"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "pending"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ]
}
```

---

# Delete a domain — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/delete-domain/

`DELETE /v1/domains/{id}`

Delete a sending domain.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `204` with an empty body.

---

# DMARC reports — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/domain-dmarc/

`GET /v1/domains/{id}/dmarc`

DMARC aggregate reports about the domain: the address to publish in your DMARC record and what mailbox providers reported.

Requires a full-access key.

Add `rua` to your DMARC record (keep your policy). Providers send one report a day; reports are kept 400 days. `ours` marks ZapSMTP sending IPs: another IP that fails DMARC is a service you have not set up (add its DKIM/SPF) or someone spoofing your domain.

### Path parameters

- `id` (string): Domain id.

### Query parameters

- `days` (integer): 1-180; out-of-range falls back to 30. Default `30`.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): Not a domain of this account.

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/dmarc' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "dmarc_summary",
  "domain": "acme.com",
  "days": 30,
  "since": "2026-09-26T00:00:00Z",
  "rua": "mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz",
  "record": {
    "type": "TXT",
    "name": "_dmarc.acme.com",
    "value": "v=DMARC1; p=none; rua=mailto:dmarc-k7x2m4q9p3a5b6c8@zapsmtp.xyz"
  },
  "reports": 42,
  "totals": {
    "messages": 18240,
    "passed": 18015,
    "dkim_passed": 18001,
    "spf_passed": 17890,
    "quarantined": 190,
    "rejected": 35
  },
  "sources": [
    {
      "ip": "192.0.2.10",
      "messages": 18000,
      "passed": 17990,
      "dkim_passed": 17985,
      "spf_passed": 17880,
      "quarantined": 10,
      "rejected": 0,
      "reporters": [
        "Yahoo",
        "google.com"
      ],
      "ours": true
    },
    {
      "ip": "203.0.113.5",
      "messages": 240,
      "passed": 25,
      "dkim_passed": 16,
      "spf_passed": 10,
      "quarantined": 180,
      "rejected": 35,
      "reporters": [
        "google.com"
      ],
      "ours": false
    }
  ],
  "reporters": [
    {
      "org": "google.com",
      "reports": 30,
      "messages": 15400
    },
    {
      "org": "Yahoo",
      "reports": 12,
      "messages": 2840
    }
  ],
  "series": [
    {
      "day": "2026-10-24T00:00:00Z",
      "messages": 640,
      "passed": 632,
      "dkim_passed": 632,
      "spf_passed": 628,
      "quarantined": 6,
      "rejected": 2
    }
  ]
}
```

---

# Domain reputation — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/domain-reputation/

`GET /v1/domains/{id}/reputation`

Blocklist (DNSBL) status of a sending domain.

Requires a full-access key.

Customer domains are checked automatically every 6 hours (operator-configurable). The exact JSON for codes/labels when empty (null vs []) depends on the stored arrays; not verified.

### Path parameters

- `id` (string (UUID), required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): domain not found

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/reputation' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "domain_reputation",
  "domain": "acme.com",
  "worst": "",
  "lists": [
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "spamhaus-dbl",
      "name": "Spamhaus DBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://check.spamhaus.org/"
    },
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "surbl",
      "name": "SURBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://www.surbl.org/surbl-analysis"
    },
    {
      "target": "acme.com",
      "kind": "domain",
      "list": "uribl",
      "name": "URIBL",
      "listed": false,
      "severity": null,
      "codes": [],
      "labels": [],
      "detail": "",
      "error": null,
      "listed_since": null,
      "checked_at": "2026-10-21T12:00:03Z",
      "removal_url": "https://admin.uribl.com/"
    }
  ],
  "events": [
    {
      "id": "019a1e00-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
      "target": "acme.com",
      "kind": "domain",
      "list": "uribl",
      "name": "URIBL",
      "event": "delisted",
      "severity": null,
      "codes": [],
      "detail": "",
      "at": "2026-10-19T06:00:02Z"
    }
  ]
}
```

---

# Retrieve brand settings — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/get-brand/

`GET /v1/domains/{id}/brand`

Brand-in-the-inbox status: sender name, BIMI logo/certificate, DMARC enforcement and per-provider readiness.

Requires a full-access key.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): domain not found

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/brand' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "from_name": "Acme",
  "logo_url": "https://zapsmtp.xyz/bimi/acme.com/logo.svg",
  "cert_url": "",
  "has_logo": true,
  "has_cert": false,
  "bimi_record": {
    "record": "BIMI",
    "type": "TXT",
    "name": "default._bimi.acme.com",
    "value": "v=BIMI1; l=https://zapsmtp.xyz/bimi/acme.com/logo.svg; a=;",
    "required": false,
    "status": "verified"
  },
  "dmarc_record": {
    "record": "DMARC",
    "type": "TXT",
    "name": "_dmarc.acme.com",
    "value": "v=DMARC1; p=quarantine; pct=100;",
    "required": false,
    "status": "verified"
  },
  "dmarc": {
    "record": "v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc@acme.com",
    "domain": "acme.com",
    "p": "quarantine",
    "sp": "",
    "pct": 100,
    "enforced": true
  },
  "published_bimi": "v=BIMI1; l=https://zapsmtp.xyz/bimi/acme.com/logo.svg; a=;",
  "checks": [
    {
      "id": "auth",
      "label": "SPF, DKIM and DMARC pass",
      "ok": true,
      "detail": "Domain verified; ZapSMTP signs every message with DKIM."
    },
    {
      "id": "dmarc",
      "label": "DMARC at enforcement",
      "ok": true,
      "detail": "Found on acme.com: v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc@acme.com"
    },
    {
      "id": "logo",
      "label": "Logo in SVG Tiny PS, hosted over HTTPS",
      "ok": true,
      "detail": "Square, ≤ 32 KB, solid background. Upload it below; we fix the profile automatically."
    },
    {
      "id": "bimi",
      "label": "BIMI record published",
      "ok": true,
      "detail": "default._bimi.acme.com points to the hosted logo. Mailbox providers may take up to 48 hours to show it."
    },
    {
      "id": "cert",
      "label": "Verified Mark Certificate (VMC) or Common Mark Certificate (CMC)",
      "ok": false,
      "detail": "Required by Gmail and Apple Mail (Gmail does not support a standalone SVG). VMC needs a registered trademark and adds the blue checkmark. Upload the PEM chain in order: certificate, intermediate, root."
    },
    {
      "id": "name",
      "label": "Sender name",
      "ok": true,
      "detail": "Used when an email's from has no display name, e.g. hello@ → \"Acme <hello@…>\"."
    }
  ],
  "providers": {
    "gmail": "needs_certificate",
    "apple": "needs_certificate",
    "yahoo": "ready"
  }
}
```

---

# Retrieve a domain — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/get-domain/

`GET /v1/domains/{id}`

Retrieve a sending domain.

Requires a full-access key.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): domain not found

```bash
curl 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `200`.

---

# List domains — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/list-domains/

`GET /v1/domains`

List sending domains (newest first) with their DNS records.

Requires a full-access key.

`status` is `pending` or `verified`. Only DKIM is required to verify a domain; SPF and DMARC are recommended and reported separately.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
      "name": "acme.com",
      "status": "verified",
      "dkim_selector": "zap",
      "dkim_verified": true,
      "spf_verified": true,
      "dmarc_verified": true,
      "open_tracking": false,
      "click_tracking": false,
      "from_name": "Acme",
      "tls": "opportunistic",
      "reply_tracking": false,
      "reply_domain": "",
      "reply_forward_to": "",
      "brand_updated_at": null,
      "last_checked_at": "2026-10-21T09:12:44Z",
      "verified_at": "2026-10-20T14:03:10Z",
      "created_at": "2026-10-20T13:58:02Z",
      "zone": "acme.com",
      "records": [
        {
          "record": "DKIM",
          "type": "TXT",
          "name": "zap._domainkey.acme.com",
          "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
          "required": true,
          "status": "verified"
        },
        {
          "record": "SPF",
          "type": "TXT",
          "name": "acme.com",
          "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
          "required": false,
          "status": "verified"
        },
        {
          "record": "DMARC",
          "type": "TXT",
          "name": "_dmarc.acme.com",
          "value": "v=DMARC1; p=none;",
          "required": false,
          "status": "verified"
        }
      ]
    }
  ]
}
```

---

# Update brand settings — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/update-brand/

`PUT /v1/domains/{id}/brand`

Set the default sender name and upload/remove the BIMI logo and certificate.

Requires a full-access live key; test keys get 403 test_key_restricted.

Hosted files are served publicly at /bimi/<domain>/logo.svg and /bimi/<domain>/cert.pem (outside /v1) for verified domains only.

### Path parameters

- `id` (string, required): Domain id

### Body parameters

- `from_name` (string): Display name used when an email's from has only an address. "" clears it. Limits: max 70 characters, no < > " or line breaks → 422 invalid_parameter
- `logo_svg` (string): SVG source; normalized to SVG Tiny PS (fixes reported in logo_fixed, warnings in logo_warnings). Limits: max 32 KB and valid SVG → otherwise 422 invalid_logo
- `cert_pem` (string): VMC/CMC PEM chain (certificate, intermediate, root). Limits: 422 invalid_certificate
- `remove_logo` (boolean): Default `False`.
- `remove_cert` (boolean): Default `False`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `invalid_certificate` (HTTP 422)
- `invalid_logo` (HTTP 422)
- `invalid_parameter` (HTTP 422)

```bash
curl -X PUT 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/brand' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from_name": "Acme"
}'
```

Response `200`.

---

# Update a domain — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/update-domain/

`PATCH /v1/domains/{id}`

Set the domain's tracking defaults (opens, clicks, replies) and its outbound TLS policy.

Requires a full-access live key; test keys get 403 test_key_restricted.

Fields left out keep their value. The response is the domain, as in `GET /domains/{id}`.

Reply tracking: each tracked email gets its own signed Reply-To, e.g. `r1-<email id>.<signature>@reply.acme.com`, so replies come back tied to the exact email. Each reply fires `email.replied` (classified as a person, out-of-office, unsubscribe request, bounce…) and arrives as a received email; only replies a person wrote are forwarded. The display name is kept (the Reply-To’s name, else the From name). One reply address takes at most 100 replies a day.

### Path parameters

- `id` (string, required): Domain id

### Body parameters

- `open_tracking` (boolean): Default open tracking for emails from this domain.
- `click_tracking` (boolean): Default click tracking for emails from this domain.
- `tls` (string): Outbound encryption: `opportunistic` (default: encrypt whenever offered), `required` (TLS or no delivery) or `verified` (TLS with a valid certificate). Limits: other values → 422 invalid_parameter "tls must be opportunistic, required or verified"
- `reply_tracking` (boolean): Default reply tracking for emails from this domain (override per email with `tracking.replies`). Limits: true without a reply_domain → 422 invalid_parameter "reply_tracking needs a reply_domain: add an inbound domain such as reply.<domain> first"
- `reply_domain` (string): Where tracked reply addresses live: one of your inbound domains, MX-verified, equal to this domain or a subdomain of it (e.g. `reply.acme.com`). `""` clears it. Limits: otherwise 422 invalid_parameter
- `reply_forward_to` (string): Where replies a person wrote are forwarded: a plain address on one of your verified domains, or a confirmed forward destination; never a receiving address. `""` (default) forwards to the email’s first Reply-To, else its From. Limits: otherwise 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `invalid_parameter` (HTTP 422): bad tls; reply_domain not one of your inbound domains, not this domain or a subdomain of it, or without a verified MX record; reply_forward_to not a plain address, a receiving address, or not on a verified domain / confirmed forward destination; reply_tracking without a reply_domain

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "open_tracking": true,
  "click_tracking": true,
  "reply_domain": "reply.acme.com",
  "reply_tracking": true
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": true,
  "open_tracking": true,
  "click_tracking": true,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": true,
  "reply_domain": "reply.acme.com",
  "reply_forward_to": "support@acme.com",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T14:05:00Z",
  "verified_at": "2026-10-21T14:05:00Z",
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "verified"
    }
  ]
}
```

---

# Verify a domain — Domains API

Source: https://www.zapsmtp.xyz/docs/domains/verify-domain/

`POST /v1/domains/{id}/verify`

Check DKIM/SPF/DMARC DNS now and update the domain's status.

Requires a full-access live key; test keys get 403 test_key_restricted.

`found` shows, per DNS name, what is published right now. For the root domain only SPF-type TXT values are listed; a DMARC policy inherited from the parent domain is marked “(inherited from _dmarc.<domain>)”.

### Path parameters

- `id` (string, required): Domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): domain not found
- `conflict` (HTTP 409): this domain is already verified by another account

```bash
curl -X POST 'https://zapsmtp.xyz/v1/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/verify' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
  "name": "acme.com",
  "status": "verified",
  "dkim_selector": "zap",
  "dkim_verified": true,
  "spf_verified": true,
  "dmarc_verified": false,
  "open_tracking": false,
  "click_tracking": false,
  "from_name": "",
  "tls": "opportunistic",
  "reply_tracking": false,
  "reply_domain": "",
  "reply_forward_to": "",
  "brand_updated_at": null,
  "last_checked_at": "2026-10-21T14:02:11Z",
  "verified_at": "2026-10-21T14:02:11Z",
  "created_at": "2026-10-21T13:58:02Z",
  "zone": "acme.com",
  "records": [
    {
      "record": "DKIM",
      "type": "TXT",
      "name": "zap._domainkey.acme.com",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "required": true,
      "status": "verified"
    },
    {
      "record": "SPF",
      "type": "TXT",
      "name": "acme.com",
      "value": "v=spf1 include:_spf.zapsmtp.xyz ~all",
      "required": false,
      "status": "verified"
    },
    {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.acme.com",
      "value": "v=DMARC1; p=none;",
      "required": false,
      "status": "pending"
    }
  ],
  "found": {
    "zap._domainkey.acme.com": [
      "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."
    ],
    "acme.com": [
      "v=spf1 include:_spf.zapsmtp.xyz ~all"
    ]
  }
}
```

---

# Cancel a scheduled email — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/cancel-email/

`POST /v1/emails/{id}/cancel`

Cancel a scheduled email before it is dispatched.

Requires a full-access or sending-access key.

### Path parameters

- `id` (string, required): Scheduled email id

### Errors

- `restricted_api_key` (HTTP 403): this API key cannot manage this email (another domain or stream, or live mail with a test key)
- `not_cancellable` (HTTP 409): unknown id, already dispatched or already canceled

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/cancel' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f40-2b3c-7d4e-8f5a-6b7c8d9e0f12",
  "status": "canceled"
}
```

---

# Retrieve email content — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/get-email-content/

`GET /v1/emails/{id}/content`

Retrieve the archived content of a sent email.

Requires a full-access key.

`source` is `api` or `smtp`; `tags` is the URL-encoded tag string. Content is kept for your plan’s log retention.

### Path parameters

- `id` (string, required): Email id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): content not available (past your plan's log retention)

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/content' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "source": "api",
  "from": "Acme <hello@acme.com>",
  "to": [
    "jane@example.org"
  ],
  "cc": [],
  "bcc": [],
  "subject": "Your receipt",
  "html": "<p>Thanks for your order!</p>",
  "text": "Thanks for your order!",
  "raw": "",
  "tags": "category=receipt",
  "size": 2481
}
```

---

# Retrieve an email — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/get-email/

`GET /v1/emails/{id}`

Retrieve one email with per-recipient status and its event timeline.

Requires a full-access key.

Only data inside the plan's log retention is visible. metadata may be null.

### Path parameters

- `id` (string, required): Email id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found (events can take a few seconds to appear)

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "from": "Acme <hello@acme.com>",
  "subject": "Your receipt",
  "created_at": "2026-10-21T15:04:10.902Z",
  "recipients": [
    {
      "email": "jane@example.org",
      "status": "delivered",
      "updated_at": "2026-10-21T15:04:12.381Z",
      "response": "250 2.0.0 OK 1761059052 x7si123"
    }
  ],
  "events": [
    {
      "type": "Reception",
      "status": "queued",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:10.902Z",
      "attempts": 0
    },
    {
      "type": "Delivery",
      "status": "delivered",
      "recipient": "jane@example.org",
      "time": "2026-10-21T15:04:12.381Z",
      "response_code": 250,
      "response": "250 2.0.0 OK 1761059052 x7si123",
      "attempts": 1,
      "mx": "gmail-smtp-in.l.google.com.",
      "peer_addr": "142.250.153.27",
      "tls": "TLSv1.3 TLS_AES_256_GCM_SHA384",
      "egress_source": "ip-1"
    }
  ],
  "stream": "transactional",
  "test": false,
  "metadata": {
    "order_id": "A-1042"
  }
}
```

---

# Retrieve an attachment — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/get-sent-attachment/

`GET /v1/emails/{id}/attachments/{aid}`

One attachment of a sent email with a fresh download link.

Requires a full-access key.

### Path parameters

- `id` (string, required): Email id.
- `aid` (string, required): Attachment id from the list.

### Errors

- `not_found` (HTTP 404): Unknown email or attachment.

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/attachments/att_1' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "attachment",
  "id": "att_1",
  "filename": "invoice.pdf",
  "content_type": "application/pdf",
  "content_disposition": "attachment",
  "content_id": "",
  "size": 20480,
  "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi…",
  "expires_at": "2026-10-22T16:04:10Z"
}
```

---

# List emails — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/list-emails/

`GET /v1/emails`

List sent emails, newest first.

Requires a full-access key.

Use the last item's id as before= for the next page. metadata may be null when the email has none. last_status and last_event carry the same value.

### Query parameters

- `limit` (integer): 1-100; out-of-range values fall back to 20. Default `20`.
- `before` (string): Cursor: an email id (UUIDv7) or RFC 3339 time; returns emails accepted before it. An email id gives an exact page boundary. Limits: 422 invalid_parameter "before must be an email id or RFC 3339 time"
- `after` (string): Email id or RFC 3339 time; only emails created after it (still newest first). Limits: 422 invalid_parameter "after must be an email id or RFC 3339 time"
- `status` (string): Filter by latest status. status=scheduled lists pending scheduled sends instead (different item shape, ordered by scheduled time ascending, has_more always false, other filters/cursors ignored). One of `queued`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `failed`, `opened`, `clicked`, `replied`, `suppressed`, `scheduled`.
- `q` (string): Case-insensitive substring of a recipient or subject, or an exact email id.
- `days` (integer): Look-back window in days, 1-90 (other values ignored). Always capped by the plan's log retention. Default `30`.
- `stream` (string): One of `transactional`, `broadcast`.
- `mode` (string): Filter live or test-mode (sandbox) traffic; other values ignored. One of `live`, `test`.
- `metadata[<key>]` (string): Exact match on a metadata value, e.g. metadata[order_id]=A-1042. Repeatable for several keys.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): bad before/after

```bash
curl 'https://zapsmtp.xyz/v1/emails?limit=10' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "email",
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "from": "Acme <hello@acme.com>",
      "subject": "Your receipt",
      "to": [
        "jane@example.org"
      ],
      "last_status": "delivered",
      "last_event": "delivered",
      "created_at": "2026-10-21T15:04:10.902Z",
      "stream": "transactional",
      "test": false,
      "metadata": {
        "order_id": "A-1042"
      }
    }
  ]
}
```

---

# List attachments — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/list-sent-attachments/

`GET /v1/emails/{id}/attachments`

Attachments of a sent email, each with a download link valid for one hour.

Requires a full-access key.

Emails sent without attachments return an empty list.

### Path parameters

- `id` (string, required): Email id.

### Errors

- `not_found` (HTTP 404): Unknown email, or past your plan’s log retention.

```bash
curl 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/attachments' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "attachment",
      "id": "att_1",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "content_disposition": "attachment",
      "content_id": "",
      "size": 20480,
      "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi…",
      "expires_at": "2026-10-22T16:04:10Z"
    }
  ]
}
```

---

# Reschedule an email — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/reschedule-email/

`PATCH /v1/emails/{id}`

Reschedule a scheduled email.

Requires a full-access or sending-access key.

Unknown ids return 409 not_cancellable, not 404.

### Path parameters

- `id` (string, required): Scheduled email id

### Body parameters

- `scheduled_at` (string, required): RFC 3339 or "in <n> <unit>" (see POST /emails). A time in the past dispatches as soon as possible. Limits: missing → 422 missing_required_field; unparsable or > 7 days ahead → 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403): this API key cannot manage this email (another domain or stream, or live mail with a test key)
- `not_cancellable` (HTTP 409): only scheduled emails can be updated
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422)

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "scheduled_at": "in 2 hours"
}'
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f40-2b3c-7d4e-8f5a-6b7c8d9e0f12",
  "status": "scheduled",
  "last_event": "scheduled",
  "scheduled_at": "2026-10-23T09:00:00Z",
  "from": "Acme <hello@acme.com>",
  "to": [
    "jane@example.org"
  ],
  "subject": "Your weekly digest",
  "created_at": "2026-10-21T16:20:05.114Z"
}
```

---

# Send a batch — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/send-batch/

`POST /v1/emails/batch`

Send 1-100 emails in one request.

Requires a full-access or sending-access key. Test keys follow the same rules as for sending.

Per-email error codes use the same classification as POST /emails (domain_not_verified, restricted_api_key, rate_limit_exceeded, monthly_quota_exceeded, etc. appear inside errors[] rather than as the HTTP status). Emails are sent concurrently (up to 16 at a time); each email may have its own scheduled_at.

Body: length 1-100 else 422 invalid_parameter "batch must contain 1 to 100 emails"

An item of `data` carries `reply_to` when reply tracking is on for that email.

### Headers

- `x-batch-validation` (string): strict (default) | permissive (case-insensitive). strict: if any email fails validation nothing is sent and 422 is returned. permissive: valid emails are sent; invalid ones are reported in errors.
- `Idempotency-Key` (string): optional, 1-256 bytes

### Body parameters

- `[ ]` (object[], required): 1–100 emails. Each item takes the fields of [Send an email](https://www.zapsmtp.xyz/docs/emails/send-email/).

### Errors

- `validation_error` (HTTP 400): invalid JSON or x-batch-validation not strict/permissive
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413)
- `invalid_parameter` (HTTP 422): batch size outside 1-100
- `validation_error` (HTTP 422): strict mode, any email invalid
- `service_unavailable` (HTTP 503): too many large bodies in flight

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered@simulator.zapsmtp.xyz"
    ],
    "subject": "Hello Ann",
    "text": "Hi Ann!"
  },
  {
    "from": "Acme <hello@acme.com>",
    "to": [
      "bounced@simulator.zapsmtp.xyz"
    ],
    "subject": "Hello Bob",
    "text": "Hi Bob!"
  }
]'
```

**Response `200 OK`**

```json
{
  "data": [
    {
      "index": 0,
      "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    },
    {
      "index": 2,
      "id": "019a1f2e-7c3c-7a10-8b21-4d5e6f7a8b9c",
      "suppressed": [
        "old@example.org"
      ]
    }
  ],
  "errors": [
    {
      "index": 1,
      "code": "missing_required_field",
      "message": "subject is required"
    }
  ]
}
```

---

# Send an email — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/send-email/

`POST /v1/emails`

Send an email (or schedule it with scheduled_at).

Requires a full-access or sending-access key. Live keys: From domain must be verified by the account. Test keys: any From domain, nothing delivered, monthly quota not charged.

Recipients are deduplicated and lowercased; max 50 across to+cc+bcc. Message-ID is <id>@<hostname>, or <id>.<thread_id>@<hostname> for a reply that continues a conversation.

The response also carries `thread_id`: the conversation this email belongs to. An email with `In-Reply-To` / `References` headers (set them in `headers`) joins the thread of the message it answers; otherwise it starts a new one.

`failed_recipients`: addresses the mail server refused while it took the others; they are not sent and not charged. `unconfirmed: true`: the mail server took the message but its answer was lost; it counts as sent and must not be retried (its events tell the outcome).

Scheduled emails (`scheduled_at`): at most 10,000 (256 MB) may wait per account. At send time the account and the key are checked again: a suspended account or a revoked or expired key fails the email.

With reply tracking on, the response carries `reply_to`: the tracked address the email carries in place of its own Reply-To. Human replies are forwarded to the domain’s `reply_forward_to`, else to the email’s first Reply-To, else to its From.

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `from` (string): RFC 5322 address, e.g. "Acme <hello@acme.com>". Domain must be verified (live keys). When only an address is given, the domain's from_name (brand settings) is used as display name. May be omitted when template is used and the template defines from. Limits: missing → 422 missing_required_field; unparsable → 422 invalid_parameter "invalid from address"
- `to` (string | string[], required): Recipient(s). Limits: at least one; each must parse as an address (422 invalid_parameter "invalid to address ...")
- `cc` (string | string[]): Cc recipients.
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Reply-To address(es).
- `subject` (string): Subject line. May be omitted when template is used and the template defines a subject. Limits: blank → 422 missing_required_field
- `html` (string): HTML body. At least one of html/text is required (unless template is used). Limits: both empty → 422 missing_required_field "html or text is required"; cannot be combined with template (422 invalid_parameter)
- `text` (string): Plain-text body. When only `html` is given, a plain-text part is generated from it (readable text, links as `text (url)`, hidden elements such as the preheader left out).
- `headers` (object<string,string>): Custom headers. Limits: Reserved headers are rejected (422 invalid_parameter "header ... cannot be set"): From, To, Cc, Bcc, Reply-To, Subject, Date, Message-Id, Mime-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, any X-Zap-*, X-ZapRef. Names must be printable ASCII without spaces or ':'.
- `attachments` (object[]): Attachments; 40 MB total. Limits: 422 invalid_attachment with message attachments[i]: set either content or path, not both | content must be base64 | content or path is required | filename is required | path must be an http(s) URL | fetching path returned HTTP <n> | attachments exceed 40MB in total
  - `filename` (string, required): File name shown to the recipient.
  - `content` (string): File content, base64-encoded. Set `content` or `path`, not both.
  - `path` (string): An HTTPS URL we download the file from instead (private and internal addresses are refused).
  - `content_type` (string): MIME type. Detected from the file name when omitted.
  - `content_id` (string): Makes the file inline: reference it in the HTML as `cid:<content_id>`.
- `tags` (object[]): Returned in webhooks as data.tags. Limits: at most 20 tags per email; name and value must match ^[A-Za-z0-9_-]{1,256}$ (422 invalid_parameter)
  - `name` (string, required): Letters, digits, `_` and `-`, up to 256 characters.
  - `value` (string, required): Same characters, up to 256.
- `scheduled_at` (string): RFC 3339 time (e.g. 2026-10-21T15:00:00Z) or relative "in <n> <unit>" with unit min|mins|minute|minutes|h|hour|hours|d|day|days. Times in the past send immediately. Limits: unparsable → 422 invalid_parameter; more than 7 days ahead → 422 invalid_parameter "scheduled_at must be within 7 days"
- `metadata` (object<string,string>): Returned in webhooks and GET /emails; filter with GET /emails?metadata[key]=value. Limits: max 10 keys; keys ^[A-Za-z0-9_-]{1,40}$; values max 500 bytes (UTF-8) (422 invalid_parameter)
- `stream` (string): Limits: other values → 422 invalid_parameter; conflicting with the key's stream → 403 restricted_api_key One of `transactional`, `broadcast`. Default `transactional (or the key's stream)`.
- `tracking` (object): Overrides the From domain's open, click and reply tracking defaults for this email.
  - `opens` (boolean): Track opens for this email.
  - `clicks` (boolean): Track link clicks for this email.
  - `replies` (boolean): Reply tracking: the email carries a signed Reply-To on the domain’s `reply_domain`, so replies come back tied to this email (`email.replied`). Needs a reply domain on the sending domain (see [Update a domain](https://www.zapsmtp.xyz/docs/domains/update-domain/)), else 422 invalid_parameter.
- `template` (object): Render a stored, published template: id = template id or alias. Request subject/from override the template's. Cannot be combined with html/text. Limits: missing id → 422 missing_required_field "template.id is required"; unknown → 422 invalid_parameter "template <id> not found"; never published → 422 invalid_parameter; `variables.global` → 422 invalid_parameter (reserved); a value of the wrong type → 422 template_variables_invalid; a required variable without value or default → 422 template_variables_missing; anything else the template uses still absent → 422 template_render_error "missing template variables: a, b"
  - `id` (string, required): Template id or alias. The template must be published.
  - `variables` (object): Values for the template’s own variables. Checked against the published [variable schema](https://www.zapsmtp.xyz/docs/templating/#schema): defaults fill absent values, optional variables without one render empty, names the schema does not declare are passed through. `global` is reserved: global variables come from the account.
- `tls` (string): `required` or `verified`: deliver only over TLS (`verified`: with a valid certificate for the receiving server). Raises the domain's policy, never lowers it.

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403): key restricted to another domain or stream
- `account_suspended` (HTTP 403): account is suspended
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `payload_too_large` (HTTP 413): request body exceeds 40MB
- `misdirected_cell` (HTTP 421): the account is served by another cell: "this account is served by cell <cell> at <url>", Zap-Cell: <cell>; send to that URL
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422): e.g. too many recipients (max 50), invalid address, bad tags/metadata/stream/scheduled_at, "at least one recipient is required"
- `invalid_attachment` (HTTP 422)
- `template_render_error` (HTTP 422)
- `template_variables_invalid` (HTTP 422): template variables of the wrong type: a, b (checked against the published variable schema)
- `template_variables_missing` (HTTP 422): missing required template variables: a, b (required, no value and no default)
- `rejected` (HTTP 422): the mail transfer agent refused the message: <reason>
- `rate_limit_exceeded` (HTTP 429): rate limit exceeded
- `monthly_quota_exceeded` (HTTP 429): monthly quota exceeded
- `daily_quota_exceeded` (HTTP 429): daily sending limit reached; it resets at 00:00 UTC
- `overloaded` (HTTP 429): server at capacity ("the server is at capacity; retry shortly", Retry-After: 1) or event pipeline backed up ("the event pipeline is backed up; retry shortly", Retry-After: 5); nothing sent, retry
- `service_unavailable` (HTTP 503): a backing store failing over ("a backing service is failing over; retry shortly", Retry-After: 2); MTA unreachable ("mail transfer agent temporarily unavailable, retry"), suppression list being rebuilt ("suppression list is being rebuilt, retry shortly"), or too many large request bodies in flight (Retry-After: 5)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Idempotency-Key: order-1042-receipt' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "to": [
    "delivered@simulator.zapsmtp.xyz"
  ],
  "subject": "Your receipt",
  "html": "<p>Thanks for your order.</p>",
  "tags": [
    {
      "name": "category",
      "value": "receipt"
    }
  ],
  "metadata": {
    "order_id": "A-1042"
  }
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

---

# Share an email — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/share-email/

`POST /v1/emails/{id}/share`

Create a link anyone can open to view a sent email — for a colleague or support. It shows the subject, sender, recipients and body; never attachments or headers.

Requires a full-access live key; test keys get 403 test_key_restricted.

The page renders the body in a sandbox: scripts, forms and external requests other than images are blocked.

### Path parameters

- `id` (string, required): Email id.

### Body parameters

- `expires_in_hours` (integer): 1–720. Default `72`.

### Errors

- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): Unknown email, or past your plan’s log retention.
- `invalid_parameter` (HTTP 422): expires_in_hours out of range.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/share' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "expires_in_hours": 72
}'
```

**Response `201 Created`**

```json
{
  "object": "email_share",
  "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "url": "https://zapsmtp.xyz/t/s/eyJ0Ijoi…",
  "expires_at": "2026-10-25T15:04:10Z"
}
```

---

# Spam-check a draft — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/spam-check-draft/

`POST /v1/emails/spam-check`

Score a draft for spam before sending (nothing is sent or stored).

Requires a full-access or sending-access key.

Body: from missing or both html and text empty → 422 missing_required_field "from and html or text are required". Only these six fields are accepted (others → 400).

### Body parameters

- `from` (string, required): From address; when its domain is verified by the account the draft is DKIM-signed with the real key.
- `to` (string | string[]): Recipient(s); the first is used as envelope recipient. Limits: 422 invalid_parameter "to must be a string or an array of strings" Default `recipient@example.com`.
- `subject` (string)
- `html` (string): At least one of html and text is required.
- `text` (string)
- `stream` (string): Selects the shared pool used to pick the egress IP when the account has no dedicated IP. Default `transactional`.

### Errors

- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422)
- `rate_limit_exceeded` (HTTP 429): spam checks are limited to 30 per minute
- `service_unavailable` (HTTP 503): spam checks are busy, try again shortly
- `scanner_unavailable` (HTTP 503): the spam scanners are temporarily unavailable, try again

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/spam-check' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@acme.com>",
  "subject": "Your receipt",
  "html": "<p>Thanks for your order.</p>"
}'
```

**Response `200 OK`**

```json
{
  "object": "spam_check",
  "score": 1.3,
  "threshold": 5,
  "verdict": "good",
  "engines": [
    {
      "engine": "spamassassin",
      "score": 1.3,
      "threshold": 5,
      "verdict": "good",
      "rules": [
        {
          "name": "HTML_MESSAGE",
          "score": 0.001,
          "description": "HTML included in message"
        },
        {
          "name": "MIME_HTML_ONLY",
          "score": 1.1,
          "description": "Message only has text/html MIME parts"
        }
      ]
    },
    {
      "engine": "rspamd",
      "score": 0.8,
      "threshold": 6,
      "verdict": "good",
      "rules": [
        {
          "name": "MIME_HTML_ONLY",
          "score": 0.2,
          "description": "Messages that have only HTML part"
        }
      ]
    }
  ],
  "dkim_signed": true,
  "sending_ip": "203.0.113.25",
  "issues": [],
  "note": "Scored as a receiving server sees it: DKIM-signed with your key, sent from your egress IP, checked against live DNS blocklists. SpamAssassin is the headline score (≥ 5 = spam); rspamd is shown alongside."
}
```

---

# Spam-check a sent email — Emails API

Source: https://www.zapsmtp.xyz/docs/emails/spam-check-email/

`POST /v1/emails/{id}/spam-check`

Score an already sent email (live or test) from the content archive.

Requires a full-access key.

Always scored with the transactional pool's IP when the account has no dedicated IP. Availability follows GET /emails/{id}/content (plan log retention), although the 404 message says 7 days.

### Path parameters

- `id` (string, required): Email id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): content not available (kept for 7 days)
- `rate_limit_exceeded` (HTTP 429)
- `service_unavailable` (HTTP 503)
- `scanner_unavailable` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/spam-check' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "spam_check",
  "score": 6.2,
  "threshold": 5,
  "verdict": "spam",
  "engines": [
    {
      "engine": "spamassassin",
      "score": 6.2,
      "threshold": 5,
      "verdict": "spam",
      "rules": [
        {
          "name": "URIBL_BLOCKED",
          "score": 0.001,
          "description": "ADMINISTRATOR NOTICE: The query to URIBL was blocked"
        }
      ]
    },
    {
      "engine": "rspamd",
      "score": 4.1,
      "threshold": 6,
      "verdict": "needs_work",
      "rules": []
    }
  ],
  "dkim_signed": false,
  "sending_ip": "203.0.113.25",
  "issues": [
    {
      "kind": "not_signed",
      "message": "The From domain is not verified, so the message is not DKIM-signed and fails DMARC. Verify the domain before sending."
    }
  ],
  "note": "Scored as a receiving server sees it: DKIM-signed with your key, sent from your egress IP, checked against live DNS blocklists. SpamAssassin is the headline score (≥ 5 = spam); rspamd is shown alongside.",
  "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
}
```

---

# Add a forward destination — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/create-forward-destination/

`POST /v1/inbound/forward-destinations`

Add a forward destination: we email it a confirmation link; routes can forward there once its owner confirms.

Requires a full-access live key; test keys get 403 test_key_restricted.

The confirmation page asks for a click, so mail scanners that follow links cannot confirm. Forwarded mail keeps its original From and DKIM, is ARC-signed by us, counts as one sent email and appears in the email log; spam is never forwarded.

### Body parameters

- `email` (string, required): A plain address. Not a ZapSMTP receiving address (it would loop).

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): <email> is already a forward destination
- `invalid_parameter` (HTTP 422): "email must be a plain address (name@example.com)" | "cannot forward to a ZapSMTP receiving address (it would loop)"
- `limit_exceeded` (HTTP 422): at most 20 forward destinations per account
- `rate_limit_exceeded` (HTTP 429): at most 20 forward destinations can be added a day
- `service_unavailable` (HTTP 503): the destination was added but its confirmation email could not be sent; resend it

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/forward-destinations' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "team@acme.com"
}'
```

**Response `201 Created`**

```json
{
  "id": "0199f0b2-0000-7000-8000-00000000f001",
  "email": "team@acme.com",
  "confirmation_sent_at": "2026-10-25T10:00:00Z",
  "verified_at": null,
  "created_at": "2026-10-25T10:00:00Z"
}
```

---

# Add an inbound domain — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/create-inbound-domain/

`POST /v1/inbound/domains`

Create an inbound domain: a managed address (<slug>.<inbound zone>) or your own domain.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `managed` (boolean): true: create an instant managed domain <10 random lowercase chars>.<inbound zone>; no DNS needed; name is ignored. Default `False`.
- `name` (string): Required unless managed is true. Your own domain. It (or a parent) must be verified for sending by the account. Then publish MX 10 <inbound host> and call verify. Limits: invalid → 422 invalid_parameter "invalid domain name"; ZapSMTP-owned names → 422 reserved_domain; not verified for sending → 403 domain_not_verified
- `reject_spam` (boolean): Refuse messages flagged as spam at SMTP time instead of delivering them with is_spam: true. Default `False`.
- `require_tls` (boolean): Accept encrypted mail only: senders without STARTTLS are refused with 530 5.7.0.

### Errors

- `domain_not_verified` (HTTP 403): verify <name> (or its parent domain) for sending first; inbound reuses that proof of ownership
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): this domain already receives mail on ZapSMTP
- `invalid_parameter` (HTTP 422): invalid domain name
- `reserved_domain` (HTTP 422): this domain is reserved by ZapSMTP; use a managed address or your own domain
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "managed": true
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f20-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
  "name": "k3f9x2m7q1.in.zapsmtp.xyz",
  "managed": true,
  "reject_spam": false,
  "mx_verified": true,
  "last_checked_at": "2026-10-21T15:00:00Z",
  "created_at": "2026-10-21T15:00:00Z",
  "records": [],
  "example_address": "anything@k3f9x2m7q1.in.zapsmtp.xyz"
}
```

---

# Create a route — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/create-route/

`POST /v1/inbound/routes`

Create an inbound route (max 100 per account).

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string): Label (trimmed).
- `priority` (integer): Lower runs first; first match wins. Default `100`.
- `match_recipient` (string): Glob (case-insensitive, * and ?) e.g. support+*@acme.com, or /regex/ (RE2, case-insensitive). Empty matches all. Limits: max 512 chars; must compile (422 invalid_parameter)
- `match_sender` (string): Same syntax, matched against the envelope sender. Limits: max 512 chars; must compile
- `match_header` (string): Header name to test.
- `match_header_value` (string): Glob or /regex/ for that header's value. Limits: max 512 chars; must compile
- `action` (string, required): webhook: deliver email.received only to webhook_id; store: keep without webhook; forward: keep and forward to forward_id (a confirmed forward destination); reject: refuse with 550 at SMTP time. Limits: 422 invalid_parameter "action must be webhook, store, reject or forward" One of `webhook`, `store`, `forward`, `reject`.
- `webhook_id` (string | null): Required when action is webhook. A webhook of this account. Cleared for store/reject. Limits: 422 "webhook_id is required for action webhook" / "webhook_id does not belong to this account"
- `forward_id` (string | null): A confirmed forward destination of this account (action forward). Cleared for other actions. Limits: 422 "forward_id is required for action forward" / "forward_id does not belong to this account" / "... is not confirmed yet"
- `enabled` (boolean): Default `True`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): validation failures or "at most 100 routes per account"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/routes' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Support tickets",
  "priority": 10,
  "match_recipient": "support+*@acme.com",
  "action": "store"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "name": "Support tickets",
  "priority": 10,
  "match_recipient": "support+*@acme.com",
  "match_sender": "",
  "match_header": "",
  "match_header_value": "",
  "action": "webhook",
  "webhook_id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "enabled": true,
  "created_at": "2026-10-21T15:20:00Z"
}
```

---

# Remove a forward destination — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/delete-forward-destination/

`DELETE /v1/inbound/forward-destinations/{id}`

Remove a forward destination; routes forwarding there only store from then on.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string): Forward destination id.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): forward destination not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/inbound/forward-destinations/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "forward_destination",
  "id": "0199f0b2-0000-7000-8000-00000000f001",
  "deleted": true
}
```

---

# Delete an inbound domain — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/delete-inbound-domain/

`DELETE /v1/inbound/domains/{id}`

Delete an inbound domain.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string (UUID), required): Inbound domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): inbound domain not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/inbound/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `204` with an empty body.

---

# Delete a route — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/delete-route/

`DELETE /v1/inbound/routes/{id}`

Delete an inbound route.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string (UUID), required): Route id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): route not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/inbound/routes/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `204` with an empty body.

---

# Retrieve an inbound domain — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/get-inbound-domain/

`GET /v1/inbound/domains/{id}`

Retrieve an inbound domain.

Requires a full-access key.

### Path parameters

- `id` (string (UUID), required): Inbound domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): inbound domain not found

```bash
curl 'https://zapsmtp.xyz/v1/inbound/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f21-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "name": "reply.acme.com",
  "managed": false,
  "reject_spam": true,
  "mx_verified": true,
  "last_checked_at": "2026-10-21T15:05:00Z",
  "created_at": "2026-10-20T11:30:00Z",
  "records": [
    {
      "record": "MX",
      "type": "MX",
      "name": "reply.acme.com",
      "value": "10 zapsmtp.xyz",
      "required": true,
      "status": "verified"
    }
  ],
  "example_address": "anything@reply.acme.com"
}
```

---

# Retrieve a route — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/get-route/

`GET /v1/inbound/routes/{id}`

Retrieve an inbound route.

Requires a full-access key.

### Path parameters

- `id` (string (UUID), required): Route id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): route not found

```bash
curl 'https://zapsmtp.xyz/v1/inbound/routes/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "name": "Support tickets",
  "priority": 10,
  "match_recipient": "support+*@acme.com",
  "match_sender": "",
  "match_header": "",
  "match_header_value": "",
  "action": "webhook",
  "webhook_id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "enabled": true,
  "created_at": "2026-10-20T12:00:00Z"
}
```

---

# Inbound stats — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/inbound-stats/

`GET /v1/inbound/stats`

Inbound counters for the last 24 hours.

Requires a full-access key.

### Errors

- `restricted_api_key` (HTTP 403)
- `inbound_not_configured` (HTTP 503)

```bash
curl 'https://zapsmtp.xyz/v1/inbound/stats' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "received": 128,
  "rejected": 3,
  "spam": 7
}
```

---

# List forward destinations — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/list-forward-destinations/

`GET /v1/inbound/forward-destinations`

List the addresses received mail can be forwarded to.

Requires a full-access key.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/inbound/forward-destinations' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "0199f0b2-0000-7000-8000-00000000f001",
      "email": "team@acme.com",
      "confirmation_sent_at": "2026-10-25T10:00:00Z",
      "verified_at": null,
      "created_at": "2026-10-25T10:00:00Z"
    }
  ]
}
```

---

# List inbound domains — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/list-inbound-domains/

`GET /v1/inbound/domains`

List inbound domains (oldest first).

Requires a full-access key.

MX target host comes from config (ZAP_INBOUND_HOST, defaults to the API hostname); managed zone from ZAP_INBOUND_ZONE.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/inbound/domains' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f20-4c5d-7e6f-8a9b-0c1d2e3f4a5b",
      "name": "k3f9x2m7q1.in.zapsmtp.xyz",
      "managed": true,
      "reject_spam": false,
      "mx_verified": true,
      "last_checked_at": "2026-10-20T10:00:00Z",
      "created_at": "2026-10-20T10:00:00Z",
      "records": [],
      "example_address": "anything@k3f9x2m7q1.in.zapsmtp.xyz"
    },
    {
      "id": "019a1f21-5d6e-7f80-9a1b-2c3d4e5f6a7b",
      "name": "reply.acme.com",
      "managed": false,
      "reject_spam": true,
      "mx_verified": false,
      "last_checked_at": null,
      "created_at": "2026-10-20T11:30:00Z",
      "records": [
        {
          "record": "MX",
          "type": "MX",
          "name": "reply.acme.com",
          "value": "10 zapsmtp.xyz",
          "required": true,
          "status": "pending"
        }
      ],
      "example_address": "anything@reply.acme.com"
    }
  ]
}
```

---

# List routes — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/list-routes/

`GET /v1/inbound/routes`

List inbound routes in evaluation order (priority ascending, then created_at).

Requires a full-access key.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/inbound/routes' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
      "name": "Support tickets",
      "priority": 10,
      "match_recipient": "support+*@acme.com",
      "match_sender": "",
      "match_header": "",
      "match_header_value": "",
      "action": "webhook",
      "webhook_id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
      "enabled": true,
      "created_at": "2026-10-20T12:00:00Z"
    }
  ]
}
```

---

# Resend the confirmation — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/resend-forward-confirmation/

`POST /v1/inbound/forward-destinations/{id}/resend`

Email a new confirmation link (the previous one stops working).

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string): Forward destination id.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): no unconfirmed forward destination with this id
- `rate_limit_exceeded` (HTTP 429): a confirmation email was sent less than a minute ago
- `service_unavailable` (HTTP 503): the confirmation email could not be sent; try again

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/forward-destinations/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10/resend' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "0199f0b2-0000-7000-8000-00000000f001",
  "email": "team@acme.com",
  "confirmation_sent_at": "2026-10-25T10:00:00Z",
  "verified_at": null,
  "created_at": "2026-10-25T10:00:00Z"
}
```

---

# Update an inbound domain — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/update-inbound-domain/

`PATCH /v1/inbound/domains/{id}`

Update an inbound domain's spam policy.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string (UUID), required): Inbound domain id

### Body parameters

- `reject_spam` (boolean): Refuse flagged spam (550) instead of delivering it with is_spam: true.
- `require_tls` (boolean): Accept encrypted mail only: senders without STARTTLS are refused with 530 5.7.0.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): inbound domain not found

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/inbound/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "reject_spam": true
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f21-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "name": "reply.acme.com",
  "managed": false,
  "reject_spam": true,
  "mx_verified": true,
  "last_checked_at": "2026-10-21T15:05:00Z",
  "created_at": "2026-10-20T11:30:00Z",
  "records": [
    {
      "record": "MX",
      "type": "MX",
      "name": "reply.acme.com",
      "value": "10 zapsmtp.xyz",
      "required": true,
      "status": "verified"
    }
  ],
  "example_address": "anything@reply.acme.com"
}
```

---

# Update a route — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/update-route/

`PATCH /v1/inbound/routes/{id}`

Update an inbound route (partial; same fields and validation as create).

Requires a full-access live key; test keys get 403 test_key_restricted.

Any subset of the POST /inbound/routes fields. Omitted fields keep their value; webhook_id: "" clears it. The resulting route must still be valid (e.g. action webhook needs webhook_id).

### Path parameters

- `id` (string (UUID), required): Route id

### Body parameters

- `name` (string): Label (trimmed).
- `priority` (integer): Lower runs first; first match wins.
- `match_recipient` (string): Glob (case-insensitive, * and ?) e.g. support+*@acme.com, or /regex/ (RE2, case-insensitive). Empty matches all. Limits: max 512 chars; must compile (422 invalid_parameter)
- `match_sender` (string): Same syntax, matched against the envelope sender. Limits: max 512 chars; must compile
- `match_header` (string): Header name to test.
- `match_header_value` (string): Glob or /regex/ for that header's value. Limits: max 512 chars; must compile
- `action` (string): webhook: deliver email.received only to webhook_id; store: keep without webhook; forward: keep and forward to forward_id (a confirmed forward destination); reject: refuse with 550 at SMTP time. Limits: 422 invalid_parameter "action must be webhook, store, reject or forward" One of `webhook`, `store`, `forward`, `reject`.
- `webhook_id` (string | null): A webhook of this account. Cleared for store/reject. Limits: 422 "webhook_id is required for action webhook" / "webhook_id does not belong to this account"
- `forward_id` (string | null): A confirmed forward destination of this account (action forward). Cleared for other actions. Limits: 422 "forward_id is required for action forward" / "forward_id does not belong to this account" / "... is not confirmed yet"
- `enabled` (boolean)

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): route not found
- `invalid_parameter` (HTTP 422)

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/inbound/routes/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "name": "Support tickets",
  "priority": 5,
  "match_recipient": "support+*@acme.com",
  "match_sender": "",
  "match_header": "",
  "match_header_value": "",
  "action": "store",
  "webhook_id": null,
  "enabled": true,
  "created_at": "2026-10-20T12:00:00Z"
}
```

---

# Verify MX records — Inbound setup API

Source: https://www.zapsmtp.xyz/docs/inbound/verify-inbound-domain/

`POST /v1/inbound/domains/{id}/verify`

Check the domain's MX record now.

Requires a full-access live key; test keys get 403 test_key_restricted.

`mx_verified` becomes `true` as soon as any MX record of the domain points to our inbound host.

### Path parameters

- `id` (string (UUID), required): Inbound domain id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): inbound domain not found

```bash
curl -X POST 'https://zapsmtp.xyz/v1/inbound/domains/019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47/verify' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "domain": {
    "id": "019a1f21-5d6e-7f80-9a1b-2c3d4e5f6a7b",
    "name": "reply.acme.com",
    "managed": false,
    "reject_spam": true,
    "mx_verified": true,
    "last_checked_at": "2026-10-21T15:05:00Z",
    "created_at": "2026-10-20T11:30:00Z",
    "records": [
      {
        "record": "MX",
        "type": "MX",
        "name": "reply.acme.com",
        "value": "10 zapsmtp.xyz",
        "required": true,
        "status": "verified"
      }
    ],
    "example_address": "anything@reply.acme.com"
  },
  "mx_found": [
    "zapsmtp.xyz"
  ]
}
```

---

# Create an API key — API keys & SMTP credentials API

Source: https://www.zapsmtp.xyz/docs/keys/create-api-key/

`POST /v1/api-keys`

Create an API key; the full key (token) is returned only once.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `name` (string, required): Limits: 1-100 characters (not trimmed) → 422 invalid_parameter "name is required (max 100 chars)"
- `permission` (string): One of `full_access`, `sending_access`. Default `full_access`.
- `domain_id` (string): Restrict sending to one of the account's domains. Only with sending_access. Limits: 422 "domain_id can only be used with sending_access" / "unknown domain_id"
- `mode` (string): test creates a zap_test_ key (see [API keys](https://www.zapsmtp.xyz/docs/conventions/#keys)). One of `live`, `test`. Default `live`.
- `stream` (string): Restrict the key to one message stream. One of `transactional`, `broadcast`.
- `expires_at` (string (RFC 3339)): Limits: must be in the future → 422 "expires_at must be in the future"
- `expires_in_days` (integer): Alternative to expires_at; when > 0 it overrides expires_at.

### Errors

- `key_restricted` (HTTP 403): this API key expires, so the keys it manages must expire no later than it does | this API key is limited to the <stream> stream, and so are the keys it manages
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): name, permission, domain_id, mode, stream or expiry invalid

```bash
curl -X POST 'https://zapsmtp.xyz/v1/api-keys' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "checkout-service",
  "permission": "sending_access",
  "mode": "live"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f05-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
  "token": "zap_8fK2mQ9xLr3TzV7bN1cW5yHjP0aS4dE6gU2iO9kX",
  "key": {
    "id": "019a1f05-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
    "name": "Production",
    "prefix": "zap_8fK2mQ",
    "permission": "sending_access",
    "mode": "live",
    "stream": null,
    "expires_at": null,
    "domain_id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
    "last_used_at": null,
    "created_at": "2026-10-21T15:30:00Z"
  }
}
```

---

# Create SMTP credentials — API keys & SMTP credentials API

Source: https://www.zapsmtp.xyz/docs/keys/create-smtp-credential/

`POST /v1/smtp-credentials`

Create an SMTP credential; the password is returned only once.

Requires a full-access live key; test keys get 403 test_key_restricted.

Password: 40 base62 characters. Credentials are sending-only (always behave like sending_access, live mode) and cannot call the HTTP API.

### Body parameters

- `name` (string, required): Limits: trimmed, 1-100 characters → 422 invalid_parameter "name is required (max 100 chars)"
- `domain_id` (string): Restrict the credential to one of the account's domains. Limits: 422 invalid_parameter "unknown domain_id"

### Errors

- `plan_limit_reached` (HTTP 403): the <Plan> plan includes <n> SMTP credentials; upgrade your plan to add more
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/smtp-credentials' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "wordpress-shop"
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f06-4d5e-7f60-8b7c-8d9e0f1a2b3c",
  "name": "WordPress",
  "username": "smtp_k3f9x2m7q1ab",
  "domain_id": null,
  "created_at": "2026-10-21T15:35:00Z",
  "password": "Xa7Lq2Vb9Rk4Tm1Wc8Np3Zs6Hd0Fj5Gy2Ue7Io4K",
  "settings": {
    "host": "zapsmtp.xyz",
    "ports": {
      "465": "TLS",
      "587": "STARTTLS",
      "2525": "STARTTLS"
    },
    "mechanisms": [
      "PLAIN",
      "LOGIN"
    ]
  }
}
```

---

# List API keys — API keys & SMTP credentials API

Source: https://www.zapsmtp.xyz/docs/keys/list-api-keys/

`GET /v1/api-keys`

List active API keys (newest first); tokens are never returned.

Requires a full-access key.

Revoked keys and SMTP credentials are not listed. last_used_at is updated at most every 5 minutes.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/api-keys' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f05-3c4d-7e5f-8a6b-7c8d9e0f1a2b",
      "name": "Production",
      "prefix": "zap_8fK2mQ",
      "permission": "sending_access",
      "mode": "live",
      "stream": "transactional",
      "expires_at": null,
      "domain_id": "019a1f10-8a10-7b22-8c31-5d2e9f0a4b17",
      "last_used_at": "2026-10-21T15:04:10Z",
      "created_at": "2026-10-20T09:00:00Z"
    }
  ]
}
```

---

# List SMTP credentials — API keys & SMTP credentials API

Source: https://www.zapsmtp.xyz/docs/keys/list-smtp-credentials/

`GET /v1/smtp-credentials`

List active SMTP credentials plus the plan limit and relay settings.

Requires a full-access key.

No has_more field on this list. limit = plan's max SMTP credentials (0 = unlimited).

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/smtp-credentials' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "data": [
    {
      "id": "019a1f06-4d5e-7f60-8b7c-8d9e0f1a2b3c",
      "name": "WordPress",
      "username": "smtp_k3f9x2m7q1ab",
      "domain_id": null,
      "last_used_at": "2026-10-21T14:00:00Z",
      "created_at": "2026-10-20T09:30:00Z"
    }
  ],
  "limit": 10,
  "settings": {
    "host": "zapsmtp.xyz",
    "ports": {
      "465": "TLS",
      "587": "STARTTLS",
      "2525": "STARTTLS"
    },
    "mechanisms": [
      "PLAIN",
      "LOGIN"
    ]
  }
}
```

---

# Revoke an API key — API keys & SMTP credentials API

Source: https://www.zapsmtp.xyz/docs/keys/revoke-api-key/

`DELETE /v1/api-keys/{id}`

Revoke an API key immediately.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): API key id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): api key not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/api-keys/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `204` with an empty body.

---

# Revoke SMTP credentials — API keys & SMTP credentials API

Source: https://www.zapsmtp.xyz/docs/keys/revoke-smtp-credential/

`DELETE /v1/smtp-credentials/{id}`

Revoke an SMTP credential.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): SMTP credential id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): smtp credential not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/smtp-credentials/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `204` with an empty body.

---

# Update an API key — API keys & SMTP credentials API

Source: https://www.zapsmtp.xyz/docs/keys/update-api-key/

`PATCH /v1/api-keys/{id}`

Rename a key or change its permission and restrictions. The token and the mode never change; the new rights apply to the next request.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): API key id.

### Body parameters

- `name` (string): 1–100 characters.
- `permission` (string): One of `full_access`, `sending_access`.
- `domain_id` (string | null): Restrict sending to one verified domain (sending access only). `null` lifts the restriction.
- `stream` (string | null): Restrict to one stream. `null` lifts the restriction. One of `transactional`, `broadcast`.

### Errors

- `key_restricted` (HTTP 403): this API key expires, so the keys it manages must expire no later than it does | this API key is limited to the <stream> stream, and so are the keys it manages
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): Unknown or revoked key.
- `invalid_parameter` (HTTP 422): Invalid name, permission or stream; domain_id with full access; unknown domain; "domain_id must be a string or null".

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/api-keys/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "checkout-service",
  "domain_id": "019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1c11-2f3e-7a4b-9c5d-6e7f8a9b0c1d",
  "name": "checkout-service",
  "prefix": "zap_8fK2mQ",
  "permission": "sending_access",
  "mode": "live",
  "stream": null,
  "expires_at": null,
  "domain_id": "019a1e9b-41c2-7a0e-b5d1-3f6c2e8a9d47",
  "last_used_at": "2026-10-22T09:12:00Z",
  "created_at": "2026-10-01T10:00:00Z"
}
```

---

# Retrieve a log — Logs & usage API

Source: https://www.zapsmtp.xyz/docs/logs/get-log/

`GET /v1/logs/{id}`

Retrieve one request with its request and response bodies. Bodies are capped at 16 KB; API keys, passwords and signing secrets are always replaced with `[redacted]`.

Requires a full-access key.

### Path parameters

- `id` (string, required): Log id (the `X-Request-Id` of the response).

### Errors

- `not_found` (HTTP 404): Unknown id, or past your plan’s log retention.

```bash
curl 'https://zapsmtp.xyz/v1/logs/019a1f31-5b2e-7c9d-8e4f-1a2b3c4d5e6f' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "log",
  "id": "019a1f31-5b2e-7c9d-8e4f-1a2b3c4d5e6f",
  "api_key_id": "019a1c11-2f3e-7a4b-9c5d-6e7f8a9b0c1d",
  "method": "POST",
  "path": "/v1/emails",
  "route": "/v1/emails",
  "status": 200,
  "duration_ms": 38,
  "ip": "203.0.113.7",
  "user_agent": "node-fetch/3.3",
  "created_at": "2026-10-22T15:04:10.902Z",
  "request_body": {
    "from": "Acme <hello@acme.com>",
    "to": [
      "delivered@simulator.zapsmtp.xyz"
    ],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>"
  },
  "response_body": {
    "id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
  }
}
```

---

# List logs — Logs & usage API

Source: https://www.zapsmtp.xyz/docs/logs/list-logs/

`GET /v1/logs`

List the API requests made with your keys, newest first. Bodies are on [Retrieve a log](https://www.zapsmtp.xyz/docs/logs/get-log/). Entries appear within seconds and are kept for your plan’s log retention.

Requires a full-access key.

Requests made with API keys are logged; the dashboard’s own calls are not. The `X-Request-Id` header of every response is the id of its log entry.

### Query parameters

- `limit` (integer): 1–100. Default `20`.
- `before` (string): A log id: return older entries.
- `after` (string): A log id: return newer entries.
- `status` (string): An exact status (`422`) or a class: `2xx`, `4xx`, `5xx`.
- `method` (string): HTTP method.
- `path` (string): Path prefix, e.g. `/v1/emails`.
- `api_key_id` (string): Only requests made with this key.

### Errors

- `invalid_parameter` (HTTP 422): before or after is not a log id.

```bash
curl 'https://zapsmtp.xyz/v1/logs?limit=20&status=4xx' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "log",
      "id": "019a1f31-5b2e-7c9d-8e4f-1a2b3c4d5e6f",
      "api_key_id": "019a1c11-2f3e-7a4b-9c5d-6e7f8a9b0c1d",
      "method": "POST",
      "path": "/v1/emails",
      "route": "/v1/emails",
      "status": 200,
      "duration_ms": 38,
      "ip": "203.0.113.7",
      "user_agent": "node-fetch/3.3",
      "created_at": "2026-10-22T15:04:10.902Z"
    }
  ]
}
```

---

# Retrieve usage — Logs & usage API

Source: https://www.zapsmtp.xyz/docs/logs/usage/

`GET /v1/usage`

This month’s sending against your plan: emails sent, included volume, limit, overage and, on the Free plan, today’s count.

Requires a full-access key.

`limit` is `null` on paid plans without a spending cap: email keeps flowing and extra volume is billed. The Free plan adds `daily_limit` and `sent_today`.

```bash
curl 'https://zapsmtp.xyz/v1/usage' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "usage",
  "month": "2026-10",
  "sent": 52310,
  "included": 50000,
  "limit": null,
  "overage_emails": 2310,
  "overage_cents": 196,
  "plan": {
    "id": "pro_50k",
    "name": "Pro 50k",
    "retention_days": 30
  }
}
```

---

# List dedicated IPs — Simulator & dedicated IPs API

Source: https://www.zapsmtp.xyz/docs/platform/dedicated-ips/

`GET /v1/dedicated-ips`

List the account's dedicated IPs with warm-up progress and current blocklist listings.

Requires a full-access key.

`status` is `warming`, `active` or `paused`. During warm-up, `warmup_day` and `daily_cap` show the current day and today’s volume limit. `blocklists` lists current listings of the IP.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/dedicated-ips' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "address": "203.0.113.25",
      "hostname": "mta25.zapsmtp.com",
      "status": "warming",
      "warmup_day": 9,
      "warmup_days": 30,
      "warmup_progress": 0.3,
      "daily_cap": 3000,
      "blocklists": []
    }
  ]
}
```

---

# List simulator addresses — Simulator & dedicated IPs API

Source: https://www.zapsmtp.xyz/docs/platform/simulator/

`GET /v1/simulator`

List the simulator addresses and the events each produces.

Requires a full-access key.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/simulator' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "domain": "simulator.zapsmtp.xyz",
  "note": "Simulator recipients never leave ZapSMTP, work with live and test keys, never touch your suppression list or reputation, and accept +labels (delivered+signup@…).",
  "scenarios": [
    {
      "address": "delivered@simulator.zapsmtp.xyz",
      "event": "email.delivered",
      "result": "250 accepted by the mailbox"
    },
    {
      "address": "bounced@simulator.zapsmtp.xyz",
      "event": "email.bounced",
      "result": "550 5.1.1 Permanent / MailboxDoesNotExist"
    },
    {
      "address": "full@simulator.zapsmtp.xyz",
      "event": "email.bounced",
      "result": "552 5.2.2 Permanent / MailboxFull"
    },
    {
      "address": "blocked@simulator.zapsmtp.xyz",
      "event": "email.bounced",
      "result": "554 5.7.1 Permanent / SpamBlocked"
    },
    {
      "address": "delayed@simulator.zapsmtp.xyz",
      "event": "email.delivery_delayed → email.delivered",
      "result": "451 on the first attempt, delivered ~20 s later"
    },
    {
      "address": "complained@simulator.zapsmtp.xyz",
      "event": "email.delivered → email.complained",
      "result": "delivered, then an ARF abuse complaint"
    },
    {
      "address": "suppressed@simulator.zapsmtp.xyz",
      "event": "email.suppressed",
      "result": "treated as on your suppression list; not sent"
    },
    {
      "address": "bounce+421+4.7.0+try-later@simulator.zapsmtp.xyz",
      "event": "email.delivery_delayed",
      "result": "any reply you need: bounce+<code>[+<x.y.z>][+<words-with-dashes>]"
    }
  ]
}
```

---

# Delete a received email — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/delete-received/

`DELETE /v1/emails/receiving/{id}`

Permanently erase a received email's content and metadata (GDPR erasure).

Requires a full-access live key; test keys get 403 test_key_restricted.

Idempotent: deleting an id that does not exist (but is a valid UUID) still returns 200 deleted:true.

### Path parameters

- `id` (string (UUID), required): Received email id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): id is not a UUID
- `not_ready` (HTTP 409): this email is still being stored; retry the erasure in a few seconds (Retry-After: 5)
- `inbound_not_configured` (HTTP 503)

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/emails/receiving/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
  "deleted": true
}
```

---

# Retrieve an attachment — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/get-received-attachment/

`GET /v1/emails/receiving/{id}/attachments/{aid}`

Retrieve one attachment's metadata and signed download link.

Requires a full-access key.

### Path parameters

- `id` (string (UUID), required): Received email id
- `aid` (string, required): Attachment id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found | attachment not found
- `inbound_not_configured` (HTTP 503)

```bash
curl 'https://zapsmtp.xyz/v1/emails/receiving/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/attachments/att_1' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "attachment",
  "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
  "filename": "screenshot.png",
  "content_type": "image/png",
  "content_disposition": "attachment",
  "content_id": null,
  "size": 48213,
  "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi....aGk",
  "expires_at": "2026-10-21T16:12:00Z"
}
```

---

# Retrieve a received email — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/get-received/

`GET /v1/emails/receiving/{id}`

Retrieve a received email with bodies, headers, authentication results and download links.

Requires a full-access key.

`automated` is null for mail a person wrote, else `{type, reason}`: `bounce` (delivery status notification), `out_of_office`, `auto_reply`, `auto_generated` (notifications, null sender) or `bulk` (mailing lists). Detected from Auto-Submitted, X-Autoreply, Precedence, List-Id, multipart/report and well-known subjects; `reason` names the evidence.

`tls`: the TLS version the sending server used (e.g. `TLSv1_3`); empty when the message was not encrypted.

### Path parameters

- `id` (string (UUID), required): Received email id

### Query parameters

- `html_format` (string): cid: return html as received (cid: references to inline parts). Any other value: inline images are embedded as data: URIs (html_format in the response reports what was returned). One of `data_uri`, `cid`. Default `data_uri`.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): unknown/non-UUID id or past plan retention
- `inbound_not_configured` (HTTP 503)

```bash
curl 'https://zapsmtp.xyz/v1/emails/receiving/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
  "created_at": "2026-10-21T15:10:02.904Z",
  "from": "jane@example.org",
  "to": [
    "support@acme.com"
  ],
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "received_for": [
    "support+1234@acme.com"
  ],
  "subject": "Re: Ticket #1234",
  "message_id": "<CAF=abc123@mail.example.org>",
  "html": "<p>Thanks, that fixed it!</p><blockquote>...</blockquote>",
  "html_format": "data_uri",
  "text": "Thanks, that fixed it!\n\nOn Tue, Oct 21, 2026 Acme wrote:\n> ...",
  "headers": {
    "Subject": "Re: Ticket #1234",
    "From": "Jane Doe <jane@example.org>",
    "To": "support@acme.com"
  },
  "authentication": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass"
  },
  "raw": {
    "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi....Qm9n",
    "expires_at": "2026-10-21T16:12:00Z"
  },
  "attachments": [
    {
      "object": "attachment",
      "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
      "filename": "screenshot.png",
      "content_type": "image/png",
      "content_disposition": "attachment",
      "content_id": null,
      "size": 48213
    }
  ],
  "from_name": "Jane Doe",
  "reply_text": "Thanks, that fixed it!",
  "mailbox_hash": "1234",
  "in_reply_to_email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
  "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
  "automated": null,
  "envelope": {
    "from": "jane@example.org",
    "to": "support+1234@acme.com"
  },
  "spam": {
    "score": 1.2,
    "is_spam": false,
    "action": "no action"
  },
  "arc": "unknown",
  "route_id": "019a1f31-0b2c-7d3e-8f4a-5b6c7d8e9f01",
  "action": "webhook",
  "status": "received",
  "size": 61877,
  "peer_ip": "198.51.100.7",
  "helo": "mail.example.org"
}
```

---

# Retrieve a conversation — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/get-thread/

`GET /v1/threads/{id}`

A conversation: its state (participants, counts, last message, awaiting_reply, unread, metadata) and its received and sent emails, oldest first.

Requires a full-access key.

`awaiting_reply`: the last email a person wrote came in (automated mail does not count). `unread`: something was received after `read_at` (set with `PATCH /threads/{id}`).

Threads are derived from the standard In-Reply-To / References headers: no setup. Every received email, webhook `email.received` and send response carries its `thread_id`.

Refused messages are not part of a thread. At most 500 emails are listed (`has_more`); fetch bodies with `GET /emails/receiving/{id}` and `GET /emails/{id}/content`.

Emails received before 2026-10-23 have a thread id but are not listed here.

### Path parameters

- `id` (string (UUID), required): Thread id (`thread_id` of any email in it)

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): thread not found (or past your plan's log retention)

```bash
curl 'https://zapsmtp.xyz/v1/threads/3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "thread",
  "id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
  "subject": "Where is my order?",
  "participants": [
    "jane@example.org",
    "support@acme.com"
  ],
  "message_count": 3,
  "inbound_count": 2,
  "outbound_count": 1,
  "has_attachments": false,
  "first_message_at": "2026-10-21T15:10:02.904Z",
  "last_message_at": "2026-10-21T16:02:13.540Z",
  "last_inbound_at": "2026-10-21T16:02:13.540Z",
  "last_message": {
    "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
    "direction": "inbound",
    "from": "jane@example.org",
    "subject": "Re: Where is my order?"
  },
  "awaiting_reply": true,
  "unread": true,
  "read_at": null,
  "metadata": {
    "ticket": "T-1042"
  },
  "has_more": false,
  "data": [
    {
      "object": "email",
      "direction": "inbound",
      "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
      "created_at": "2026-10-21T15:10:02.904Z",
      "from": "jane@example.org",
      "to": [
        "support@acme.com"
      ],
      "cc": [],
      "subject": "Where is my order?",
      "message_id": "<CAF=abc123@mail.example.org>"
    },
    {
      "object": "email",
      "direction": "outbound",
      "id": "019a1f41-8b2c-7e3d-9f40-5a6b7c8d9e0f",
      "created_at": "2026-10-21T15:20:41.112Z",
      "from": "Acme Support <support@acme.com>",
      "to": [
        "jane@example.org"
      ],
      "cc": [],
      "subject": "Re: Where is my order?"
    },
    {
      "object": "email",
      "direction": "inbound",
      "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
      "created_at": "2026-10-21T16:02:13.540Z",
      "from": "jane@example.org",
      "to": [
        "support@acme.com"
      ],
      "cc": [],
      "subject": "Automatic reply: Where is my order?",
      "message_id": "<CAF=def456@mail.example.org>",
      "automated": "out_of_office"
    }
  ]
}
```

---

# List attachments — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/list-received-attachments/

`GET /v1/emails/receiving/{id}/attachments`

List a received email's attachments with signed download links.

Requires a full-access key.

Each `download_url` works for one hour without an API key. Files are always served as downloads; HTML, SVG, XML and JavaScript are served as binary so they can never run in a browser.

### Path parameters

- `id` (string (UUID), required): Received email id

### Query parameters

- `limit` (integer): 1-100; when omitted or out of range all attachments are returned.
- `after` (string): Attachment id; returns attachments after it (ignored if unknown).
- `before` (string): Attachment id; returns attachments before it (used only when after is absent).

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found
- `inbound_not_configured` (HTTP 503)

```bash
curl 'https://zapsmtp.xyz/v1/emails/receiving/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/attachments' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "attachment",
      "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
      "filename": "screenshot.png",
      "content_type": "image/png",
      "content_disposition": "attachment",
      "content_id": null,
      "size": 48213,
      "download_url": "https://zapsmtp.xyz/v1/files/eyJ0Ijoi....aGk",
      "expires_at": "2026-10-21T16:12:00Z"
    }
  ]
}
```

---

# List received emails — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/list-received/

`GET /v1/emails/receiving`

List received (inbound) emails, newest first.

Requires a full-access key.

`action` is `default`, `webhook`, `store`, `reject` or `spam_reject`. `in_reply_to_email_id` appears only when the message replies to an email you sent through ZapSMTP.

### Query parameters

- `limit` (integer): 1-100; out-of-range falls back to 20. Default `20`.
- `before` (string): Cursor: an email id or RFC 3339 time; returns messages received before it. An email id gives an exact page boundary. Limits: 422 invalid_parameter "before must be an email id or RFC 3339 time"
- `after` (string): Email id or RFC 3339 time. Limits: 422 invalid_parameter "after must be an email id or RFC 3339 time"
- `q` (string): Case-insensitive substring of sender, recipient or subject, or an exact id.
- `status` (string): One of `received`, `rejected`.
- `domain` (string): Inbound domain name (exact).
- `thread_id` (string (UUID)): Only emails of this conversation (see `GET /threads/{id}`).
- `automated` (string): `false`: only emails a person wrote; `true`: only automated ones; or one type: `bounce`, `out_of_office`, `auto_reply`, `auto_generated`, `bulk`. Limits: 422 invalid_parameter for other values.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422)
- `inbound_not_configured` (HTTP 503): inbound email is not enabled on this deployment

```bash
curl 'https://zapsmtp.xyz/v1/emails/receiving?limit=10' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "email",
      "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
      "from": "jane@example.org",
      "from_name": "Jane Doe",
      "to": [
        "support@acme.com"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "received_for": [
        "support+1234@acme.com"
      ],
      "subject": "Re: Ticket #1234",
      "message_id": "<CAF=abc123@mail.example.org>",
      "created_at": "2026-10-21T15:10:02.904Z",
      "attachments": [
        {
          "id": "5b0f8f7e-2a1c-5d3e-9f4a-6b7c8d9e0f1a",
          "filename": "screenshot.png",
          "content_type": "image/png",
          "content_disposition": "attachment",
          "content_id": null,
          "size": 48213
        }
      ],
      "status": "received",
      "action": "webhook",
      "is_spam": false,
      "spam_score": 1.2,
      "size": 61877,
      "in_reply_to_email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23"
    }
  ]
}
```

---

# List conversations — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/list-threads/

`GET /v1/threads`

List conversations (threads with at least one received email), the most recently active first: a helpdesk inbox.

Requires a full-access key.

Served from a per-conversation summary kept up to date as emails arrive: a page costs the same however much email you have.

A conversation you started (your first email) is counted once the customer answers it.

### Query parameters

- `limit` (integer): 1-100; out-of-range falls back to 20. Default `20`.
- `before` (string): Cursor: the `last_message_at` of the last conversation you have (RFC 3339). Limits: 422 invalid_parameter otherwise.
- `before_id` (string): With before: the id of the last conversation you have, so conversations active at the same instant are neither skipped nor repeated.
- `awaiting_reply` (boolean): `true`: only conversations whose last human email came in.
- `unread` (boolean): `true`: only conversations with an email received after their read mark.
- `participant` (string): Only conversations this address took part in (case-insensitive).

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): before must be an RFC 3339 time

```bash
curl 'https://zapsmtp.xyz/v1/threads?awaiting_reply=true' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "thread",
      "id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
      "subject": "Where is my order?",
      "participants": [
        "jane@example.org",
        "support@acme.com"
      ],
      "message_count": 3,
      "inbound_count": 2,
      "outbound_count": 1,
      "has_attachments": false,
      "first_message_at": "2026-10-21T15:10:02.904Z",
      "last_message_at": "2026-10-21T16:02:13.540Z",
      "last_inbound_at": "2026-10-21T16:02:13.540Z",
      "last_message": {
        "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
        "direction": "inbound",
        "from": "jane@example.org",
        "subject": "Re: Where is my order?"
      },
      "awaiting_reply": true,
      "unread": true,
      "read_at": null,
      "metadata": {
        "ticket": "T-1042"
      }
    }
  ]
}
```

---

# Redeliver to webhooks — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/redeliver-received/

`POST /v1/emails/receiving/{id}/redeliver`

Re-send the email.received webhook for a stored message.

Requires a full-access live key; test keys get 403 test_key_restricted.

The event is re-queued asynchronously (hence 202).

### Path parameters

- `id` (string (UUID), required): Received email id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): email not found
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/receiving/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/redeliver' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `202 `**

```json
{
  "object": "email",
  "id": "019a1f30-1d4e-7a6b-8c2d-3e4f5a6b7c8d",
  "redelivered": true
}
```

---

# Reply to a received email — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/reply-received/

`POST /v1/emails/receiving/{id}/reply`

Reply to a received email: recipients, subject, sender and threading headers default to the email's, so the answer lands in the sender's conversation.

Requires a full-access key. Live keys: the From domain must be verified for sending.

Our Message-ID of the reply names its thread, so the customer's answer joins the conversation even from a mail client that keeps only `In-Reply-To`.

Every other rule of `POST /emails` applies: suppressions, quotas, tracking, test keys.

Loop protection: replies to automated email need `allow_automated`, and one conversation takes at most 20 replies an hour.

### Path parameters

- `id` (string (UUID), required): Received email id

### Headers

- `Idempotency-Key` (string): optional, 1-256 bytes (see [Idempotency](https://www.zapsmtp.xyz/docs/conventions/#idempotency))

### Body parameters

- `text` (string): Plain-text body. Either text or html (or a template) is required.
- `html` (string): HTML body.
- `from` (string): Default: the address that received the email (e.g. `support@acme.com`), which must be on a verified sending domain. Required when the email came to a managed `*.in.zapsmtp.xyz` address (those only receive): 422 missing_required_field.
- `to` (string | string[]): Default: the email's Reply-To, else its From. Limits: 422 missing_required_field when the email has neither.
- `reply_all` (boolean): Also copy everyone on the email's To and Cc, except the receiving address, the sender you reply from and anyone already addressed. Default `false`.
- `allow_automated` (boolean): Answer an automated email anyway (see `automated` on the received email). Without it a reply to a bounce, out-of-office, auto-reply or notification is refused with 422 automated_message: two auto-responders answering each other is a mail loop. Bulk mail can be answered without it. Default `false`.
- `auto_reply` (boolean): This answer is itself automatic (an acknowledgement, a ticket receipt): adds `Auto-Submitted: auto-replied` and `X-Auto-Response-Suppress: All` (RFC 3834), so other auto-responders do not answer it. Default `false`.
- `cc` (string | string[]): Added to the Cc (reply_all adds the email's recipients after these).
- `bcc` (string | string[]): Bcc recipients.
- `reply_to` (string | string[]): Default: the receiving address when you reply from another one, so the customer's answer comes back to the same inbox.
- `subject` (string): Default: `Re: ` + the email's subject (kept as is when it already starts with Re:).
- `headers` (object): Custom headers. `In-Reply-To` and `References` are set for you (RFC 5322 threading); a value you give wins.
- `attachments, tags, metadata, stream, tracking, template, scheduled_at`: As in [POST /emails](https://www.zapsmtp.xyz/docs/emails/send-email/).

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `invalid_idempotency_key` (HTTP 400): Idempotency-Key must be 1 to 256 bytes
- `domain_not_verified` (HTTP 403): sender domain is not verified for this account
- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): email not found
- `idempotency_key_reused` (HTTP 409)
- `idempotency_request_in_progress` (HTTP 409)
- `missing_required_field` (HTTP 422): from (managed receiving address), to (no sender on the email), or the body
- `automated_message` (HTTP 422): the email is a bounce, out-of-office, auto-reply or notification; pass allow_automated: true
- `rate_limit_exceeded` (HTTP 429)
- `thread_reply_limit` (HTTP 429): too many replies in this conversation in the last hour (a mail loop?); at most 20 per hour; Retry-After: 3600
- `inbound_not_configured` (HTTP 503)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/receiving/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/reply' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Thanks, it ships today."
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f41-8b2c-7e3d-9f40-5a6b7c8d9e0f",
  "thread_id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13"
}
```

---

# Report spam / not spam — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/report-received-spam/

`POST /v1/emails/receiving/{id}/spam`

Report a received email as spam or not spam: your account's spam filter learns from it.

Requires a full-access live key; test keys get 403 test_key_restricted.

Each account has its own statistics: your reports never change another account's filter. The filter starts scoring once it has learned 20 emails of each kind. Reporting the same email twice is harmless. `learned` is false when the email has too few words to learn from.

### Path parameters

- `id` (string): Received email id.

### Body parameters

- `spam` (boolean, required): true: mail like this is spam; false: it is wanted. Limits: missing → 422 missing_required_field

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): Unknown email or past your plan's retention.
- `service_unavailable` (HTTP 503): The spam filter could not learn right now; retry.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/emails/receiving/019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23/spam' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "spam": true
}'
```

**Response `200 OK`**

```json
{
  "object": "email",
  "id": "01a17204-bd5b-7691-9fca-52161a26e6d7",
  "spam": true,
  "learned": true
}
```

---

# Mark read, set metadata — Received emails API

Source: https://www.zapsmtp.xyz/docs/receiving/update-thread/

`PATCH /v1/threads/{id}`

Mark a conversation read or unread and set its metadata.

Requires a full-access live key; test keys get 403 test_key_restricted.

Omitted fields are kept.

### Path parameters

- `id` (string (UUID), required): Thread id

### Body parameters

- `read` (boolean): `true` sets `read_at` to now (unread again once a new email arrives); `false` clears it.
- `metadata` (object): Your own key-value pairs (a ticket id, a CRM deal), replacing the previous ones. Limits: at most 20 keys matching [A-Za-z0-9_-]{1,40}, values up to 500 bytes (UTF-8) (422 invalid_parameter).

### Errors

- `validation_error` (HTTP 400): invalid JSON / unknown field
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): thread not found
- `invalid_parameter` (HTTP 422): metadata limits

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/threads/3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "read": true,
  "metadata": {
    "ticket": "T-1042"
  }
}'
```

**Response `200 OK`**

```json
{
  "object": "thread",
  "id": "3f1c9a52-6b0e-5d4f-8a71-2c9e0b4d6f13",
  "subject": "Where is my order?",
  "participants": [
    "jane@example.org",
    "support@acme.com"
  ],
  "message_count": 3,
  "inbound_count": 2,
  "outbound_count": 1,
  "has_attachments": false,
  "first_message_at": "2026-10-21T15:10:02.904Z",
  "last_message_at": "2026-10-21T16:02:13.540Z",
  "last_inbound_at": "2026-10-21T16:02:13.540Z",
  "last_message": {
    "id": "019a1f52-0c1d-7f2e-8a3b-4c5d6e7f8091",
    "direction": "inbound",
    "from": "jane@example.org",
    "subject": "Re: Where is my order?"
  },
  "awaiting_reply": true,
  "unread": false,
  "read_at": "2026-10-21T16:05:00.000Z",
  "metadata": {
    "ticket": "T-1042"
  }
}
```

---

# Metrics by domain, stream, tag or provider — Statistics API

Source: https://www.zapsmtp.xyz/docs/stats/metrics/

`GET /v1/metrics`

Delivery and engagement of live mail by sending domain, stream, tag or mailbox provider, with rates and a time series.

Requires a full-access key.

Counts are recipients, except `delayed`, `opened` and `clicked`: unique emails. Delivery and bounce rates are of `sent`; complaint, open and click rates of `delivered`. Test-mode mail is excluded. Kept for 400 days.

An out-of-band bounce (a later bounce email from the remote server) has no sending domain: it is grouped under an empty `value`.

Totals and the series count each email once whatever the dimension; with `dimension=tag` an email with several tags appears in each of its tags' groups.

### Query parameters

- `from` (string): RFC 3339 start. At most 400 days before `to`. Default `7 days ago`.
- `to` (string): RFC 3339 end (exclusive). Default `now`.
- `granularity` (string): `hour` (ranges up to 31 days) or `day` for `series`. Default `hour up to 48 hours, else day`.
- `dimension` (string): `domain`, `stream`, `tag` or `provider`: adds `groups`, one row per value, busiest first.
- `domain` (string): Only this sending (From) domain.
- `stream` (string): `transactional` or `broadcast`.
- `provider` (string): Gmail, Microsoft, Yahoo, Apple or Other.
- `tag` (string): Only emails with this tag, as `name=value`. Cannot be combined with domain, stream or provider, and groups only by `tag`.

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422): Bad time, range, granularity or dimension, or a tag combined with another filter.

```bash
curl 'https://zapsmtp.xyz/v1/metrics?dimension=domain' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "metrics",
  "from": "2026-10-18T00:00:00Z",
  "to": "2026-10-25T00:00:00Z",
  "granularity": "day",
  "dimension": "domain",
  "totals": {
    "sent": 12400,
    "delivered": 12210,
    "bounced": 95,
    "delayed": 3,
    "complained": 4,
    "opened": 4380,
    "human_opened": 2409,
    "clicked": 912,
    "suppressed": 2,
    "failed": 0,
    "delivery_rate": 0.9847,
    "bounce_rate": 0.0077,
    "complaint_rate": 0.0003,
    "open_rate": 0.3587,
    "human_open_rate": 0.1972,
    "click_rate": 0.0747
  },
  "series": [
    {
      "time": "2026-10-18T00:00:00Z",
      "sent": 1700,
      "delivered": 1676,
      "bounced": 14,
      "delayed": 3,
      "complained": 1,
      "opened": 601,
      "human_opened": 331,
      "clicked": 120,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9859,
      "bounce_rate": 0.0082,
      "complaint_rate": 0.0006,
      "open_rate": 0.3586,
      "human_open_rate": 0.1974,
      "click_rate": 0.0716
    }
  ],
  "groups": [
    {
      "value": "acme.com",
      "sent": 9800,
      "delivered": 9668,
      "bounced": 70,
      "delayed": 3,
      "complained": 3,
      "opened": 3540,
      "human_opened": 1947,
      "clicked": 760,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9865,
      "bounce_rate": 0.0071,
      "complaint_rate": 0.0003,
      "open_rate": 0.3662,
      "human_open_rate": 0.2013,
      "click_rate": 0.0786
    },
    {
      "value": "news.acme.com",
      "sent": 2600,
      "delivered": 2542,
      "bounced": 25,
      "delayed": 3,
      "complained": 1,
      "opened": 840,
      "human_opened": 462,
      "clicked": 152,
      "suppressed": 2,
      "failed": 0,
      "delivery_rate": 0.9777,
      "bounce_rate": 0.0096,
      "complaint_rate": 0.0004,
      "open_rate": 0.3304,
      "human_open_rate": 0.1817,
      "click_rate": 0.0598
    }
  ]
}
```

---

# Breakdown — Statistics API

Source: https://www.zapsmtp.xyz/docs/stats/stats-breakdown/

`GET /v1/stats/breakdown`

Per-provider delivery, bounce classes, engagement and top clicked links.

Requires a full-access key.

Providers are Gmail, Microsoft, Yahoo, Apple and Other. `delayed` counts emails that were delayed at least once.

### Query parameters

- `hours` (integer): 1-720; out-of-range falls back to 24. Default `24`.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/stats/breakdown?hours=168' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "providers": [
    {
      "provider": "Gmail",
      "sent": 920,
      "delivered": 915,
      "bounced": 3,
      "delayed": 4,
      "complained": 1
    },
    {
      "provider": "Microsoft",
      "sent": 410,
      "delivered": 402,
      "bounced": 6,
      "delayed": 9,
      "complained": 0
    }
  ],
  "bounces": [
    {
      "classification": "InvalidRecipient",
      "count": 7
    }
  ],
  "engagement": {
    "delivered": 1840,
    "unique_opens": 702,
    "unique_clicks": 133,
    "opens": 1190,
    "clicks": 201,
    "human_unique_opens": 386,
    "machine_opens": 595
  },
  "top_links": [
    {
      "url": "https://acme.com/orders/A-1042",
      "clicks": 88,
      "unique": 80
    }
  ]
}
```

---

# Time series — Statistics API

Source: https://www.zapsmtp.xyz/docs/stats/stats-timeseries/

`GET /v1/stats/timeseries`

Event counts by status in time buckets.

Requires a full-access key.

One point per (bucket, status); empty buckets are not emitted. Test-mode traffic excluded.

### Query parameters

- `hours` (integer): 1-720; out-of-range falls back to 24. Bucket size: <=1h → 60 s, <=6h → 300 s, <=24h → 1800 s, <=168h → 10800 s, otherwise 43200 s. Default `24`.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/stats/timeseries?hours=24' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "hours": 24,
  "bucket_seconds": 1800,
  "since": "2026-10-20T15:00:00Z",
  "data": [
    {
      "t": "2026-10-20T15:00:00Z",
      "status": "delivered",
      "count": 74
    },
    {
      "t": "2026-10-20T15:00:00Z",
      "status": "queued",
      "count": 75
    }
  ]
}
```

---

# Totals — Statistics API

Source: https://www.zapsmtp.xyz/docs/stats/stats/

`GET /v1/stats`

Event counts by status over the last N hours (live traffic only).

Requires a full-access key.

Counts events (not unique emails), ordered by status name; test-mode traffic excluded.

### Query parameters

- `hours` (integer): 1-720; out-of-range falls back to 24. Default `24`.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/stats?hours=24' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "hours": 24,
  "data": [
    {
      "status": "bounced",
      "count": 12
    },
    {
      "status": "delivered",
      "count": 1840
    },
    {
      "status": "queued",
      "count": 1861
    }
  ]
}
```

---

# Add a suppression — Suppressions API

Source: https://www.zapsmtp.xyz/docs/suppressions/add-suppression/

`POST /v1/suppressions`

Add an address to the suppression list.

Requires a full-access live key; test keys get 403 test_key_restricted.

Idempotent: an existing entry keeps its reason, except that an `unsubscribe` entry becomes `manual` when you add it as manual (a later bounce or complaint upgrades it the same way). The response echoes the requested reason with 201.

### Body parameters

- `email` (string, required): Address (stored lowercased). Limits: 422 invalid_parameter "invalid email"
- `reason` (string): `manual`: no email at all; `unsubscribe`: no broadcast email (transactional email still goes out). Limits: 422 invalid_parameter "reason must be manual or unsubscribe" One of `manual`, `unsubscribe`. Default `manual`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/suppressions' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "former-customer@example.com",
  "reason": "manual"
}'
```

**Response `201 Created`**

```json
{
  "email": "someone@example.org",
  "reason": "manual"
}
```

---

# Add suppressions in bulk — Suppressions API

Source: https://www.zapsmtp.xyz/docs/suppressions/add-suppressions/

`POST /v1/suppressions/batch`

Add up to 1,000 addresses in one call. Duplicates are ignored; existing entries keep their reason (an unsubscribe becomes manual when added as manual); sends see the change immediately.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `emails` (string[], required): 1–1,000 addresses.
- `reason` (string): `manual`: no email at all; `unsubscribe`: no broadcast email (transactional email still goes out). One of `manual`, `unsubscribe`. Default `manual`.

### Errors

- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): Empty or over 1,000 addresses, an invalid address, or an unknown reason.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/suppressions/batch' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "ann@example.com",
    "bob@example.com"
  ],
  "reason": "manual"
}'
```

**Response `201 Created`**

```json
{
  "object": "suppression_batch",
  "added": 2,
  "reason": "manual",
  "emails": [
    "ann@example.com",
    "bob@example.com"
  ]
}
```

---

# Remove a suppression — Suppressions API

Source: https://www.zapsmtp.xyz/docs/suppressions/delete-suppression/

`DELETE /v1/suppressions/{email}`

Remove an address from the suppression list.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `email` (string, required): Address (URL-encoded; matched case-insensitively)

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): suppression not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/suppressions/former-customer%40example.com' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `204` with an empty body.

---

# Retrieve a suppression — Suppressions API

Source: https://www.zapsmtp.xyz/docs/suppressions/get-suppression/

`GET /v1/suppressions/{email}`

Check whether one address is suppressed, and why.

Requires a full-access key.

`unsubscribe` stops only broadcast email (`stream: broadcast`); transactional email to the address still goes out. Every other reason stops all email to it.

### Path parameters

- `email` (string, required): The address (case-insensitive, URL-encoded).

### Errors

- `not_found` (HTTP 404): The address is not suppressed.

```bash
curl 'https://zapsmtp.xyz/v1/suppressions/former-customer%40example.com' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "email": "former-customer@example.com",
  "reason": "unsubscribe",
  "source_id": null,
  "created_at": "2026-10-20T08:00:00Z"
}
```

---

# List suppressions — Suppressions API

Source: https://www.zapsmtp.xyz/docs/suppressions/list-suppressions/

`GET /v1/suppressions`

List suppressed addresses, newest first, with cursor pagination.

Requires a full-access key.

`reason` is `hard_bounce`, `complaint`, `unsubscribe` or `manual`; `source_id` is the email that caused it (`null` when added by hand). Pass `next_cursor` as `after` for the next page.

`unsubscribe` stops only broadcast email (`stream: broadcast`); transactional email to the address still goes out. Every other reason stops all email to it.

### Query parameters

- `limit` (integer): 1-1000; out-of-range falls back to 100. Default `100`.
- `after` (string): Opaque cursor from next_cursor. Limits: 422 invalid_parameter "invalid after cursor"
- `before` (string): Legacy: RFC 3339 timestamp; returns entries created before it. Ignored when after is set. Limits: 422 invalid_parameter "before must be RFC3339"

### Errors

- `restricted_api_key` (HTTP 403)
- `invalid_parameter` (HTTP 422)

```bash
curl 'https://zapsmtp.xyz/v1/suppressions?limit=20' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "email": "old@example.org",
      "reason": "hard_bounce",
      "source_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "created_at": "2026-10-21T15:04:13Z"
    },
    {
      "email": "angry@example.net",
      "reason": "complaint",
      "source_id": "019a1f2a-1b2c-7d3e-8f4a-5b6c7d8e9f00",
      "created_at": "2026-10-21T11:20:40Z"
    }
  ],
  "next_cursor": "MTc2MTA0NzI0MDAwMDAwMDAwMHxhbmdyeUBleGFtcGxlLm5ldA"
}
```

---

# Remove suppressions in bulk — Suppressions API

Source: https://www.zapsmtp.xyz/docs/suppressions/remove-suppressions/

`POST /v1/suppressions/batch/remove`

Remove up to 1,000 addresses in one call. Addresses that are not on the list are ignored.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Body parameters

- `emails` (string[], required): 1–1,000 addresses.

### Errors

- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): Empty or over 1,000 addresses, or an invalid address.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/suppressions/batch/remove' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "ann@example.com",
    "bob@example.com"
  ]
}'
```

**Response `200 OK`**

```json
{
  "object": "suppression_batch",
  "removed": 1,
  "emails": [
    "ann@example.com"
  ]
}
```

---

# Save a module — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/create-template-module/

`POST /v1/template-modules`

Save rows as a module that every template of the account can insert.

Requires a full-access live key; test keys get 403 test_key_restricted.

Inserting a module copies its rows into the template: changing the module later does not change templates that already use it.

### Body parameters

- `name` (string, required): Limits: trimmed, 1-200 characters → 422 missing_required_field
- `category` (string): Groups modules in the editor’s palette. Limits: trimmed, max 100 characters → 422 missing_required_field Default `""`.
- `design` (object, required): The saved rows: `{"rows": [...]}` with at least one row in the visual editor’s format (copy rows from a template’s `design`). Limits: max 1 MB → 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `payload_too_large` (HTTP 413): request body too large
- `invalid_parameter` (HTTP 422): design must be {"rows": [...]} with at least one row (max 1 MB)
- `missing_required_field` (HTTP 422): name is required (max 200 chars), category max 100 chars

```bash
curl -X POST 'https://zapsmtp.xyz/v1/template-modules' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Footer",
  "category": "Brand",
  "design": {
    "rows": [
      {
        "id": "r1",
        "columns": [
          {
            "id": "c1",
            "width": 100,
            "blocks": [
              {
                "id": "b1",
                "type": "text",
                "html": "<p>Acme Inc. · 1 Market St, San Francisco</p>"
              }
            ]
          }
        ]
      }
    ]
  }
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f61-4e5f-7a60-8b71-8c9d0e1f2a3b",
  "name": "Footer",
  "category": "Brand",
  "design": {
    "rows": [
      {
        "id": "r1",
        "columns": [
          {
            "id": "c1",
            "width": 100,
            "blocks": [
              {
                "id": "b1",
                "type": "text",
                "html": "<p>Acme Inc. · 1 Market St, San Francisco</p>"
              }
            ]
          }
        ]
      }
    ]
  },
  "created_at": "2026-10-22T16:00:00Z",
  "updated_at": "2026-10-22T16:00:00Z"
}
```

---

# Create a countdown timer — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/create-template-timer/

`POST /v1/template-timers`

Create a countdown timer image: an animated GIF that shows the time left whenever the email is opened.

Requires a full-access live key; test keys get 403 test_key_restricted.

Nothing is stored: the URL carries the signed settings, so changing it breaks the image. Put it in an `<img>` of a template (the visual editor’s timer block does this for you).

Each open renders one frame per second for a minute, then the last frame stays; after `end` it shows zeros. Renders are shared for 5 seconds, so a broadcast opened by many recipients at once costs one render.

### Body parameters

- `end` (string (RFC 3339), required): When the countdown reaches zero. Limits: missing → 422 invalid_parameter "end is required"; not RFC 3339 → 400 validation_error
- `width` (integer): Image width in px, 200-600; the height follows. Limits: otherwise 422 invalid_parameter "w must be 200–600" Default `600`.
- `digit_color` (string, required): Digit colour, hex `RRGGBB` or `RRGGBBAA` (a leading # is allowed). Limits: otherwise 422 invalid_parameter "fg: colour must be RRGGBB or RRGGBBAA"
- `label_color` (string, required): Label colour, same format. Limits: 422 invalid_parameter "lc: …"
- `background` (string, required): Background colour, same format; alpha `00` (e.g. `ffffff00`) is transparent. Limits: 422 invalid_parameter "bg: …"
- `labels` (string[]): Exactly 4 labels under days, hours, minutes and seconds, each up to 12 characters, without `|`. `""` hides one label; four empty labels hide the label row. Limits: 422 invalid_parameter "l must hold 4 labels separated by |" / "labels are limited to 12 characters" Default `["days", "hours", "minutes", "seconds"]`.

### Errors

- `validation_error` (HTTP 400): invalid JSON body (e.g. end not RFC 3339)
- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): see the fields

```bash
curl -X POST 'https://zapsmtp.xyz/v1/template-timers' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "end": "2026-11-28T23:59:59Z",
  "digit_color": "111827",
  "label_color": "6b7280",
  "background": "ffffff"
}'
```

**Response `200 OK`**

```json
{
  "object": "template_timer",
  "url": "https://zapsmtp.xyz/i/timer.gif?bg=ffffff&end=1795910399&fg=111827&l=days%7Chours%7Cminutes%7Cseconds&lc=6b7280&w=600&sig=Hk3x9vQm2LrT8aWc"
}
```

---

# Delete an image — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/delete-template-asset/

`DELETE /v1/template-assets/{id}`

Delete an image. Its URL stops working, also in emails already sent.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string (UUID), required): Image id.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): image not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/template-assets/5b0e3c1a-9d2f-4e7b-8a61-2f4c6d8e0a13' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "template_asset",
  "id": "5b0e3c1a-9d2f-4e7b-8a61-2f4c6d8e0a13",
  "deleted": true
}
```

---

# Delete a module — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/delete-template-module/

`DELETE /v1/template-modules/{id}`

Delete a module. Templates that inserted it keep their copy.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string (UUID), required): Module id.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): module not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/template-modules/019a1f61-4e5f-7a60-8b71-8c9d0e1f2a3b' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "template_module",
  "id": "019a1f61-4e5f-7a60-8b71-8c9d0e1f2a3b",
  "deleted": true
}
```

---

# Retrieve a module — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/get-template-module/

`GET /v1/template-modules/{id}`

Retrieve a module.

Requires a full-access key.

### Path parameters

- `id` (string (UUID), required): Module id.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): module not found

```bash
curl 'https://zapsmtp.xyz/v1/template-modules/019a1f61-4e5f-7a60-8b71-8c9d0e1f2a3b' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f61-4e5f-7a60-8b71-8c9d0e1f2a3b",
  "name": "Footer",
  "category": "Brand",
  "design": {
    "rows": [
      {
        "id": "r1",
        "columns": [
          {
            "id": "c1",
            "width": 100,
            "blocks": [
              {
                "id": "b1",
                "type": "text",
                "html": "<p>Acme Inc. · 1 Market St, San Francisco</p>"
              }
            ]
          }
        ]
      }
    ]
  },
  "created_at": "2026-10-22T16:00:00Z",
  "updated_at": "2026-10-22T16:00:00Z"
}
```

---

# List images — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/list-template-assets/

`GET /v1/template-assets`

List the account’s template images, newest first.

Requires a full-access key.

All images of the account in one page (`has_more` is always false).

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/template-assets' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "5b0e3c1a-9d2f-4e7b-8a61-2f4c6d8e0a13",
      "name": "logo.png",
      "ext": "png",
      "content_type": "image/png",
      "size": 18342,
      "width": 480,
      "height": 120,
      "created_at": "2026-10-22T16:10:00Z",
      "object": "template_asset",
      "url": "https://zapsmtp.xyz/i/5b0e3c1a-9d2f-4e7b-8a61-2f4c6d8e0a13.png"
    }
  ]
}
```

---

# List modules — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/list-template-modules/

`GET /v1/template-modules`

List saved modules (reusable rows for the visual editor), most recently updated first.

Requires a full-access key.

All modules of the account in one page (`has_more` is always false).

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/template-modules' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f61-4e5f-7a60-8b71-8c9d0e1f2a3b",
      "name": "Footer",
      "category": "Brand",
      "design": {
        "rows": [
          {
            "id": "r1",
            "columns": [
              {
                "id": "c1",
                "width": 100,
                "blocks": [
                  {
                    "id": "b1",
                    "type": "text",
                    "html": "<p>Acme Inc. · 1 Market St, San Francisco</p>"
                  }
                ]
              }
            ]
          }
        ]
      },
      "created_at": "2026-10-22T16:00:00Z",
      "updated_at": "2026-10-22T16:00:00Z"
    }
  ]
}
```

---

# Update a module — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/update-template-module/

`PATCH /v1/template-modules/{id}`

Rename, recategorize or replace a module’s rows.

Requires a full-access live key; test keys get 403 test_key_restricted.

Fields left out keep their value.

### Path parameters

- `id` (string (UUID), required): Module id.

### Body parameters

- `name` (string): Limits: trimmed, 1-200 characters → 422 missing_required_field
- `category` (string): Groups modules in the editor’s palette. Limits: trimmed, max 100 characters → 422 missing_required_field
- `design` (object): The saved rows: `{"rows": [...]}` with at least one row in the visual editor’s format (copy rows from a template’s `design`). Limits: max 1 MB → 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): module not found
- `payload_too_large` (HTTP 413): request body too large
- `invalid_parameter` (HTTP 422): design must be {"rows": [...]} with at least one row (max 1 MB)
- `missing_required_field` (HTTP 422): name is required (max 200 chars), category max 100 chars

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/template-modules/019a1f61-4e5f-7a60-8b71-8c9d0e1f2a3b' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "category": "Footers"
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f61-4e5f-7a60-8b71-8c9d0e1f2a3b",
  "name": "Footer",
  "category": "Footers",
  "design": {
    "rows": [
      {
        "id": "r1",
        "columns": [
          {
            "id": "c1",
            "width": 100,
            "blocks": [
              {
                "id": "b1",
                "type": "text",
                "html": "<p>Acme Inc. · 1 Market St, San Francisco</p>"
              }
            ]
          }
        ]
      }
    ]
  },
  "created_at": "2026-10-22T16:00:00Z",
  "updated_at": "2026-10-23T09:30:00Z"
}
```

---

# Upload an image — Modules, images & timers API

Source: https://www.zapsmtp.xyz/docs/template-library/upload-template-asset/

`POST /v1/template-assets`

Upload an image for use in templates, as a multipart file or by URL; returns its public URL.

Requires a full-access live key; test keys get 403 test_key_restricted.

PNG, JPEG, GIF or WebP, up to 5 MB and 40 megapixels; the file content decides the type, not its name. PNG and JPEG images wider than 1,200 px are scaled down to 1,200 px (twice a 600 px email); GIF (animations included) and WebP are kept as they are. `width` and `height` are those of the stored image.

The URL is public (anyone with it can load the image) and long-lived: use it in `<img src>` of any template. The name keeps letters, digits, spaces and `. _ ( ) -`, up to 200 characters.

Each account holds up to 2,000 images and 1 GB.

### Headers

- `Content-Type` (string, required): `multipart/form-data` with the image in field `file`, or `application/json` with the body below.

### Body parameters

- `url` (string, required): JSON upload: an http(s) URL we download the image from (private and internal addresses are refused). Limits: unreachable, not HTTP 200 or not a URL → 422 invalid_parameter
- `name` (string): JSON upload: the file name shown in the image library. Default `the last segment of the URL`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `payload_too_large` (HTTP 413): images are limited to 5 MB
- `invalid_image` (HTTP 422): only PNG, JPEG, GIF and WebP images are accepted | image dimensions are too large | images are limited to 5 MB | the image could not be decoded
- `invalid_parameter` (HTTP 422): send the image as multipart field "file", or JSON {"url": "..."} | url must be an http(s) URL | fetching url returned HTTP <n> | could not fetch url: <reason> | the image at url is over 5 MB
- `quota_exceeded` (HTTP 422): image library is full (2,000 images or 1 GB): delete unused images first
- `storage_unavailable` (HTTP 503): object storage is not configured

```bash
curl -X POST 'https://zapsmtp.xyz/v1/template-assets' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/brand/logo.png",
  "name": "logo.png"
}'
```

**Response `201 Created`**

```json
{
  "id": "5b0e3c1a-9d2f-4e7b-8a61-2f4c6d8e0a13",
  "name": "logo.png",
  "ext": "png",
  "content_type": "image/png",
  "size": 18342,
  "width": 480,
  "height": 120,
  "created_at": "2026-10-22T16:10:00Z",
  "object": "template_asset",
  "url": "https://zapsmtp.xyz/i/5b0e3c1a-9d2f-4e7b-8a61-2f4c6d8e0a13.png"
}
```

---

# Create a template — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/create-template/

`POST /v1/templates`

Create a template (logic-less Mustache).

Requires a full-access live key; test keys get 403 test_key_restricted.

Syntax: {{var}} escaped, {{{var}}} raw, {{#list}}…{{/list}} sections, {{^x}}…{{/x}} inverted sections. Exact ordering of variable_names is determined by the parser; the example order is illustrative.

Body: html and text both empty → 422 missing_required_field; template syntax errors → 422 template_render_error "<field>: <error>"; a tag that is not a variable name ({{first name}}, {{#each items}}, {{> footer}}) → 422 template_render_error "html: line L, column C: {{…}} is not a variable name: …"

`variable_schema` in the response is the saved list after discovery. A send is checked against the published copy, `published.variable_schema`.

### Body parameters

- `name` (string, required): Limits: trimmed, 1-200 characters → 422 missing_required_field "name is required (max 200 chars)"
- `alias` (string): Stable handle usable instead of the id (template.id in sends, /templates/{alias}). Limits: ^[a-z0-9][a-z0-9_-]{0,62}$ → 422 invalid_parameter; duplicate → 409 conflict
- `subject` (string): Mustache source.
- `html` (string): At least one of html and text is required. Mustache source; {{var}} is HTML-escaped, {{{var}}} raw.
- `text` (string)
- `from` (string): Default From used when a send omits from.
- `variables` (object): Sample variables used by previews. Never used for sending; a variable first found in the source takes its sample as `example`.
- `variable_schema` (object[]): Declares the template’s variables (see [Variable schema](https://www.zapsmtp.xyz/docs/templating/#schema)). Replaces the declared list when given. On every save, names the source uses that the list lacks are added (their sample value as example): a section {{#x}} as optional `any`, a dotted {{x.y}} as a required `object`, any other name as a required `any`, never stricter than sends were before, and declared names the source no longer uses are kept with `unused: true`. Limits: at most 200 entries, no duplicates, defaults and examples of their type → 422 invalid_parameter "variable_schema: <reason>"
  - `name` (string, required): Variable name: letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved.
  - `type` (string, required): What a send must pass. One of `string`, `number`, `boolean`, `url`, `date`, `list`, `object`, `any`.
  - `required` (boolean): A send without a value (or with `null`) and without a default is refused with `template_variables_missing`. Default `false`.
  - `default` (any): Used when a send gives no value; must be of `type`.
  - `example` (any): Used by previews; must be of `type`.
  - `description` (string): For your team; at most 500 bytes.
- `design` (object | null): The visual editor’s document (a JSON object with a numeric `version`), stored with the template. `null` makes it a code template. Changing `html` without sending `design` drops the design (it no longer describes the HTML). Limits: max 1 MB → 422 invalid_parameter "design is larger than 1 MB"; not an object with a numeric version → 422 invalid_parameter
- `publish` (boolean): Publish the result in the same call. Without it the template stays a draft and is not used for sending until [published](https://www.zapsmtp.xyz/docs/templates/publish-template/). Default `false`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `conflict` (HTTP 409): a template with this alias already exists
- `payload_too_large` (HTTP 413): request body too large (over 4 MB)
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422)
- `template_render_error` (HTTP 422): template syntax error: "<field>: <error>"
- `template_render_error` (HTTP 422): a tag that is not a variable name, e.g. {{first name}}, {{#each items}}, {{> footer}}: "html: line L, column C: {{…}} is not a variable name: letters, digits, _ and - (no spaces), parts joined with dots"

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Welcome",
  "alias": "welcome",
  "subject": "Welcome, {{first_name}}",
  "html": "<p>Hi {{first_name}}, your workspace is ready.</p>",
  "publish": true
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "name": "Receipt",
  "alias": "receipt",
  "subject": "Your receipt for {{order_id}}",
  "html": "<p>Hi {{name}}, thanks for order {{order_id}}.</p>",
  "text": "Hi {{name}}, thanks for order {{order_id}}.",
  "from": "Acme <billing@acme.com>",
  "variables": {
    "name": "Jane",
    "order_id": "A-1042"
  },
  "variable_schema": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "example": "A-1042",
      "description": "Order number shown to the customer"
    },
    {
      "name": "name",
      "type": "string",
      "required": false,
      "default": "there",
      "example": "Jane"
    }
  ],
  "design": null,
  "created_at": "2026-10-21T16:10:00Z",
  "updated_at": "2026-10-21T16:10:00Z",
  "object": "template",
  "variable_names": [
    "order_id",
    "name"
  ],
  "status": "draft",
  "has_unpublished_changes": false,
  "published_at": null,
  "published": null
}
```

---

# Delete a template — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/delete-template/

`DELETE /v1/templates/{id}`

Delete a template.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Template id or alias

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): template not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/templates/welcome' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "template",
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "deleted": true
}
```

---

# Duplicate a template — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/duplicate-template/

`POST /v1/templates/{id}/duplicate`

Copy a template’s draft into a new, unpublished template named “… (copy)”, without the alias.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Template id or alias.

### Errors

- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): Unknown template.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/welcome/duplicate' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `201 Created`**

```json
{
  "object": "template",
  "id": "019a1f52-3e4f-7a5b-8c6d-7e8f9a0b1c2d",
  "name": "Welcome (copy)",
  "alias": null,
  "status": "draft",
  "has_unpublished_changes": false,
  "published_at": null,
  "published": null
}
```

---

# Retrieve a version — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/get-template-version/

`GET /v1/templates/{id}/versions/{vid}`

Retrieve one version with its bodies and design.

Requires a full-access key.

Empty `html`, `text` and `from` are left out, and so is `design` for a code template.

### Path parameters

- `id` (string, required): Template id or alias.
- `vid` (string (UUID), required): Version id from the list.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): template not found | version not found

```bash
curl 'https://zapsmtp.xyz/v1/templates/welcome/versions/019a1f58-2b3c-7d4e-8f50-6a7b8c9d0e1f' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f58-2b3c-7d4e-8f50-6a7b8c9d0e1f",
  "kind": "saved",
  "author": "jane@acme.com",
  "name": "Welcome",
  "subject": "Welcome, {{first_name}}",
  "html": "<p>Hi {{first_name}}, welcome to Acme.</p>",
  "text": "Hi {{first_name}}, welcome to Acme.",
  "from": "Acme <hello@acme.com>",
  "created_at": "2026-10-22T14:52:00Z"
}
```

---

# Retrieve a template — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/get-template/

`GET /v1/templates/{id}`

Retrieve a template by id or alias.

Requires a full-access key.

`id` is what `template.id` takes when you send; the alias works too. `published` is the version sends use (`null` until the first publish).

`published.variable_schema` is `null` for a template last published before variable schemas existed: its sends need every variable, as before, until it is published again.

### Path parameters

- `id` (string, required): Template id (UUID) or alias

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): template not found

```bash
curl 'https://zapsmtp.xyz/v1/templates/welcome' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
  "name": "Receipt",
  "alias": "receipt",
  "subject": "Your receipt for {{order_id}}",
  "html": "<p>Hi {{name}}, thanks for order {{order_id}}.</p>",
  "text": "Hi {{name}}, thanks for order {{order_id}}.",
  "from": "Acme <billing@acme.com>",
  "variables": {
    "name": "Jane",
    "order_id": "A-1042"
  },
  "variable_schema": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "example": "A-1042",
      "description": "Order number shown to the customer"
    },
    {
      "name": "name",
      "type": "string",
      "required": false,
      "default": "there",
      "example": "Jane"
    }
  ],
  "design": null,
  "created_at": "2026-10-21T16:10:00Z",
  "updated_at": "2026-10-21T16:10:00Z",
  "object": "template",
  "variable_names": [
    "order_id",
    "name"
  ],
  "status": "published",
  "has_unpublished_changes": false,
  "published_at": "2026-10-21T16:12:00Z",
  "published": {
    "subject": "Your receipt for {{order_id}}",
    "html": "<p>Hi {{name}}, thanks for order {{order_id}}.</p>",
    "text": "Hi {{name}}, thanks for order {{order_id}}.",
    "from": "Acme <billing@acme.com>",
    "design": null,
    "variable_schema": [
      {
        "name": "order_id",
        "type": "string",
        "required": true,
        "example": "A-1042",
        "description": "Order number shown to the customer"
      },
      {
        "name": "name",
        "type": "string",
        "required": false,
        "default": "there",
        "example": "Jane"
      }
    ]
  }
}
```

---

# List versions — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/list-template-versions/

`GET /v1/templates/{id}/versions`

List a template’s saved versions, newest first.

Requires a full-access key.

A version is recorded on every create, update, publish and restore: `kind` is `saved`, `published` or `restored`. `author` is the teammate’s email, or `API key`. The newest 50 versions are kept. List items leave out the bodies; retrieve a version for them.

### Path parameters

- `id` (string, required): Template id or alias.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): template not found

```bash
curl 'https://zapsmtp.xyz/v1/templates/welcome/versions' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f5a-3d4e-7f50-9a61-7b8c9d0e1f2a",
      "kind": "published",
      "author": "API key",
      "name": "Welcome",
      "subject": "Welcome, {{first_name}}",
      "created_at": "2026-10-22T15:10:00Z"
    },
    {
      "id": "019a1f58-2b3c-7d4e-8f50-6a7b8c9d0e1f",
      "kind": "saved",
      "author": "jane@acme.com",
      "name": "Welcome",
      "subject": "Welcome, {{first_name}}",
      "created_at": "2026-10-22T14:52:00Z"
    }
  ]
}
```

---

# List templates — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/list-templates/

`GET /v1/templates`

List templates (most recently updated first).

Requires a full-access key.

`variables` are sample values for previews; `variable_names` lists the variables used in the subject and bodies.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/templates' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
      "name": "Receipt",
      "alias": "receipt",
      "subject": "Your receipt for {{order_id}}",
      "html": "<p>Hi {{name}}, thanks for order {{order_id}}.</p>",
      "text": "Hi {{name}}, thanks for order {{order_id}}.",
      "from": "Acme <billing@acme.com>",
      "variables": {
        "name": "Jane",
        "order_id": "A-1042"
      },
      "design": null,
      "created_at": "2026-10-20T12:30:00Z",
      "updated_at": "2026-10-21T09:00:00Z",
      "object": "template",
      "variable_names": [
        "order_id",
        "name"
      ]
    }
  ]
}
```

---

# Publish a template — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/publish-template/

`POST /v1/templates/{id}/publish`

Make the current draft the version sends use. Until a template is published, sending with it fails.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Template id or alias.

### Errors

- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): Unknown template.

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/welcome/publish' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "template",
  "id": "019a1f50-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
  "name": "Welcome",
  "alias": "welcome",
  "subject": "Welcome, {{first_name}}",
  "html": "<p>Hi {{first_name}}</p>",
  "text": "",
  "from": "",
  "design": null,
  "status": "published",
  "has_unpublished_changes": false,
  "published_at": "2026-10-22T15:10:00Z",
  "published": {
    "subject": "Welcome, {{first_name}}",
    "html": "<p>Hi {{first_name}}</p>",
    "text": "",
    "from": "",
    "design": null
  },
  "variable_names": [
    "first_name"
  ]
}
```

---

# Render unsaved source — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/render-source/

`POST /v1/templates/render`

Validate and preview unsaved template source.

Requires a full-access key.

### Body parameters

- `subject` (string)
- `html` (string)
- `text` (string)
- `variables` (object): Default `{}`.

### Errors

- `restricted_api_key` (HTTP 403)
- `template_render_error` (HTTP 422): <field>: <syntax error>

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/render' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "subject": "Hi {{first_name}}",
  "html": "<p>Hello {{first_name}}</p>",
  "variables": {
    "first_name": "Ann"
  }
}'
```

**Response `200 OK`**

```json
{
  "subject": "Hello Jane",
  "html": "<p>Welcome, Jane!</p>",
  "text": "",
  "missing_variables": [
    "plan"
  ],
  "variable_names": [
    "name",
    "plan"
  ],
  "design": null
}
```

---

# Render a template — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/render-template/

`POST /v1/templates/{id}/render`

Preview a stored template with given variables (defaults to its sample variables).

Requires a full-access key.

Missing variables do not fail the preview; they are listed in missing_variables.

### Path parameters

- `id` (string, required): Template id or alias

### Body parameters

- `variables` (object): Variables to render with; when omitted the template's stored sample variables are used.

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): template not found
- `template_render_error` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/welcome/render' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "variables": {
    "first_name": "Ann"
  }
}'
```

**Response `200 OK`**

```json
{
  "subject": "Your receipt for A-1042",
  "html": "<p>Hi Jane, thanks for order A-1042.</p>",
  "text": "Hi Jane, thanks for order A-1042.",
  "missing_variables": [],
  "variable_names": [
    "order_id",
    "name"
  ],
  "design": null
}
```

---

# Restore a version — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/restore-template-version/

`POST /v1/templates/{id}/versions/{vid}/restore`

Copy a version back into the draft. Publishing stays a separate step.

Requires a full-access live key; test keys get 403 test_key_restricted.

Restores name, subject, html, text, from and design; alias and sample variables stay. The restore is recorded as a version of kind `restored`. Sends keep using the published version until you [publish](https://www.zapsmtp.xyz/docs/templates/publish-template/).

### Path parameters

- `id` (string, required): Template id or alias.
- `vid` (string (UUID), required): Version id from the list.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): template not found | version not found

```bash
curl -X POST 'https://zapsmtp.xyz/v1/templates/welcome/versions/019a1f58-2b3c-7d4e-8f50-6a7b8c9d0e1f/restore' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f50-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
  "name": "Welcome",
  "alias": "welcome",
  "subject": "Welcome, {{first_name}}",
  "html": "<p>Hi {{first_name}}, welcome to Acme.</p>",
  "text": "Hi {{first_name}}, welcome to Acme.",
  "from": "Acme <hello@acme.com>",
  "variables": {
    "first_name": "Ann"
  },
  "design": null,
  "created_at": "2026-10-20T12:30:00Z",
  "updated_at": "2026-10-22T15:20:00Z",
  "published": {
    "subject": "Welcome, {{first_name}}",
    "html": "<p>Hi {{first_name}}</p>",
    "text": "",
    "from": "",
    "design": null
  },
  "published_at": "2026-10-22T15:10:00Z",
  "object": "template",
  "status": "published",
  "has_unpublished_changes": true,
  "variable_names": [
    "first_name"
  ]
}
```

---

# Update a template — Templates API

Source: https://www.zapsmtp.xyz/docs/templates/update-template/

`PATCH /v1/templates/{id}`

Update a template (partial).

Requires a full-access live key; test keys get 403 test_key_restricted.

Fields left out keep their value; the same validation as create applies to the result.

Every save (and publish) is kept in the version history: see [List versions](https://www.zapsmtp.xyz/docs/templates/list-template-versions/).

`has_unpublished_changes` is also `true` when only the draft’s `variable_schema` differs from the published one.

### Path parameters

- `id` (string, required): Template id or alias

### Body parameters

- `name` (string): Limits: trimmed, 1-200 characters → 422 missing_required_field "name is required (max 200 chars)"
- `alias` (string): Stable handle; `""` removes it usable instead of the id (template.id in sends, /templates/{alias}). Limits: ^[a-z0-9][a-z0-9_-]{0,62}$ → 422 invalid_parameter; duplicate → 409 conflict
- `subject` (string): Mustache source.
- `html` (string): Mustache source; {{var}} is HTML-escaped, {{{var}}} raw.
- `text` (string)
- `from` (string): Default From used when a send omits from.
- `variables` (object): Sample variables used by previews; replaces the whole object. Never used for sending; a variable first found in the source takes its sample as `example`.
- `variable_schema` (object[]): Declares the template’s variables (see [Variable schema](https://www.zapsmtp.xyz/docs/templating/#schema)). Replaces the declared list when given. On every save, names the source uses that the list lacks are added (their sample value as example): a section {{#x}} as optional `any`, a dotted {{x.y}} as a required `object`, any other name as a required `any`, never stricter than sends were before, and declared names the source no longer uses are kept with `unused: true`. Limits: at most 200 entries, no duplicates, defaults and examples of their type → 422 invalid_parameter "variable_schema: <reason>"
  - `name` (string, required): Variable name: letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved.
  - `type` (string, required): What a send must pass. One of `string`, `number`, `boolean`, `url`, `date`, `list`, `object`, `any`.
  - `required` (boolean): A send without a value (or with `null`) and without a default is refused with `template_variables_missing`. Default `false`.
  - `default` (any): Used when a send gives no value; must be of `type`.
  - `example` (any): Used by previews; must be of `type`.
  - `description` (string): For your team; at most 500 bytes.
- `design` (object | null): The visual editor’s document (a JSON object with a numeric `version`), stored with the template. `null` makes it a code template. Changing `html` without sending `design` drops the design (it no longer describes the HTML). Limits: max 1 MB → 422 invalid_parameter "design is larger than 1 MB"; not an object with a numeric version → 422 invalid_parameter
- `publish` (boolean): Publish the result in the same call. Without it the template stays a draft and is not used for sending until [published](https://www.zapsmtp.xyz/docs/templates/publish-template/). Default `false`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): template not found
- `conflict` (HTTP 409): a template with this alias already exists
- `payload_too_large` (HTTP 413): request body too large (over 4 MB)
- `missing_required_field` (HTTP 422)
- `invalid_parameter` (HTTP 422)
- `template_render_error` (HTTP 422): template syntax error: "<field>: <error>"
- `template_render_error` (HTTP 422): a tag that is not a variable name, e.g. {{first name}}, {{#each items}}, {{> footer}}: "html: line L, column C: {{…}} is not a variable name: letters, digits, _ and - (no spaces), parts joined with dots"

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/templates/welcome' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "subject": "Welcome aboard, {{first_name}}"
}'
```

Response `200`.

---

# Delete a global variable — Variables API

Source: https://www.zapsmtp.xyz/docs/variables/delete-global-variable/

`DELETE /v1/variables/global/{key}`

Delete a global variable. Sends with a template that still uses it then fail with 422 template_render_error until it is set again.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `key` (string, required): The key, used as `{{global.key}}`: letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved. Limits: other keys → 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): global variable not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/variables/global/company_name' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "variable",
  "name": "global.company_name",
  "deleted": true
}
```

---

# List variables — Variables API

Source: https://www.zapsmtp.xyz/docs/variables/list-variables/

`GET /v1/variables`

The variable catalogue: every variable the account’s templates can use, with where each is used. System variables first, then global ones, then template variables, each sorted by name.

Requires a full-access key.

`kind` is `system` (filled by ZapSMTP), `global` (set for the account, written `{{global.key}}`) or `template` (a template’s own).

A global variable that templates use but that has no value yet is listed without `value`; sends with those templates fail until you set it.

A template variable lists in `types` every type its templates declare, and per template its `type`, `required`, `default` and `unused` (declared, but the source no longer names it).

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/variables' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "variable",
      "name": "zap:unsubscribe_url",
      "kind": "system",
      "type": "url",
      "description": "The recipient's one-click unsubscribe link (also adds List-Unsubscribe).",
      "templates": []
    },
    {
      "object": "variable",
      "name": "global.company_name",
      "kind": "global",
      "type": "string",
      "key": "company_name",
      "value": "Acme Inc.",
      "description": "Legal name for footers",
      "updated_at": "2026-10-25T14:20:00Z",
      "templates": [
        {
          "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
          "name": "Receipt"
        }
      ]
    },
    {
      "object": "variable",
      "name": "global.support_url",
      "kind": "global",
      "type": "string",
      "key": "support_url",
      "templates": [
        {
          "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
          "name": "Receipt"
        }
      ]
    },
    {
      "object": "variable",
      "name": "coupon",
      "kind": "template",
      "types": [
        "object"
      ],
      "templates": [
        {
          "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
          "name": "Receipt",
          "type": "object"
        }
      ]
    },
    {
      "object": "variable",
      "name": "order_id",
      "kind": "template",
      "types": [
        "string"
      ],
      "description": "Order number shown to the customer",
      "templates": [
        {
          "id": "019a1f23-7f80-7192-8b3c-4d5e6f7a8b9c",
          "name": "Receipt",
          "type": "string",
          "required": true
        }
      ]
    }
  ]
}
```

---

# Set a global variable — Variables API

Source: https://www.zapsmtp.xyz/docs/variables/put-global-variable/

`PUT /v1/variables/global/{key}`

Create or replace a global variable. Every template that uses it renders the new value from the next send on.

Requires a full-access live key; test keys get 403 test_key_restricted.

The response does not list the templates using the variable; `GET /variables` does.

### Path parameters

- `key` (string, required): The key, used as `{{global.key}}`: letters, digits, `_` and `-`, starting with a letter or `_`, up to 64; `global` is reserved. Limits: other keys → 422 invalid_parameter

### Body parameters

- `value` (string): The value, always a string. Limits: at most 10 KB → 422 invalid_parameter Default `""`.
- `description` (string): What it is for. Limits: at most 500 bytes → 422 invalid_parameter

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422): bad key, value over 10 KB or description over 500 bytes

```bash
curl -X PUT 'https://zapsmtp.xyz/v1/variables/global/company_name' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "value": "Acme Inc.",
  "description": "Legal name for footers"
}'
```

**Response `200 OK`**

```json
{
  "object": "variable",
  "name": "global.company_name",
  "kind": "global",
  "type": "string",
  "key": "company_name",
  "value": "Acme Inc.",
  "description": "Legal name for footers",
  "updated_at": "2026-10-27T10:30:00Z",
  "templates": []
}
```

---

# Create a webhook — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/create-webhook/

`POST /v1/webhooks`

Create a webhook endpoint; the signing secret is returned.

Requires a full-access live key; test keys get 403 test_key_restricted.

The secret is also readable later via GET /webhooks/{id}.

To send clicks of one button to this endpoint: `{"events": ["email.clicked"], "filter": {"actions": ["confirm_order"]}}`. Endpoints always return `filter`, with an empty list when there is none.

### Body parameters

- `url` (string, required): Absolute https:// URL. Limits: 422 invalid_parameter "url must be an absolute https:// URL"
- `events` (string[]): Limits: unknown type → 422 invalid_parameter "unknown event type <x>; allowed: ..." One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `all event types`.
- `include_content` (boolean): `email.received` carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (`truncated: true`). Default `false`.
- `batch` (boolean): Send events up to 100 per request (or every second) as a JSON array, signed as one body; `Zap-Event-Id` is the batch id, each event keeps its own `id`. `email.received` with the full message still arrives alone. Default `false`.
- `filter` (object): Narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/); other event types are not affected. Empty or absent: every click. Default `{"actions": []}`.
  - `actions` (string[]): Action names (lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters). The endpoint then receives `email.clicked` only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com/hooks/zapsmtp",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ]
}'
```

**Response `201 Created`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-21T15:40:00Z",
  "include_content": false,
  "batch": false,
  "filter": {
    "actions": []
  }
}
```

---

# Delete a webhook — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/delete-webhook/

`DELETE /v1/webhooks/{id}`

Delete a webhook endpoint.

Requires a full-access live key; test keys get 403 test_key_restricted.

### Path parameters

- `id` (string, required): Webhook id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): webhook not found

```bash
curl -X DELETE 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

Response `204` with an empty body.

---

# Retrieve an event — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/get-webhook-event/

`GET /v1/webhooks/{id}/events/{event}`

One event with its payload and every delivery attempt, oldest first.

Requires a full-access key.

### Path parameters

- `id` (string, required): Webhook id.
- `event` (string, required): Event id (`Zap-Event-Id`).

### Errors

- `not_found` (HTTP 404): Unknown webhook, or the event is not among the last 100 attempts.

```bash
curl 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10/events/evt_5f0c2a9b7d1e4c3a8b6f2e10' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "webhook_event",
  "id": "evt_5f0c2a9b7d1e4c3a8b6f2e10",
  "type": "email.delivered",
  "status": "delivered",
  "attempts": 2,
  "last_status_code": 200,
  "first_attempt_at": "2026-10-22T10:00:00Z",
  "last_attempt_at": "2026-10-22T10:05:01Z",
  "payload": {
    "id": "evt_5f0c2a9b7d1e4c3a8b6f2e10",
    "type": "email.delivered",
    "created_at": "2026-10-22T09:59:59Z",
    "data": {
      "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
      "to": "jane@example.org"
    }
  },
  "attempt_list": [
    {
      "attempt": 1,
      "status_code": 503,
      "error": "HTTP 503",
      "duration_ms": 120,
      "at": "2026-10-22T10:00:00Z"
    },
    {
      "attempt": 2,
      "status_code": 200,
      "duration_ms": 85,
      "at": "2026-10-22T10:05:01Z"
    }
  ]
}
```

---

# Retrieve a webhook — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/get-webhook/

`GET /v1/webhooks/{id}`

Retrieve a webhook endpoint including its signing secret.

Requires a full-access key.

### Path parameters

- `id` (string, required): Webhook id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): webhook not found

```bash
curl 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp",
  "secret": "whsec_Q7v2Lk9Xp4Rb1Tz8Mw3Nc6Hy0Fd5Gs2J",
  "previous_secret_expires_at": "2026-10-22T15:45:00Z",
  "events": [
    "email.delivered",
    "email.bounced",
    "email.complained"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-20T12:00:00Z",
  "filter": {
    "actions": []
  }
}
```

---

# List events — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/list-webhook-events/

`GET /v1/webhooks/{id}/events`

Events sent to this endpoint, newest first, each with its outcome and number of attempts (from the endpoint’s last 100 delivery attempts).

Requires a full-access key.

### Path parameters

- `id` (string, required): Webhook id.

### Errors

- `not_found` (HTTP 404): Unknown webhook.

```bash
curl 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10/events' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook_event",
      "id": "evt_5f0c2a9b7d1e4c3a8b6f2e10",
      "type": "email.delivered",
      "status": "delivered",
      "attempts": 2,
      "last_status_code": 200,
      "first_attempt_at": "2026-10-22T10:00:00Z",
      "last_attempt_at": "2026-10-22T10:05:01Z"
    }
  ]
}
```

---

# List webhooks — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/list-webhooks/

`GET /v1/webhooks`

List webhook endpoints (newest first); secrets are omitted.

Requires a full-access key.

`previous_secret_expires_at` appears while a rotated secret still signs deliveries.

### Errors

- `restricted_api_key` (HTTP 403)

```bash
curl 'https://zapsmtp.xyz/v1/webhooks' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
      "url": "https://acme.com/hooks/zapsmtp",
      "events": [
        "email.delivered",
        "email.bounced",
        "email.complained"
      ],
      "enabled": true,
      "disabled_reason": null,
      "created_at": "2026-10-20T12:00:00Z"
    }
  ]
}
```

---

# Replay an event — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/replay-event/

`POST /v1/webhooks/{id}/deliveries/{event}/replay`

Re-send a past event (from the last 100 deliveries) to the endpoint now.

Requires a full-access live key; test keys get 403 test_key_restricted.

Same body and Zap-Event-Id as the original, signed with the current secret(s) and a new timestamp. The replay is sent synchronously and not retried. Events whose body was over 64 KB cannot be replayed.

### Path parameters

- `id` (string, required): Webhook id
- `event` (string, required): Event id (evt_...) from GET /webhooks/{id}/deliveries

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): webhook not found | event not found in the last 100 deliveries of this webhook

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10/deliveries/evt_5f0c2a9b7d1e4c3a8b6f2e10/replay' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "ok": true,
  "delivery": {
    "event_id": "evt_4f1c9a2b7e3d5c8a1b6f0e2d",
    "event_type": "email.bounced",
    "attempt": 3,
    "status_code": 200,
    "duration_ms": 98,
    "at": "2026-10-21T16:00:00.512Z",
    "body": {
      "id": "evt_4f1c9a2b7e3d5c8a1b6f0e2d",
      "type": "email.bounced",
      "created_at": "2026-10-21T15:04:12.381Z",
      "data": {
        "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
        "to": "jane@example.org"
      }
    }
  }
}
```

---

# Rotate the signing secret — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/rotate-secret/

`POST /v1/webhooks/{id}/rotate-secret`

Generate a new signing secret; the old one stays valid for 24 hours.

Requires a full-access live key; test keys get 403 test_key_restricted.

During the grace period Zap-Signature carries two v1= entries (new secret first). Rotating again replaces the previous secret.

### Path parameters

- `id` (string, required): Webhook id

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): webhook not found

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10/rotate-secret' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "webhook",
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "secret": "whsec_R2m8Kx5Vq1Lb7Tn4Zw9Pc3Hj6Fd0Gs8Y",
  "previous_secret_expires_at": "2026-10-22T15:45:00Z"
}
```

---

# Send a test event — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/test-webhook/

`POST /v1/webhooks/{id}/test`

Send a signed sample event to the endpoint now and report the result.

Requires a full-access live key; test keys get 403 test_key_restricted.

Test events are not retried. delivery.error is present when the attempt failed (e.g. "HTTP 500"); status_code is 0 on network errors. The test attempt is recorded in the delivery log.

### Path parameters

- `id` (string, required): Webhook id

### Body parameters

- `type` (string): Limits: 422 invalid_parameter "unknown event type" One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`. Default `email.delivered`.

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): webhook not found
- `invalid_parameter` (HTTP 422)

```bash
curl -X POST 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10/test' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "email.delivered"
}'
```

**Response `200 OK`**

```json
{
  "ok": true,
  "delivery": {
    "event_id": "evt_test_9Gk2Lq7Xv1Rb4Tz8",
    "event_type": "email.delivered",
    "attempt": 1,
    "status_code": 200,
    "duration_ms": 143,
    "at": "2026-10-21T15:50:00.123Z",
    "body": {
      "id": "evt_test_9Gk2Lq7Xv1Rb4Tz8",
      "type": "email.delivered",
      "created_at": "2026-10-21T15:50:00.120Z",
      "data": {
        "email_id": "00000000-0000-0000-0000-000000000000",
        "from": "Test <test@example.com>",
        "to": "recipient@example.com",
        "subject": "ZapSMTP webhook test",
        "response": {
          "code": 250,
          "message": "OK (test event)"
        }
      }
    }
  },
  "payload": {
    "id": "evt_test_9Gk2Lq7Xv1Rb4Tz8",
    "type": "email.delivered",
    "created_at": "2026-10-21T15:50:00.120Z",
    "data": {
      "email_id": "00000000-0000-0000-0000-000000000000",
      "from": "Test <test@example.com>",
      "to": "recipient@example.com",
      "subject": "ZapSMTP webhook test",
      "response": {
        "code": 250,
        "message": "OK (test event)"
      }
    }
  }
}
```

---

# Update a webhook — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/update-webhook/

`PATCH /v1/webhooks/{id}`

Update a webhook's URL, events, click-action filter or enabled state.

Requires a full-access live key; test keys get 403 test_key_restricted.

The response's disabled_reason reflects the value before the update (the store clears it on re-enable but the returned object is not reloaded).

### Path parameters

- `id` (string, required): Webhook id

### Body parameters

- `url` (string): Limits: absolute https:// URL
- `events` (string[]): Limits: [] → 422 "select at least one event"; unknown type → 422 "unknown event type <x>" One of `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.opened`, `email.clicked`, `email.suppressed`, `email.received`, `thread.created`, `thread.replied`, `email.replied`.
- `enabled` (boolean): Re-enabling clears disabled_reason. Disabling drops pending deliveries.
- `include_content` (boolean): `email.received` carries the message: text, html, headers, and download links (valid 24 hours) for the attachments and the raw .eml; text and html are cut at 1 MB in total (`truncated: true`). Default `false`.
- `batch` (boolean): Send events up to 100 per request (or every second) as a JSON array, signed as one body; `Zap-Event-Id` is the batch id, each event keeps its own `id`. `email.received` with the full message still arrives alone. Default `false`.
- `filter` (object): Narrows `email.clicked` to some [click actions](https://www.zapsmtp.xyz/docs/click-actions/); other event types are not affected. Empty or absent: every click. Replaces the whole filter; `{"actions": []}` removes it.
  - `actions` (string[]): Action names (lowercase letters, digits, `_`, `.` and `-`, starting with a letter or digit, up to 64 characters). The endpoint then receives `email.clicked` only for links with one of these actions. Limits: more than 50 → 422 invalid_parameter "filter.actions: at most 50"; a bad name → 422 invalid_parameter "filter.actions: <name> is not an action name"

### Errors

- `restricted_api_key` (HTTP 403)
- `test_key_restricted` (HTTP 403): test-mode keys can send test email and read, not change the account: use a live key
- `not_found` (HTTP 404): webhook not found
- `invalid_parameter` (HTTP 422)

```bash
curl -X PATCH 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10' \
  -H "Authorization: Bearer $ZAP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true
}'
```

**Response `200 OK`**

```json
{
  "id": "019a1f22-6e7f-7091-8a2b-3c4d5e6f7a8b",
  "url": "https://acme.com/hooks/zapsmtp-v2",
  "events": [
    "email.delivered"
  ],
  "enabled": true,
  "disabled_reason": null,
  "created_at": "2026-10-20T12:00:00Z",
  "filter": {
    "actions": []
  }
}
```

---

# List delivery attempts — Webhooks API

Source: https://www.zapsmtp.xyz/docs/webhooks/webhook-deliveries/

`GET /v1/webhooks/{id}/deliveries`

List the last 100 delivery attempts of a webhook (newest first).

Requires a full-access key.

`attempt` starts at 1. `body` is the exact payload sent (omitted above 64 KB); `error` is omitted on success.

### Path parameters

- `id` (string, required): Webhook id

### Errors

- `restricted_api_key` (HTTP 403)
- `not_found` (HTTP 404): webhook not found

```bash
curl 'https://zapsmtp.xyz/v1/webhooks/019a1c55-0d6e-7f21-8b3a-5e9d4c7b2a10/deliveries' \
  -H "Authorization: Bearer $ZAP_API_KEY"
```

**Response `200 OK`**

```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "event_id": "evt_4f1c9a2b7e3d5c8a1b6f0e2d",
      "event_type": "email.bounced",
      "attempt": 2,
      "status_code": 503,
      "error": "HTTP 503",
      "duration_ms": 412,
      "at": "2026-10-21T15:09:17.004Z",
      "body": {
        "id": "evt_4f1c9a2b7e3d5c8a1b6f0e2d",
        "type": "email.bounced",
        "created_at": "2026-10-21T15:04:12.381Z",
        "data": {
          "email_id": "019a1f2e-7c3b-7d41-9a52-0c4b8e6f1a23",
          "to": "jane@example.org"
        }
      }
    }
  ]
}
```