# SNDR documentation

> SNDR is an email API for developers: verify a domain, send transactional email with one HTTPS request, and receive signed delivery webhooks. Base URL: https://api.sndr.sh/v1. Auth: `Authorization: Bearer <API key>`.

---

# Introduction

> SNDR is an email API for developers. Verify a domain, send with one request, and track every message.

Source: https://sndr.sh/docs

- [Quickstart](https://sndr.sh/docs/getting-started): Send your first email in a few minutes.
- [JavaScript SDK](https://sndr.sh/docs/quickstart): Install `@rkiza/sndr` and send from any runtime.
- [Send email](https://sndr.sh/docs/sending): Fields, limits, templates and attachments.
- [API reference](https://sndr.sh/docs/api-reference): Every endpoint with request and response examples.

## Build with AI

The docs are published as Markdown for ChatGPT, Claude, Cursor and other AI tools. Open them in a chat, or point your coding agent at `llms-full.txt`.

- [Ask ChatGPT](https://chatgpt.com/?hints=search&q=Read%20https%3A%2F%2Fsndr.sh%2Fllms-full.txt%20so%20I%20can%20ask%20questions%20about%20the%20SNDR%20email%20API.): Open a chat with the full SNDR docs loaded.
- [Ask Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fsndr.sh%2Fllms-full.txt%20so%20I%20can%20ask%20questions%20about%20the%20SNDR%20email%20API.): Open a chat with the full SNDR docs loaded.
- [llms-full.txt](https://sndr.sh/llms-full.txt): All docs in one Markdown file for agents.
- [Use with AI](https://sndr.sh/docs/ai): Markdown URLs and a ready-made agent prompt.

## More

- [Domains](https://sndr.sh/docs/domains): Set up SPF, DKIM and DMARC.
- [Webhooks](https://sndr.sh/docs/webhooks): Delivery and bounce events, signed.
- [Errors](https://sndr.sh/docs/errors): Every error code and what to do.
- [Partner API](https://sndr.sh/docs/cranl): Act for SNDR users with OAuth 2.0.

---

# Quickstart

> Send your first email with SNDR in a few minutes.

Source: https://sndr.sh/docs/getting-started

You need a SNDR account, a domain whose DNS you can edit, and an API key.

### 1. Create an account

Sign up at [app.sndr.sh](https://app.sndr.sh/register). The free plan includes 3,000 emails a month, no card needed.

### 2. Add and verify a domain

In **Domains**, add a subdomain such as `mail.acme.com` and copy the DNS records SNDR shows you into your DNS provider. See [Domains](https://sndr.sh/docs/domains).

### 3. Create an API key

In **API keys**, create a key with the `send` scope. It is shown once, so keep it in an environment variable:

![The Create API key dialog with a name, the Live environment, and the send and read scopes selected.](https://sndr.sh/docs/images/create-api-key.webp)

```bash
export SNDR_API_KEY="sndr_live_..."
```

### 4. Send an email

cURL:

```bash
curl -X POST https://api.sndr.sh/v1/send \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.acme.com>",
    "to": ["customer@example.com"],
    "subject": "Hello from SNDR",
    "html": "<p>It works.</p>"
  }'
```

Node.js:

```js
import { Sndr } from '@rkiza/sndr';

const sndr = new Sndr(process.env.SNDR_API_KEY);

const email = await sndr.emails.send({
  from: 'Acme <hello@mail.acme.com>',
  to: 'customer@example.com',
  subject: 'Hello from SNDR',
  html: '<p>It works.</p>',
});

console.log(email.id); // eml_...
```

Python:

```python
import os
import requests

res = requests.post(
    "https://api.sndr.sh/v1/send",
    headers={"Authorization": f"Bearer {os.environ['SNDR_API_KEY']}"},
    json={
        "from": "Acme <hello@mail.acme.com>",
        "to": ["customer@example.com"],
        "subject": "Hello from SNDR",
        "html": "<p>It works.</p>",
    },
)
res.raise_for_status()
print(res.json()["id"])
```

Go:

```go
body := strings.NewReader(`{
  "from": "Acme <hello@mail.acme.com>",
  "to": ["customer@example.com"],
  "subject": "Hello from SNDR",
  "html": "<p>It works.</p>"
}`)

req, _ := http.NewRequest("POST", "https://api.sndr.sh/v1/send", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SNDR_API_KEY"))
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
```

### 5. Check the result

You get `202 Accepted` with the email `id` and `status: "queued"`. Follow it in **Emails** in the dashboard, or get notified with [webhooks](https://sndr.sh/docs/webhooks).

## Next steps

- [Send email](https://sndr.sh/docs/sending): Every field, limit and option of a send.
- [Webhooks](https://sndr.sh/docs/webhooks): Get delivery and bounce events.
- [API reference](https://sndr.sh/docs/api-reference): All endpoints with examples.
- [Use with AI](https://sndr.sh/docs/ai): Give ChatGPT, Claude or Cursor the docs.

---

# JavaScript SDK

> Send from Node.js, Bun, Deno or edge runtimes with the official SDK.

Source: https://sndr.sh/docs/quickstart

## Install

npm:

```bash
npm install @rkiza/sndr
```

pnpm:

```bash
pnpm add @rkiza/sndr
```

bun:

```bash
bun add @rkiza/sndr
```

Works on Node 18+, Bun, Deno, Cloudflare Workers and Vercel Edge. It uses the platform `fetch`, with no native dependencies.

## Send an email

send.ts:

```js
import { Sndr } from '@rkiza/sndr';

const sndr = new Sndr(process.env.SNDR_API_KEY);

const email = await sndr.emails.send({
  from: 'Acme <hello@mail.acme.com>',
  to: 'customer@example.com',
  subject: 'Hello from SNDR',
  html: '<p>It works.</p>',
});

console.log(email.id); // eml_...
```

`to`, `cc` and `bcc` accept one address or an array. The SDK adds an `Idempotency-Key` to every send, so its automatic retries are safe.

## Options

- `apiKey` (string, required): Your API key. Pass it as the only argument, or inside an options object.
- `baseUrl` (string): API host. Defaults to `https://api.sndr.sh`.
- `retries` (object | false): Retries on network errors, `429` and `5xx`. Default: 3 attempts. `false` turns them off.

## Handle errors

```js
import { Sndr, SndrError } from '@rkiza/sndr';

try {
  await sndr.emails.send({ /* ... */ });
} catch (err) {
  if (err instanceof SndrError) {
    console.error(err.code, err.status, err.requestId);
  }
}
```

`code` matches the [error codes](https://sndr.sh/docs/errors). Include `requestId` when you contact support.

## Other resources

The client also exposes `sndr.domains`, `sndr.templates`, `sndr.webhooks`, `sndr.apiKeys` and `sndr.analytics`. To verify webhooks, use `verifyWebhookSignature` — see [Webhooks](https://sndr.sh/docs/webhooks).

---

# Use with AI

> Give ChatGPT, Claude, Cursor or any agent the SNDR docs.

Source: https://sndr.sh/docs/ai

Every docs page is also available as plain Markdown, so AI tools can read it without scraping HTML.

| URL | What it is |
| --- | --- |
| [/llms.txt](https://sndr.sh/llms.txt) | Index of all pages with a one-line summary each. |
| [/llms-full.txt](https://sndr.sh/llms-full.txt) | Every page in one Markdown file. Best for a full integration. |
| `<page>.md` | Any page as Markdown, e.g. [/docs/sending.md](https://sndr.sh/docs/sending.md). |
| [/docs/cranl/openapi.json](https://sndr.sh/docs/cranl/openapi.json) | OpenAPI spec of the Partner API, for code generators. |

## On any page

Use the **Copy page** menu at the top of a page to copy it as Markdown, or open it in ChatGPT, Claude or Perplexity with the page already loaded.

## Prompt for coding agents

Paste this into Cursor, Claude Code, Copilot or ChatGPT:

```text
Read https://sndr.sh/llms-full.txt, then add email sending to this project
with the SNDR API. Use the @rkiza/sndr SDK for JavaScript, or plain HTTPS
otherwise. Read the API key from the SNDR_API_KEY environment variable and
never hard-code it.
```

> **Tip:** Never paste a real API key into a chat. Agents only need the variable name.

---

# Send email

> The fields, limits and options of a send request.

Source: https://sndr.sh/docs/sending

Send with `POST /v1/send`. The API answers `202 Accepted` straight away and delivers in the background.

![Your app posts to /v1/send and gets 202 queued. SNDR DKIM-signs and delivers the email; the result (delivered, bounced or failed) goes to your webhook endpoint.](https://sndr.sh/docs/images/send-lifecycle.svg)

cURL:

```bash
curl -X POST https://api.sndr.sh/v1/send \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.acme.com>",
    "to": ["customer@example.com"],
    "subject": "Hello from SNDR",
    "html": "<p>It works.</p>"
  }'
```

Node.js:

```js
import { Sndr } from '@rkiza/sndr';

const sndr = new Sndr(process.env.SNDR_API_KEY);

const email = await sndr.emails.send({
  from: 'Acme <hello@mail.acme.com>',
  to: 'customer@example.com',
  subject: 'Hello from SNDR',
  html: '<p>It works.</p>',
});

console.log(email.id); // eml_...
```

Python:

```python
import os
import requests

res = requests.post(
    "https://api.sndr.sh/v1/send",
    headers={"Authorization": f"Bearer {os.environ['SNDR_API_KEY']}"},
    json={
        "from": "Acme <hello@mail.acme.com>",
        "to": ["customer@example.com"],
        "subject": "Hello from SNDR",
        "html": "<p>It works.</p>",
    },
)
res.raise_for_status()
print(res.json()["id"])
```

Go:

```go
body := strings.NewReader(`{
  "from": "Acme <hello@mail.acme.com>",
  "to": ["customer@example.com"],
  "subject": "Hello from SNDR",
  "html": "<p>It works.</p>"
}`)

req, _ := http.NewRequest("POST", "https://api.sndr.sh/v1/send", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SNDR_API_KEY"))
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
```

## Request fields

- `from` (string, required): The sender: `hello@mail.acme.com` or `Acme <hello@mail.acme.com>`. Its domain must be verified.
- `to` (string[], required): Recipients, 1 to 1,000 addresses. Always an array in the HTTP API.
- `cc` (string[]): Copied recipients, up to 100.
- `bcc` (string[]): Hidden recipients, up to 100.
- `reply_to` (string): Where replies go, if not to `from`.
- `subject` (string, required): One line, up to 998 characters. Optional when the template has a subject.
- `html` (string): HTML body. Send `html`, `text` or both.
- `text` (string): Plain-text body for clients that don’t show HTML.
- `template_id` (string): A saved template. Its subject and bodies fill any field you leave empty.
- `variables` (object): Values for `{{name}}` placeholders in the subject and bodies, e.g. `{"name": "Sara"}`.
- `attachments` (object[]): Files: `{ "filename", "content", "content_type" }`, with `content` base64-encoded.
- `headers` (object): Extra email headers, e.g. `{"X-Campaign": "welcome"}`.

## Limits

| Limit | Value |
| --- | --- |
| Recipients (`to` + `cc` + `bcc`) | 1,000 per request |
| Attachments | 10 files, 10 MiB total after decoding |
| Request body | 16 MiB |
| Subject | 998 characters, one line |

## Retry safely

Add an `Idempotency-Key` header with a unique value, such as your order ID. A retry with the same key returns the first response instead of sending the email again.

```bash
-H "Idempotency-Key: order-1234-receipt"
```

## Suppressed recipients

Addresses on your suppression list (hard bounces, complaints, unsubscribes) are removed before sending. If every `to` address is suppressed, the request fails with `suppressed`.

## Response

202 Accepted:

```json
{
  "id": "eml_01HXKQ8B3N",
  "from": "Acme <hello@mail.acme.com>",
  "to": ["customer@example.com"],
  "subject": "Hello from SNDR",
  "status": "queued",
  "created_at": "2026-01-15T10:30:00Z"
}
```

`status` starts as `queued` and ends as `delivered`, `bounced` or `failed`. Read it with `GET /v1/emails/{id}`.

---

# Domains

> Verify the domains you send from.

Source: https://sndr.sh/docs/domains

You can only send from a verified domain. Verifying proves you own it and lets inbox providers trust your mail.

### 1. Add the domain

In **Domains**, click **Add domain** and enter the domain you’ll send from.

### 2. Add the DNS records

Copy each record’s **Name** into the host field and its **Value** into the content field at your DNS provider.

![The SPF, DKIM and DMARC TXT records SNDR shows for mail.acme.com, each with a Name and a Value to copy.](https://sndr.sh/docs/images/domain-dns-records.webp)

The three required records for `mail.acme.com`. Your values come from the dashboard.

### 3. Verify

Click **Verify**. DNS changes usually show up within minutes, but can take longer at some providers.

> **Tip:** Use a subdomain such as `mail.acme.com`. It keeps your sending reputation separate from your main domain.

## What each record does

| Record | Purpose |
| --- | --- |
| SPF | Lists the servers allowed to send for your domain. |
| DKIM | A public key that lets inboxes check each email’s signature. |
| DMARC | Tells inboxes what to do when SPF or DKIM checks fail. |

> **Warning:** Keep your existing MX records (Google Workspace, Zoho…) — sending doesn’t need them changed. If the domain already has an SPF record, add SNDR’s include to it instead of creating a second one.

Manage domains from code with the [Domains API](https://sndr.sh/docs/api/domains).

---

# Webhooks

> Get signed HTTP notifications when emails are delivered, bounce or fail.

Source: https://sndr.sh/docs/webhooks

Add an endpoint in **Webhooks** (or with `POST /v1/webhooks`) and choose its events. SNDR sends each event as a signed `POST` with a JSON body.

## Events

| Event | Sent when |
| --- | --- |
| email.delivered | The recipient’s mail server accepted the email. |
| email.bounced | The address doesn’t exist (permanent failure). It’s added to your suppression list. |
| email.failed | The email couldn’t be sent, for example a rejection or signing problem. |
| email.unsubscribed | A recipient used the unsubscribe link. The address is added to your suppression list. |

Payload:

```json
{
  "id": "evt_3f9a1c2b7d4e",
  "type": "email.delivered",
  "created_at": "2026-01-15T10:30:04Z",
  "data": {
    "email_id": "eml_01HXKQ8B3N",
    "to": ["customer@example.com"]
  }
}
```

Deliveries are retried on failure, so the same event can arrive twice. Use `id` to process each event once.

## Verify the signature

Each request has an `X-Sndr-Signature` header: `t=<unix time>,v1=<hex HMAC-SHA256>`. The HMAC is computed over `t`, a dot, and the raw body, with your endpoint’s secret. Always check it before trusting the payload.

SDK:

```js
import { verifyWebhookSignature } from '@rkiza/sndr';

// rawBody: the exact request body, before JSON.parse
const valid = verifyWebhookSignature(
  rawBody,
  request.headers.get('x-sndr-signature') ?? '',
  process.env.SNDR_WEBHOOK_SECRET,
);
if (!valid) return new Response('Invalid signature', { status: 401 });
```

Node.js:

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

// header: "t=1736937004,v1=5f2b..." (v1s appears while a new secret is staged)
function verify(rawBody, header, secret) {
  const parts = header.split(',').map((p) => p.trim().split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(t + '.' + rawBody).digest();
  return parts.some(([k, sig]) => k.startsWith('v1') && /^[0-9a-f]{64}$/i.test(sig ?? '') &&
    timingSafeEqual(expected, Buffer.from(sig, 'hex')));
}
```

> **Note:** Reject requests whose `t` is more than 5 minutes old to stop replays.

## The secret

The full secret is shown once, when you create the endpoint (`secret` in the API response). Lists only show `secret_prefix`, which can’t be used to verify.

## Rotate the secret

### 1. Stage a new secret

Open the endpoint’s **Signing keys** and choose **Generate replacement secret**. Requests are now signed with both secrets (`v1` and `v1s`).

### 2. Accept both

Update your receiver to accept either secret.

### 3. Promote

Choose **Make primary**. The old secret stops signing new deliveries.

---

# API overview

> Base URL, authentication, scopes and conventions of the SNDR API.

Source: https://sndr.sh/docs/api-reference

The SNDR API is plain HTTPS and JSON. Every request goes to the same base URL:

```text
https://api.sndr.sh/v1
```

## Authentication

Send your API key as a Bearer token. Keys look like `sndr_live_...` and are created in **API keys** in the dashboard.

```bash
curl https://api.sndr.sh/v1/emails \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

> **Warning:** Keep keys on your server. Never put them in browser or mobile code.

## Scopes

| Scope | Allows |
| --- | --- |
| `read` | All `GET` endpoints. |
| `send` | Sending and every create, update or delete. |

API keys can list keys but not create or delete them. That is done in the dashboard only.

## Pagination

Paginated lists take `limit` (default 50, max 200) and `cursor`. Pass the `next_cursor` from one page to get the next, while `has_more` is `true`.

```json
{
  "data": [ ... ],
  "next_cursor": "eyJ0cyI6...",
  "has_more": true,
  "count": 50,
  "limit": 50
}
```

## Errors

Failed requests return an HTTP error status and an `error` object. See [Errors](https://sndr.sh/docs/errors) for every code.

## Endpoints

- [Emails](https://sndr.sh/docs/api/emails): Send and look up emails.
- [Domains](https://sndr.sh/docs/api/domains): Add and verify sending domains.
- [Templates](https://sndr.sh/docs/api/templates): Reusable subjects and bodies.
- [Contacts](https://sndr.sh/docs/api/contacts): Your audience for broadcasts.
- [Webhooks](https://sndr.sh/docs/api/webhooks): Event endpoints and signing keys.
- [Analytics](https://sndr.sh/docs/api/analytics): Sends, deliveries, bounces and complaints.

---

# Errors

> What each error code means and how to fix it.

Source: https://sndr.sh/docs/errors

Errors use standard HTTP status codes and the same JSON shape:

```json
{
  "error": {
    "code": "domain_not_verified",
    "message": "Domain mail.acme.com is not verified.",
    "request_id": "req_8a91lk2"
  }
}
```

- `code` (string, required): Stable, machine-readable reason. Branch on this, not on `message`.
- `message` (string, required): Human-readable explanation.
- `request_id` (string): Include it when you contact support.
- `field` (string): The request field that caused the error, when there is one.
- `fields` (object): Per-field messages for `validation_failed`.
- `retry_after_seconds` (integer): How long to wait before retrying a `429`.

## Codes

| Code | HTTP | Meaning |
| --- | --- | --- |
| invalid_request | 400 | The body or a parameter is invalid. `message` says what to fix. |
| suppressed | 400 | Every `to` address is on your suppression list. |
| unauthenticated | 401 | The API key is missing, wrong or revoked. |
| quota_exceeded | 402 | Your monthly email quota is used up. Upgrade or wait for the reset. |
| plan_limit_reached | 402 | Your plan’s limit for this resource (domains, webhooks…) is reached. |
| insufficient_scope | 403 | The API key lacks the scope this endpoint needs (`read` or `send`). |
| domain_not_linked | 403 | The `from` domain hasn’t been added to this workspace. |
| domain_not_verified | 403 | The `from` domain is added but not verified yet. |
| quarantine_active | 403 | Sending is paused for this workspace. Contact support. |
| forbidden | 403 | This key or workspace isn’t allowed to do that. |
| not_found | 404 | The resource doesn’t exist in this workspace. |
| conflict | 409 | The resource already exists or changed. |
| payload_too_large | 413 | The request body is over 16 MiB. |
| validation_failed | 422 | One or more fields are invalid. See `fields`. |
| rate_limited | 429 | Too many requests. Retry after `retry_after_seconds`. |
| send_velocity | 429 | You’re sending faster than allowed. Back off and retry. |
| server_error | 500 | Something failed on our side. Retry with backoff. |
| internal | 500 | Same as `server_error`. |
| sends_frozen | 503 | Sending is paused for maintenance. Check the status page and retry. |

> **Tip:** Retry `429` and `5xx` responses with exponential backoff. Don’t retry `4xx` errors until you’ve fixed the request.

---

# Emails

> Send emails and look up their status.

Source: https://sndr.sh/docs/api/emails

- [Send email](https://sndr.sh/docs/api/emails/send-email) `POST /v1/send`: Queue an email for delivery.
- [List emails](https://sndr.sh/docs/api/emails/list-emails) `GET /v1/emails`: List emails sent from your workspace, newest first.
- [Get email](https://sndr.sh/docs/api/emails/get-email) `GET /v1/emails/{id}`: Retrieve one email with its current status.

---

# Send email

> Queue an email for delivery.

Source: https://sndr.sh/docs/api/emails/send-email

`POST https://api.sndr.sh/v1/send`

Queue an email for delivery. Returns 202 Accepted with the queued Email. Send an Idempotency-Key header to make retries safe: a repeat with the same key within 24 hours returns the first response.

Scope: `send`

**Body** (JSON)

- `from` (string, required): Sender, as an address or "Name <address>". Its domain must be added and verified on your workspace.
- `to` (string[], required): Recipient addresses, 1–1000, plain format (no display names). Must be an array, even for one recipient.
- `cc` (string[]): CC addresses, max 100.
- `bcc` (string[]): BCC addresses, max 100. to + cc + bcc together may not exceed 1000.
- `subject` (string): Subject line, single line, max 998 bytes. Required unless the template provides one.
- `html` (string): HTML body. Send html, text or both, unless template_id provides them.
- `text` (string): Plain-text body.
- `reply_to` (string): Reply-To address.
- `template_id` (string): Saved template ID (tpl_...). Its subject, html and text fill any of those fields you leave empty.
- `variables` (object): Values for {{ name }} placeholders in subject, html and text, e.g. {"first_name":"Alex"}. {{ user.name }} reads nested objects; unknown placeholders are left as is.
- `headers` (object): Extra headers as string pairs, e.g. {"X-Entity-Ref-ID":"1234"}. No CR/LF allowed; standard headers such as From, To, Subject, Reply-To or List-Unsubscribe are ignored.
- `tags` (object[]): Objects with string values, e.g. [{"name":"category","value":"welcome"}]. Accepted but not stored or returned yet.
- `attachments` (object[]): Up to 10 files as {filename, content, content_type?}. content is standard base64; content_type defaults to application/octet-stream. Max 10 MiB decoded in total; the whole request max 16 MiB.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/send' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1234-confirmation' \
  -d '{
    "from":      "Acme <noreply@acme.com>",
    "to":        ["customer@example.com"],
    "reply_to":  "support@acme.com",
    "subject":   "Your order #{{ order_id }} is confirmed",
    "html":      "<h1>Thanks, {{ first_name }}!</h1><p>Order #{{ order_id }} is being prepared.</p>",
    "text":      "Thanks, {{ first_name }}! Order #{{ order_id }} is being prepared.",
    "variables": { "first_name": "Alex", "order_id": "1234" }
  }'
```

**Response** (202)

```json
{
  "id":              "em_3f9c1a2b-7d4",
  "organization_id": "org_8d41c7a2-3f6",
  "from":            "\"Acme\" <noreply@acme.com>",
  "to":              ["customer@example.com"],
  "subject":         "Your order #1234 is confirmed",
  "status":          "queued",
  "domain_id":       "dom_a7c2e910-4b1",
  "created_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body failed validation — e.g. to sent as a string, an invalid address, no subject or body, over 1000 recipients, CR/LF in a header field, unknown template_id, or a bad attachment.
- `suppressed` (400): Every to address is on the suppression list. Suppressed cc/bcc addresses are dropped silently.
- `quota_exceeded` (402): The monthly email quota is used up. It resets on the 1st of the month (UTC).
- `insufficient_scope` (403): The API key is missing the send scope.
- `domain_not_linked` (403): The from domain has not been added to your workspace.
- `domain_not_verified` (403): The from domain is added but its DNS records are not verified yet.
- `quarantine_active` (403): Sending is paused for this account. Contact SNDR support.
- `forbidden` (403): A recipient is on a known spam-trap list. Remove it and retry.
- `payload_too_large` (413): The request, or the rendered html + text, is over 16 MiB.
- `send_velocity` (429): Sending too fast for this account. Back off and retry.
- `sends_frozen` (503): Sending is temporarily paused platform-wide. Retry later.

---

# List emails

> List emails sent from your workspace, newest first.

Source: https://sndr.sh/docs/api/emails/list-emails

`GET https://api.sndr.sh/v1/emails`

List emails sent from your workspace, newest first. Cursor-paginated: pass next_cursor back as cursor while has_more is true.

Scope: `read`

**Query parameters**

- `limit` (integer): Page size. Default 50, max 200.
- `cursor` (string): The next_cursor value from the previous page. Omit for the first page.

**Request**

```bash
curl 'https://api.sndr.sh/v1/emails?limit=1' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "em_3f9c1a2b-7d4",
      "organization_id": "org_8d41c7a2-3f6",
      "from":            "\"Acme\" <noreply@acme.com>",
      "to":              ["customer@example.com"],
      "subject":         "Your order #1234 is confirmed",
      "status":          "delivered",
      "domain_id":       "dom_a7c2e910-4b1",
      "created_at":      "2026-06-01T12:00:00Z",
      "delivered_at":    "2026-06-01T12:00:04Z"
    }
  ],
  "next_cursor": "eyJ0cyI6IjIwMjYtMDYtMDFUMTI6MDA6MDBaIiwiaWQiOiJlbV8zZjljMWEyYi03ZDQifQ",
  "has_more":    true,
  "count":       1,
  "limit":       1
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `validation_failed` (422): limit is above 200, or cursor is not a value returned as next_cursor.

---

# Get email

> Retrieve one email with its current status.

Source: https://sndr.sh/docs/api/emails/get-email

`GET https://api.sndr.sh/v1/emails/{id}`

Retrieve one email with its current status. error explains a failed or bounced email; message bodies are not returned.

Scope: `read`

**Path parameters**

- `id` (string, required): Email ID (em_...), as returned by POST /send.

**Request**

```bash
curl 'https://api.sndr.sh/v1/emails/em_3f9c1a2b-7d4' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "id":              "em_3f9c1a2b-7d4",
  "organization_id": "org_8d41c7a2-3f6",
  "from":            "\"Acme\" <noreply@acme.com>",
  "to":              ["customer@example.com"],
  "cc":              ["accounts@example.com"],
  "subject":         "Your order #1234 is confirmed",
  "status":          "delivered",
  "domain_id":       "dom_a7c2e910-4b1",
  "created_at":      "2026-06-01T12:00:00Z",
  "delivered_at":    "2026-06-01T12:00:04Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Domains

> Add, verify and remove the domains you send from.

Source: https://sndr.sh/docs/api/domains

- [List domains](https://sndr.sh/docs/api/domains/list-domains) `GET /v1/domains`: List all sending domains on your workspace with their status and DNS records.
- [Add domain](https://sndr.sh/docs/api/domains/add-domain) `POST /v1/domains`: Add a sending domain.
- [Verify domain](https://sndr.sh/docs/api/domains/verify-domain) `POST /v1/domains/{id}/verify`: Run the DNS checks now and return the updated domain.
- [Delete domain](https://sndr.sh/docs/api/domains/delete-domain) `DELETE /v1/domains/{id}`: Remove a sending domain.

---

# List domains

> List all sending domains on your workspace with their status and DNS records.

Source: https://sndr.sh/docs/api/domains/list-domains

`GET https://api.sndr.sh/v1/domains`

List all sending domains on your workspace with their status and DNS records. Not paginated.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/v1/domains' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "dom_a7c2e910-4b1",
      "organization_id": "org_8d41c7a2-3f6",
      "name":            "mail.acme.com",
      "status":          "verified",
      "region":          "us-east-1",
      "spf_status":      "verified",
      "dkim_status":     "verified",
      "dmarc_status":    "verified",
      "mx_status":       "verified",
      "tls_rpt_status":  "failed",
      "mta_sts_status":  "failed",
      "bimi_status":     "failed",
      "records": [
        {
          "type":     "TXT",
          "name":     "mail.acme.com",
          "value":    "v=spf1 include:_spf.sndr.sh ~all",
          "status":   "verified",
          "hint":     "Add include:_spf.sndr.sh to your existing SPF record, or use this value if no SPF record exists. Keep one SPF record and retain your other mail providers.",
          "required": true,
          "label":    "SPF"
        }
      ],
      "created_at": "2026-01-20T09:00:00Z"
    }
  ]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.

---

# Add domain

> Add a sending domain.

Source: https://sndr.sh/docs/api/domains/add-domain

`POST https://api.sndr.sh/v1/domains`

Add a sending domain. Returns 201 with the domain (status pending) and the DNS records to publish; required ones have required: true.

Scope: `send`

**Body** (JSON)

- `name` (string, required): Domain or subdomain to send from, e.g. mail.acme.com.
- `region` (string): Region label stored on the domain. Defaults to us-east-1.

**Request**

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

**Response** (201)

```json
{
  "id":              "dom_a7c2e910-4b1",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "mail.acme.com",
  "status":          "pending",
  "region":          "us-east-1",
  "spf_status":      "unknown",
  "dkim_status":     "unknown",
  "dmarc_status":    "unknown",
  "mx_status":       "unknown",
  "tls_rpt_status":  "unknown",
  "mta_sts_status":  "unknown",
  "bimi_status":     "unknown",
  "records": [
    {
      "type":     "TXT",
      "name":     "mail.acme.com",
      "value":    "v=spf1 include:_spf.sndr.sh ~all",
      "status":   "unknown",
      "hint":     "Add include:_spf.sndr.sh to your existing SPF record, or use this value if no SPF record exists. Keep one SPF record and retain your other mail providers.",
      "required": true,
      "label":    "SPF"
    },
    {
      "type":     "TXT",
      "name":     "sndr._domainkey.mail.acme.com",
      "value":    "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "status":   "unknown",
      "hint":     "DKIM signing key — every outgoing message is signed with it.",
      "required": true,
      "label":    "DKIM"
    },
    {
      "type":     "TXT",
      "name":     "_dmarc.mail.acme.com",
      "value":    "v=DMARC1; p=quarantine; rua=mailto:dmarc@mail.acme.com; ruf=mailto:dmarc@mail.acme.com; pct=100; adkim=r; aspf=r",
      "status":   "unknown",
      "hint":     "Policy that ties SPF + DKIM together. Tells receivers what to do with messages that fail.",
      "required": true,
      "label":    "DMARC"
    }
  ],
  "created_at": "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, or name is missing or not a valid domain name.
- `plan_limit_reached` (402): The plan’s domain limit is reached.
- `insufficient_scope` (403): The API key is missing the send scope.
- `conflict` (409): This domain is already added to your workspace.

---

# Verify domain

> Run the DNS checks now and return the updated domain.

Source: https://sndr.sh/docs/api/domains/verify-domain

`POST https://api.sndr.sh/v1/domains/{id}/verify`

Run the DNS checks now and return the updated domain. status becomes verified when SPF, DKIM and DMARC all pass, otherwise it stays pending; each check is verified or failed.

Scope: `send`

**Path parameters**

- `id` (string, required): Domain ID (dom_...).

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/domains/dom_a7c2e910-4b1/verify' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "id":              "dom_a7c2e910-4b1",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "mail.acme.com",
  "status":          "pending",
  "region":          "us-east-1",
  "spf_status":      "verified",
  "dkim_status":     "verified",
  "dmarc_status":    "failed",
  "mx_status":       "verified",
  "tls_rpt_status":  "failed",
  "mta_sts_status":  "failed",
  "bimi_status":     "failed",
  "records": [
    {
      "type":     "TXT",
      "name":     "_dmarc.mail.acme.com",
      "value":    "v=DMARC1; p=quarantine; rua=mailto:dmarc@mail.acme.com; ruf=mailto:dmarc@mail.acme.com; pct=100; adkim=r; aspf=r",
      "status":   "failed",
      "hint":     "Policy that ties SPF + DKIM together. Tells receivers what to do with messages that fail.",
      "required": true,
      "label":    "DMARC"
    }
  ],
  "created_at": "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Delete domain

> Remove a sending domain.

Source: https://sndr.sh/docs/api/domains/delete-domain

`DELETE https://api.sndr.sh/v1/domains/{id}`

Remove a sending domain. Emails already sent are unaffected, but the domain can no longer be used as a from address.

Scope: `send`

**Path parameters**

- `id` (string, required): Domain ID (dom_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/v1/domains/dom_a7c2e910-4b1' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (204)

No content.

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Templates

> Subjects and bodies you reuse across sends.

Source: https://sndr.sh/docs/api/templates

- [List templates](https://sndr.sh/docs/api/templates/list-templates) `GET /v1/templates`: List all templates on your workspace, most recently updated first.
- [Create template](https://sndr.sh/docs/api/templates/create-template) `POST /v1/templates`: Create a template.
- [Get template](https://sndr.sh/docs/api/templates/get-template) `GET /v1/templates/{id}`: Retrieve one template, including its html and text body.
- [Update template](https://sndr.sh/docs/api/templates/update-template) `PATCH /v1/templates/{id}`: Update the fields you send; omitted fields keep their value.
- [Delete template](https://sndr.sh/docs/api/templates/delete-template) `DELETE /v1/templates/{id}`: Permanently delete a template.

---

# List templates

> List all templates on your workspace, most recently updated first.

Source: https://sndr.sh/docs/api/templates/list-templates

`GET https://api.sndr.sh/v1/templates`

List all templates on your workspace, most recently updated first. Not paginated.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/v1/templates' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "tpl_c19e5d34-82a",
      "organization_id": "org_8d41c7a2-3f6",
      "name":            "Order confirmation",
      "subject":         "Your order #{{ order_id }} is confirmed",
      "html":            "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
      "text":            "Hi {{ first_name }}, order #{{ order_id }} confirmed.",
      "version":         3,
      "created_at":      "2026-02-10T14:00:00Z",
      "updated_at":      "2026-05-01T09:00:00Z"
    }
  ]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.

---

# Create template

> Create a template.

Source: https://sndr.sh/docs/api/templates/create-template

`POST https://api.sndr.sh/v1/templates`

Create a template. Returns 201 with the template. HTML is sanitized on save: scripts, <style> blocks and event handlers are removed; inline styles stay.

Scope: `send`

**Body** (JSON)

- `name` (string, required): Internal name (not shown to recipients), 1–200 characters.
- `subject` (string, required): Subject line, max 998 characters. Supports {{ variable }} placeholders.
- `html` (string): HTML body. Either html or text is required.
- `text` (string): Plain-text body.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/templates' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name":    "Order confirmation",
    "subject": "Your order #{{ order_id }} is confirmed",
    "html":    "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
    "text":    "Hi {{ first_name }}, order #{{ order_id }} confirmed."
  }'
```

**Response** (201)

```json
{
  "id":              "tpl_c19e5d34-82a",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "Order confirmation",
  "subject":         "Your order #{{ order_id }} is confirmed",
  "html":            "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
  "text":            "Hi {{ first_name }}, order #{{ order_id }} confirmed.",
  "version":         1,
  "created_at":      "2026-06-01T12:00:00Z",
  "updated_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `plan_limit_reached` (402): The plan’s template limit is reached.
- `insufficient_scope` (403): The API key is missing the send scope.
- `validation_failed` (422): name or subject is missing or too long, or both html and text are empty.

---

# Get template

> Retrieve one template, including its html and text body.

Source: https://sndr.sh/docs/api/templates/get-template

`GET https://api.sndr.sh/v1/templates/{id}`

Retrieve one template, including its html and text body.

Scope: `read`

**Path parameters**

- `id` (string, required): Template ID (tpl_...).

**Request**

```bash
curl 'https://api.sndr.sh/v1/templates/tpl_c19e5d34-82a' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "id":              "tpl_c19e5d34-82a",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "Order confirmation",
  "subject":         "Your order #{{ order_id }} is confirmed",
  "html":            "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
  "text":            "Hi {{ first_name }}, order #{{ order_id }} confirmed.",
  "version":         3,
  "created_at":      "2026-02-10T14:00:00Z",
  "updated_at":      "2026-05-01T09:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Update template

> Update the fields you send; omitted fields keep their value.

Source: https://sndr.sh/docs/api/templates/update-template

`PATCH https://api.sndr.sh/v1/templates/{id}`

Update the fields you send; omitted fields keep their value. Empty html or text values are ignored, so a body cannot be cleared. Each update increments version.

Scope: `send`

**Path parameters**

- `id` (string, required): Template ID (tpl_...).

**Body** (JSON)

- `name` (string): New internal name, 1–200 characters.
- `subject` (string): New subject line, max 998 characters.
- `html` (string): New HTML body (sanitized on save).
- `text` (string): New plain-text body.

**Request**

```bash
curl -X PATCH 'https://api.sndr.sh/v1/templates/tpl_c19e5d34-82a' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"subject": "Order #{{ order_id }} has shipped"}'
```

**Response** (200)

```json
{
  "id":              "tpl_c19e5d34-82a",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "Order confirmation",
  "subject":         "Order #{{ order_id }} has shipped",
  "html":            "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
  "text":            "Hi {{ first_name }}, order #{{ order_id }} confirmed.",
  "version":         4,
  "created_at":      "2026-02-10T14:00:00Z",
  "updated_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `validation_failed` (422): name or subject is empty or too long.

---

# Delete template

> Permanently delete a template.

Source: https://sndr.sh/docs/api/templates/delete-template

`DELETE https://api.sndr.sh/v1/templates/{id}`

Permanently delete a template. Emails already sent are unaffected; later sends with this template_id fail with invalid_request.

Scope: `send`

**Path parameters**

- `id` (string, required): Template ID (tpl_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/v1/templates/tpl_c19e5d34-82a' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (204)

No content.

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Contacts

> The people you send broadcasts to.

Source: https://sndr.sh/docs/api/contacts

- [List contacts](https://sndr.sh/docs/api/contacts/list-contacts) `GET /v1/contacts`: List contacts on your workspace, newest first.
- [Create contact](https://sndr.sh/docs/api/contacts/create-contact) `POST /v1/contacts`: Create one contact.
- [Import contacts](https://sndr.sh/docs/api/contacts/import-contacts) `POST /v1/contacts/bulk`: Upsert up to 500 contacts by email.
- [Get contact](https://sndr.sh/docs/api/contacts/get-contact) `GET /v1/contacts/{id}`: Retrieve one contact by ID.
- [Update contact](https://sndr.sh/docs/api/contacts/update-contact) `PATCH /v1/contacts/{id}`: Update the fields you send; omitted fields are unchanged.
- [Delete contact](https://sndr.sh/docs/api/contacts/delete-contact) `DELETE /v1/contacts/{id}`: Permanently delete a contact and its group memberships.

---

# List contacts

> List contacts on your workspace, newest first.

Source: https://sndr.sh/docs/api/contacts/list-contacts

`GET https://api.sndr.sh/v1/contacts`

List contacts on your workspace, newest first. Cursor-paginated; counts holds account-wide totals per status.

Scope: `read`

**Query parameters**

- `limit` (integer): Page size. Default 50, max 200.
- `cursor` (string): The next_cursor value from the previous page. Omit for the first page.
- `status` (string): Only contacts with this status: subscribed | unsubscribed | bounced | complained.
- `group_id` (string): Only contacts in this group (grp_...).
- `q` (string): Case-insensitive search in email, first name and last name.

**Request**

```bash
curl 'https://api.sndr.sh/v1/contacts?status=subscribed&limit=20' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "con_0e6b7f21-c58",
      "organization_id": "org_8d41c7a2-3f6",
      "email":           "jane@example.com",
      "first_name":      "Jane",
      "last_name":       "Doe",
      "attributes":      { "plan": "pro", "city": "Berlin" },
      "status":          "subscribed",
      "source":          "checkout",
      "created_at":      "2026-03-01T10:00:00Z",
      "updated_at":      "2026-03-01T10:00:00Z"
    }
  ],
  "has_more": false,
  "count":    1,
  "limit":    20,
  "counts":   { "subscribed": 1, "unsubscribed": 0, "bounced": 0, "complained": 0 }
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `validation_failed` (422): limit is above 200, or cursor is not a value returned as next_cursor.

---

# Create contact

> Create one contact.

Source: https://sndr.sh/docs/api/contacts/create-contact

`POST https://api.sndr.sh/v1/contacts`

Create one contact. Returns 201 with the contact, or 409 if the email already exists — use POST /contacts/bulk to upsert.

Scope: `send`

**Body** (JSON)

- `email` (string, required): Email address. Stored lowercase and unique per account.
- `first_name` (string): First name, max 100 characters.
- `last_name` (string): Last name, max 100 characters.
- `status` (string): subscribed (default), unsubscribed, bounced or complained. Only subscribed contacts receive broadcasts.
- `attributes` (object): Free-form key-value data, e.g. {"plan":"pro"}.
- `source` (string): Label for where the contact came from. Defaults to manual.
- `group_ids` (string[]): Groups (grp_...) to add the new contact to. Unknown IDs are ignored.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/contacts' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "email":      "jane@example.com",
    "first_name": "Jane",
    "last_name":  "Doe",
    "attributes": { "plan": "pro", "city": "Berlin" },
    "source":     "checkout",
    "group_ids":  ["grp_4d8a0c5e-1f7"]
  }'
```

**Response** (201)

```json
{
  "id":              "con_0e6b7f21-c58",
  "organization_id": "org_8d41c7a2-3f6",
  "email":           "jane@example.com",
  "first_name":      "Jane",
  "last_name":       "Doe",
  "attributes":      { "plan": "pro", "city": "Berlin" },
  "status":          "subscribed",
  "source":          "checkout",
  "created_at":      "2026-06-01T12:00:00Z",
  "updated_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): The API key is missing the send scope.
- `conflict` (409): A contact with this email already exists.
- `validation_failed` (422): email is missing or invalid, a name is over 100 characters, or status is not one of the four values.

---

# Import contacts

> Upsert up to 500 contacts by email.

Source: https://sndr.sh/docs/api/contacts/import-contacts

`POST https://api.sndr.sh/v1/contacts/bulk`

Upsert up to 500 contacts by email. For existing contacts, attributes are merged and first_name, last_name and status are updated only when the row sets them, so an unsubscribed contact stays unsubscribed. New contacts default to subscribed.

Scope: `send`

**Body** (JSON)

- `contacts` (object[], required): Contacts as {email, first_name?, last_name?, status?, attributes?}, 1–500 per request.
- `source` (string): Source label for newly created contacts. Defaults to manual.
- `group_ids` (string[]): Groups (grp_...) to add every contact in the batch to.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/contacts/bulk' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contacts": [
      { "email": "alice@example.com", "first_name": "Alice", "attributes": { "tier": "gold" } },
      { "email": "bob@example.com",   "first_name": "Bob" }
    ],
    "source":    "import",
    "group_ids": ["grp_4d8a0c5e-1f7"]
  }'
```

**Response** (200)

```json
{
  "inserted": 1,
  "updated":  1,
  "skipped":  0
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `chunk_too_large` (400): More than 500 contacts in one request. Split the import.
- `insufficient_scope` (403): The API key is missing the send scope.
- `validation_failed` (422): contacts is empty, or a row has a missing or invalid email or an unknown status (fields names each row, e.g. row.<index>.email). Nothing is saved.

---

# Get contact

> Retrieve one contact by ID.

Source: https://sndr.sh/docs/api/contacts/get-contact

`GET https://api.sndr.sh/v1/contacts/{id}`

Retrieve one contact by ID.

Scope: `read`

**Path parameters**

- `id` (string, required): Contact ID (con_...).

**Request**

```bash
curl 'https://api.sndr.sh/v1/contacts/con_0e6b7f21-c58' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "id":              "con_0e6b7f21-c58",
  "organization_id": "org_8d41c7a2-3f6",
  "email":           "jane@example.com",
  "first_name":      "Jane",
  "last_name":       "Doe",
  "attributes":      { "plan": "pro", "city": "Berlin" },
  "status":          "subscribed",
  "source":          "checkout",
  "created_at":      "2026-03-01T10:00:00Z",
  "updated_at":      "2026-03-01T10:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Update contact

> Update the fields you send; omitted fields are unchanged.

Source: https://sndr.sh/docs/api/contacts/update-contact

`PATCH https://api.sndr.sh/v1/contacts/{id}`

Update the fields you send; omitted fields are unchanged. The email address cannot be changed.

Scope: `send`

**Path parameters**

- `id` (string, required): Contact ID (con_...).

**Body** (JSON)

- `first_name` (string): New first name, max 100 characters.
- `last_name` (string): New last name, max 100 characters.
- `status` (string): subscribed, unsubscribed, bounced or complained.
- `attributes` (object): Replaces the whole attributes object (keys are not merged).

**Request**

```bash
curl -X PATCH 'https://api.sndr.sh/v1/contacts/con_0e6b7f21-c58' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status": "unsubscribed"}'
```

**Response** (200)

```json
{
  "id":              "con_0e6b7f21-c58",
  "organization_id": "org_8d41c7a2-3f6",
  "email":           "jane@example.com",
  "first_name":      "Jane",
  "last_name":       "Doe",
  "attributes":      { "plan": "pro", "city": "Berlin" },
  "status":          "unsubscribed",
  "source":          "checkout",
  "created_at":      "2026-03-01T10:00:00Z",
  "updated_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `validation_failed` (422): status is not one of the allowed values, or a name is over 100 characters.

---

# Delete contact

> Permanently delete a contact and its group memberships.

Source: https://sndr.sh/docs/api/contacts/delete-contact

`DELETE https://api.sndr.sh/v1/contacts/{id}`

Permanently delete a contact and its group memberships.

Scope: `send`

**Path parameters**

- `id` (string, required): Contact ID (con_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/v1/contacts/con_0e6b7f21-c58' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "status": "ok"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Contact Groups

> Lists of contacts for broadcasts.

Source: https://sndr.sh/docs/api/contact-groups

- [List contact groups](https://sndr.sh/docs/api/contact-groups/list-contact-groups) `GET /v1/contact-groups`: List all contact groups on your workspace, newest first, with member counts.
- [Create contact group](https://sndr.sh/docs/api/contact-groups/create-contact-group) `POST /v1/contact-groups`: Create a contact group.
- [Get contact group](https://sndr.sh/docs/api/contact-groups/get-contact-group) `GET /v1/contact-groups/{id}`: Retrieve one contact group with its member count.
- [Update contact group](https://sndr.sh/docs/api/contact-groups/update-contact-group) `PATCH /v1/contact-groups/{id}`: Update the group’s name and/or description.
- [Delete contact group](https://sndr.sh/docs/api/contact-groups/delete-contact-group) `DELETE /v1/contact-groups/{id}`: Delete a group and its memberships.
- [List group members](https://sndr.sh/docs/api/contact-groups/list-group-members) `GET /v1/contact-groups/{id}/members`: List the contacts in a group, most recently added first.
- [Add group members](https://sndr.sh/docs/api/contact-groups/add-group-members) `POST /v1/contact-groups/{id}/members`: Add contacts to a group by ID.
- [Remove group members](https://sndr.sh/docs/api/contact-groups/remove-group-members) `DELETE /v1/contact-groups/{id}/members`: Remove contacts from a group.

---

# List contact groups

> List all contact groups on your workspace, newest first, with member counts.

Source: https://sndr.sh/docs/api/contact-groups/list-contact-groups

`GET https://api.sndr.sh/v1/contact-groups`

List all contact groups on your workspace, newest first, with member counts. Not paginated.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/v1/contact-groups' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "grp_4d8a0c5e-1f7",
      "organization_id": "org_8d41c7a2-3f6",
      "name":            "Newsletter",
      "slug":            "newsletter",
      "description":     "Opted in at checkout",
      "member_count":    4200,
      "created_at":      "2026-01-10T08:00:00Z"
    }
  ]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.

---

# Create contact group

> Create a contact group.

Source: https://sndr.sh/docs/api/contact-groups/create-contact-group

`POST https://api.sndr.sh/v1/contact-groups`

Create a contact group. Returns 201 with the group.

Scope: `send`

**Body** (JSON)

- `name` (string, required): Group name, 1–80 characters. Names with the same slug (e.g. "VIP" and "vip") conflict.
- `description` (string): Optional internal note.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/contact-groups' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "VIP customers", "description": "Accounts over $10k ARR"}'
```

**Response** (201)

```json
{
  "id":              "grp_4d8a0c5e-1f7",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "VIP customers",
  "slug":            "vip-customers",
  "description":     "Accounts over $10k ARR",
  "member_count":    0,
  "created_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, or name is missing or over 80 characters.
- `insufficient_scope` (403): The API key is missing the send scope.
- `name_taken` (409): A group with the same name (slug) already exists.

---

# Get contact group

> Retrieve one contact group with its member count.

Source: https://sndr.sh/docs/api/contact-groups/get-contact-group

`GET https://api.sndr.sh/v1/contact-groups/{id}`

Retrieve one contact group with its member count.

Scope: `read`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Request**

```bash
curl 'https://api.sndr.sh/v1/contact-groups/grp_4d8a0c5e-1f7' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "id":              "grp_4d8a0c5e-1f7",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "VIP customers",
  "slug":            "vip-customers",
  "description":     "Accounts over $10k ARR",
  "member_count":    142,
  "created_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Update contact group

> Update the group’s name and/or description.

Source: https://sndr.sh/docs/api/contact-groups/update-contact-group

`PATCH https://api.sndr.sh/v1/contact-groups/{id}`

Update the group’s name and/or description. Omitted fields keep their value; the name cannot be empty. The slug does not change.

Scope: `send`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Body** (JSON)

- `name` (string): New name. Omitting it clears the name.
- `description` (string): New description. Omitting it clears the description.

**Request**

```bash
curl -X PATCH 'https://api.sndr.sh/v1/contact-groups/grp_4d8a0c5e-1f7' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Enterprise customers", "description": "Accounts over $10k ARR"}'
```

**Response** (200)

```json
{
  "id":              "grp_4d8a0c5e-1f7",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "Enterprise customers",
  "slug":            "vip-customers",
  "description":     "Accounts over $10k ARR",
  "member_count":    142,
  "created_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Delete contact group

> Delete a group and its memberships.

Source: https://sndr.sh/docs/api/contact-groups/delete-contact-group

`DELETE https://api.sndr.sh/v1/contact-groups/{id}`

Delete a group and its memberships. The contacts themselves are kept. A group that a broadcast still targets cannot be deleted.

Scope: `send`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/v1/contact-groups/grp_4d8a0c5e-1f7' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "status": "ok"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `group_in_use` (409): A broadcast still targets this group. Delete or retarget the broadcast first.

---

# List group members

> List the contacts in a group, most recently added first.

Source: https://sndr.sh/docs/api/contact-groups/list-group-members

`GET https://api.sndr.sh/v1/contact-groups/{id}/members`

List the contacts in a group, most recently added first. Offset-paginated; total is the group size. An unknown group returns an empty list.

Scope: `read`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Query parameters**

- `limit` (integer): Page size. Default 50, max 500 (larger values fall back to 50).
- `offset` (integer): Number of rows to skip. Default 0.

**Request**

```bash
curl 'https://api.sndr.sh/v1/contact-groups/grp_4d8a0c5e-1f7/members?limit=50&offset=0' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "con_0e6b7f21-c58",
      "organization_id": "org_8d41c7a2-3f6",
      "email":           "jane@example.com",
      "first_name":      "Jane",
      "last_name":       "Doe",
      "attributes":      { "plan": "pro" },
      "status":          "subscribed",
      "source":          "checkout",
      "created_at":      "2026-03-01T10:00:00Z",
      "updated_at":      "2026-03-01T10:00:00Z"
    }
  ],
  "total": 142
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.

---

# Add group members

> Add contacts to a group by ID.

Source: https://sndr.sh/docs/api/contact-groups/add-group-members

`POST https://api.sndr.sh/v1/contact-groups/{id}/members`

Add contacts to a group by ID. Contacts already in the group or not in the account are skipped; added counts new memberships only.

Scope: `send`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Body** (JSON)

- `contact_ids` (string[], required): Contact IDs (con_...) to add, at least one.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/contact-groups/grp_4d8a0c5e-1f7/members' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids": ["con_0e6b7f21-c58", "con_71c3b9e4-a02"]}'
```

**Response** (200)

```json
{
  "added": 2
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, or contact_ids is missing or empty.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Remove group members

> Remove contacts from a group.

Source: https://sndr.sh/docs/api/contact-groups/remove-group-members

`DELETE https://api.sndr.sh/v1/contact-groups/{id}/members`

Remove contacts from a group. The contacts themselves are kept. IDs that are not members are ignored.

Scope: `send`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Body** (JSON)

- `contact_ids` (string[], required): Contact IDs (con_...) to remove, at least one.

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/v1/contact-groups/grp_4d8a0c5e-1f7/members' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids": ["con_0e6b7f21-c58"]}'
```

**Response** (200)

```json
{
  "status": "ok"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, or contact_ids is missing or empty.
- `insufficient_scope` (403): The API key is missing the send scope.

---

# Broadcasts

> Send one email to a contact group.

Source: https://sndr.sh/docs/api/broadcasts

- [List broadcasts](https://sndr.sh/docs/api/broadcasts/list-broadcasts) `GET /v1/broadcasts`: List broadcasts on your workspace, newest first.
- [Create broadcast](https://sndr.sh/docs/api/broadcasts/create-broadcast) `POST /v1/broadcasts`: Create a draft broadcast.
- [Get broadcast](https://sndr.sh/docs/api/broadcasts/get-broadcast) `GET /v1/broadcasts/{id}`: Retrieve one broadcast with its body and send progress (total_recipients, sent_count, failed_count).
- [Update broadcast](https://sndr.sh/docs/api/broadcasts/update-broadcast) `PATCH /v1/broadcasts/{id}`: Update a draft broadcast.
- [Delete broadcast](https://sndr.sh/docs/api/broadcasts/delete-broadcast) `DELETE /v1/broadcasts/{id}`: Delete a draft broadcast.
- [Send broadcast](https://sndr.sh/docs/api/broadcasts/send-broadcast) `POST /v1/broadcasts/{id}/send`: Queue a draft for immediate delivery to the group’s currently subscribed contacts.
- [List broadcast recipients](https://sndr.sh/docs/api/broadcasts/list-broadcast-recipients) `GET /v1/broadcasts/{id}/recipients`: List per-recipient delivery rows in queue order.

---

# List broadcasts

> List broadcasts on your workspace, newest first.

Source: https://sndr.sh/docs/api/broadcasts/list-broadcasts

`GET https://api.sndr.sh/v1/broadcasts`

List broadcasts on your workspace, newest first. Cursor-paginated. status is draft, queued, sending or sent.

Scope: `read`

**Query parameters**

- `limit` (integer): Page size. Default 50, max 200.
- `cursor` (string): The next_cursor value from the previous page. Omit for the first page.

**Request**

```bash
curl 'https://api.sndr.sh/v1/broadcasts' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":               "bca_9b3e6d12-a40",
      "organization_id":  "org_8d41c7a2-3f6",
      "name":             "June newsletter",
      "group_id":         "grp_4d8a0c5e-1f7",
      "from_email":       "hello@acme.com",
      "subject":          "June product update",
      "html":             "<h1>June update</h1><p>Here is what is new.</p>",
      "status":           "sent",
      "total_recipients": 4200,
      "sent_count":       4188,
      "failed_count":     12,
      "created_at":       "2026-05-28T14:00:00Z",
      "started_at":       "2026-06-01T09:00:00Z",
      "completed_at":     "2026-06-01T09:42:10Z"
    }
  ],
  "has_more": false,
  "count":    1,
  "limit":    50
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `validation_failed` (422): limit is above 200, or cursor is not a value returned as next_cursor.

---

# Create broadcast

> Create a draft broadcast.

Source: https://sndr.sh/docs/api/broadcasts/create-broadcast

`POST https://api.sndr.sh/v1/broadcasts`

Create a draft broadcast. Returns 201 with the broadcast. The from domain is not checked here; if it is not verified, every recipient fails at send time.

Scope: `send`

**Body** (JSON)

- `name` (string, required): Internal campaign name, 1–120 characters.
- `group_id` (string, required): Contact group to send to (grp_...). Must belong to your workspace.
- `from_email` (string, required): Sender, as an address or "Name <address>", on a verified domain.
- `subject` (string, required): Subject line, 1–500 characters.
- `html` (string): HTML body. Required unless text or template_id is set. {{email}}, {{first_name}}, {{last_name}} and any contact attribute (e.g. {{plan}}) are filled in per recipient.
- `text` (string): Plain-text body.
- `template_id` (string): Saved template (tpl_...) whose html and text are used when the broadcast has no body.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/broadcasts' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name":       "June newsletter",
    "group_id":   "grp_4d8a0c5e-1f7",
    "from_email": "Acme <hello@acme.com>",
    "subject":    "June product update",
    "html":       "<h1>June update</h1><p>Here is what is new.</p>"
  }'
```

**Response** (201)

```json
{
  "id":               "bca_9b3e6d12-a40",
  "organization_id":  "org_8d41c7a2-3f6",
  "name":             "June newsletter",
  "group_id":         "grp_4d8a0c5e-1f7",
  "from_email":       "\"Acme\" <hello@acme.com>",
  "subject":          "June product update",
  "html":             "<h1>June update</h1><p>Here is what is new.</p>",
  "status":           "draft",
  "total_recipients": 0,
  "sent_count":       0,
  "failed_count":     0,
  "created_at":       "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): The API key is missing the send scope.
- `validation_failed` (422): A required field is missing or too long, from_email is invalid, there is no body or template, or group_id is not in this account.

---

# Get broadcast

> Retrieve one broadcast with its body and send progress (total_recipients, sent_count, failed_count).

Source: https://sndr.sh/docs/api/broadcasts/get-broadcast

`GET https://api.sndr.sh/v1/broadcasts/{id}`

Retrieve one broadcast with its body and send progress (total_recipients, sent_count, failed_count).

Scope: `read`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Request**

```bash
curl 'https://api.sndr.sh/v1/broadcasts/bca_9b3e6d12-a40' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "id":               "bca_9b3e6d12-a40",
  "organization_id":  "org_8d41c7a2-3f6",
  "name":             "June newsletter",
  "group_id":         "grp_4d8a0c5e-1f7",
  "from_email":       "hello@acme.com",
  "subject":          "June product update",
  "html":             "<h1>June update</h1><p>Here is what is new.</p>",
  "status":           "sending",
  "total_recipients": 4200,
  "sent_count":       1630,
  "failed_count":     4,
  "created_at":       "2026-05-28T14:00:00Z",
  "started_at":       "2026-06-01T09:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Update broadcast

> Update a draft broadcast.

Source: https://sndr.sh/docs/api/broadcasts/update-broadcast

`PATCH https://api.sndr.sh/v1/broadcasts/{id}`

Update a draft broadcast. Send only the fields to change; it returns the updated broadcast.

Scope: `send`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Body** (JSON)

- `name` (string): New internal name, 1–120 characters.
- `group_id` (string): New target group (grp_...).
- `from_email` (string): New sender, as an address or "Name <address>".
- `subject` (string): New subject line, 1–500 characters.
- `template_id` (string): New template ID (tpl_...).
- `html` (string): New HTML body.
- `text` (string): New plain-text body.

**Request**

```bash
curl -X PATCH 'https://api.sndr.sh/v1/broadcasts/bca_9b3e6d12-a40' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"subject": "June product update: highlights"}'
```

**Response** (200)

```json
{
  "id":               "bca_9b3e6d12-a40",
  "organization_id":  "org_8d41c7a2-3f6",
  "name":             "June newsletter",
  "group_id":         "grp_4d8a0c5e-1f7",
  "from_email":       "hello@acme.com",
  "subject":          "June product update: highlights",
  "html":             "<h1>June update</h1><p>Here is what is new.</p>",
  "status":           "draft",
  "total_recipients": 0,
  "sent_count":       0,
  "failed_count":     0,
  "created_at":       "2026-05-28T14:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `not_editable` (400): The broadcast is no longer a draft.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `validation_failed` (422): name or subject is empty or too long, or from_email is invalid.

---

# Delete broadcast

> Delete a draft broadcast.

Source: https://sndr.sh/docs/api/broadcasts/delete-broadcast

`DELETE https://api.sndr.sh/v1/broadcasts/{id}`

Delete a draft broadcast. Broadcasts past draft cannot be deleted.

Scope: `send`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/v1/broadcasts/bca_9b3e6d12-a40' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "status": "ok"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): The broadcast does not exist or is no longer a draft.

---

# Send broadcast

> Queue a draft for immediate delivery to the group’s currently subscribed contacts.

Source: https://sndr.sh/docs/api/broadcasts/send-broadcast

`POST https://api.sndr.sh/v1/broadcasts/{id}/send`

Queue a draft for immediate delivery to the group’s currently subscribed contacts. Takes no body; scheduling is not supported. recipients is the number of contacts queued.

Scope: `send`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/broadcasts/bca_9b3e6d12-a40/send' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "status":     "queued",
  "recipients": 4200
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `empty_audience` (400): The group has no subscribed contacts. The broadcast stays in draft, so add contacts and send it again.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `cannot_queue` (409): The broadcast is not a draft.

---

# List broadcast recipients

> List per-recipient delivery rows in queue order.

Source: https://sndr.sh/docs/api/broadcasts/list-broadcast-recipients

`GET https://api.sndr.sh/v1/broadcasts/{id}/recipients`

List per-recipient delivery rows in queue order. Offset-paginated; status is pending, sending, sent or failed, and email_id links to GET /emails/{id}. An unknown broadcast returns an empty list.

Scope: `read`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Query parameters**

- `limit` (integer): Page size. Default 50, max 500 (larger values fall back to 50).
- `offset` (integer): Number of rows to skip. Default 0.

**Request**

```bash
curl 'https://api.sndr.sh/v1/broadcasts/bca_9b3e6d12-a40/recipients?limit=50&offset=0' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":           "br_7f2c9a41e8d0",
      "broadcast_id": "bca_9b3e6d12-a40",
      "contact_id":   "con_0e6b7f21-c58",
      "email":        "jane@example.com",
      "variables":    {},
      "email_id":     "em_d2a8f6c1-3b9",
      "status":       "sent",
      "sent_at":      "2026-06-01T09:01:12Z",
      "created_at":   "2026-06-01T09:00:00Z"
    }
  ],
  "total": 4200
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.

---

# Webhooks

> Endpoints for email events, and their signing secrets.

Source: https://sndr.sh/docs/api/webhooks

- [List webhooks](https://sndr.sh/docs/api/webhooks/list-webhooks) `GET /v1/webhooks`: List all webhooks on your workspace.
- [Create webhook](https://sndr.sh/docs/api/webhooks/create-webhook) `POST /v1/webhooks`: Register a webhook.
- [Delete webhook](https://sndr.sh/docs/api/webhooks/delete-webhook) `DELETE /v1/webhooks/{id}`: Delete a webhook.
- [List signing keys](https://sndr.sh/docs/api/webhooks/list-signing-keys) `GET /v1/webhooks/{id}/signing-keys`: List the webhook’s rotation keys (status primary, secondary or retired) without secrets.
- [Stage signing key](https://sndr.sh/docs/api/webhooks/stage-signing-key) `POST /v1/webhooks/{id}/signing-keys/stage`: Create a secondary key and return its secret once.
- [Promote signing key](https://sndr.sh/docs/api/webhooks/promote-signing-key) `POST /v1/webhooks/{id}/signing-keys/{key_id}/promote`: Make a secondary key the primary.
- [Retire signing key](https://sndr.sh/docs/api/webhooks/retire-signing-key) `POST /v1/webhooks/{id}/signing-keys/{key_id}/retire`: Retire a secondary key without promoting it.

---

# List webhooks

> List all webhooks on your workspace.

Source: https://sndr.sh/docs/api/webhooks/list-webhooks

`GET https://api.sndr.sh/v1/webhooks`

List all webhooks on your workspace. Secrets are not returned; secret_prefix shows which secret a webhook was created with.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/v1/webhooks' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "wh_2a7d4e9c-6b1",
      "organization_id": "org_8d41c7a2-3f6",
      "url":             "https://your-app.com/webhooks/sndr",
      "events":          ["email.delivered", "email.bounced", "email.failed"],
      "secret_prefix":   "whsec_Xk9pQ2",
      "active":          true,
      "created_at":      "2026-03-10T10:00:00Z"
    }
  ],
  "has_more": false,
  "count":    1,
  "limit":    1
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.

---

# Create webhook

> Register a webhook.

Source: https://sndr.sh/docs/api/webhooks/create-webhook

`POST https://api.sndr.sh/v1/webhooks`

Register a webhook. Returns 201 with the webhook and its signing secret. This is the only time the full secret is shown, so store it now.

Scope: `send`

**Body** (JSON)

- `url` (string, required): Public HTTPS URL. Hosts that resolve to private, loopback or link-local addresses are rejected.
- `events` (string[], required): Events to receive, at least one of: email.delivered, email.bounced, email.failed, email.unsubscribed (email.queued and email.complained are accepted but not sent).

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/webhooks' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "url":    "https://your-app.com/webhooks/sndr",
    "events": ["email.delivered", "email.bounced", "email.failed"]
  }'
```

**Response** (201)

```json
{
  "id":              "wh_2a7d4e9c-6b1",
  "organization_id": "org_8d41c7a2-3f6",
  "url":             "https://your-app.com/webhooks/sndr",
  "events":          ["email.delivered", "email.bounced", "email.failed"],
  "secret_prefix":   "whsec_Xk9pQ2",
  "active":          true,
  "created_at":      "2026-06-01T12:00:00Z",
  "secret":          "Xk9pQ2vLr8TzW4mN1bYcE7hJ0aSdFgUi"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, url is missing or not a URL, or an event name is not supported.
- `plan_limit_reached` (402): The plan’s webhook limit is reached.
- `insufficient_scope` (403): The API key is missing the send scope.
- `validation_failed` (422): url is not https, cannot be resolved, or points at a private address.

---

# Delete webhook

> Delete a webhook.

Source: https://sndr.sh/docs/api/webhooks/delete-webhook

`DELETE https://api.sndr.sh/v1/webhooks/{id}`

Delete a webhook. No further events are sent to its URL.

Scope: `send`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/v1/webhooks/wh_2a7d4e9c-6b1' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (204)

No content.

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# List signing keys

> List the webhook’s rotation keys (status primary, secondary or retired) without secrets.

Source: https://sndr.sh/docs/api/webhooks/list-signing-keys

`GET https://api.sndr.sh/v1/webhooks/{id}/signing-keys`

List the webhook’s rotation keys (status primary, secondary or retired) without secrets. A new webhook has no rows until you stage a key; its creation secret signs as primary until then.

Scope: `read`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).

**Request**

```bash
curl 'https://api.sndr.sh/v1/webhooks/wh_2a7d4e9c-6b1/signing-keys' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "webhook_id":  "wh_2a7d4e9c-6b1",
  "webhook_url": "https://your-app.com/webhooks/sndr",
  "data": [
    {
      "id":              "whk_61d0a9c7-5e4",
      "webhook_id":      "wh_2a7d4e9c-6b1",
      "status":          "secondary",
      "created_at":      "2026-06-01T13:00:00Z",
      "created_by":      "usr_5b2f8c1e-9a3",
      "rotation_reason": "scheduled rotation"
    }
  ],
  "count": 1
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Stage signing key

> Create a secondary key and return its secret once.

Source: https://sndr.sh/docs/api/webhooks/stage-signing-key

`POST https://api.sndr.sh/v1/webhooks/{id}/signing-keys/stage`

Create a secondary key and return its secret once. Events are signed with both keys (v1 and v1s) until you promote or retire it. The body is optional.

Scope: `send`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).

**Body** (JSON)

- `reason` (string): Short label stored with the key. Defaults to customer.
- `notes` (string): Optional free-form note.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/webhooks/wh_2a7d4e9c-6b1/signing-keys/stage' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"reason": "scheduled rotation"}'
```

**Response** (201)

```json
{
  "id":              "whk_61d0a9c7-5e4",
  "webhook_id":      "wh_2a7d4e9c-6b1",
  "status":          "secondary",
  "created_at":      "2026-06-01T13:00:00Z",
  "created_by":      "usr_5b2f8c1e-9a3",
  "rotation_reason": "scheduled rotation",
  "secret":          "Qm3vT8xZ1cR6yH0nB5wL9kD2fJ7sA4gP"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is missing or not valid JSON (send {} for the defaults).
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Promote signing key

> Make a secondary key the primary.

Source: https://sndr.sh/docs/api/webhooks/promote-signing-key

`POST https://api.sndr.sh/v1/webhooks/{id}/signing-keys/{key_id}/promote`

Make a secondary key the primary. The previous primary is retired at once, so update your receiver to the new secret first.

Scope: `send`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).
- `key_id` (string, required): Secondary key ID (whk_...) from the stage call.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/webhooks/wh_2a7d4e9c-6b1/signing-keys/whk_61d0a9c7-5e4/promote' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "id":     "whk_61d0a9c7-5e4",
  "status": "primary"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `conflict` (409): The key is not a secondary key.

---

# Retire signing key

> Retire a secondary key without promoting it.

Source: https://sndr.sh/docs/api/webhooks/retire-signing-key

`POST https://api.sndr.sh/v1/webhooks/{id}/signing-keys/{key_id}/retire`

Retire a secondary key without promoting it. The primary key cannot be retired; promote a replacement instead.

Scope: `send`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).
- `key_id` (string, required): Secondary key ID (whk_...).

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/webhooks/wh_2a7d4e9c-6b1/signing-keys/whk_61d0a9c7-5e4/retire' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "id":     "whk_61d0a9c7-5e4",
  "status": "retired"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `conflict` (409): The key is not a secondary key (it is the primary or already retired).

---

# Suppressions

> Addresses SNDR will not send to.

Source: https://sndr.sh/docs/api/suppressions

- [List suppressions](https://sndr.sh/docs/api/suppressions/list-suppressions) `GET /v1/suppressions`: List every suppressed address on your workspace, newest first.
- [Add suppression](https://sndr.sh/docs/api/suppressions/add-suppression) `POST /v1/suppressions`: Suppress an address, e.g.
- [Remove suppression](https://sndr.sh/docs/api/suppressions/remove-suppression) `DELETE /v1/suppressions/{addr}`: Remove an address so emails to it are attempted again.

---

# List suppressions

> List every suppressed address on your workspace, newest first.

Source: https://sndr.sh/docs/api/suppressions/list-suppressions

`GET https://api.sndr.sh/v1/suppressions`

List every suppressed address on your workspace, newest first. Not paginated. reason is bounce, unsubscribe, manual, or the value set when it was added.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/v1/suppressions' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "data": [
    {
      "organization_id": "org_8d41c7a2-3f6",
      "address":         "hard-bounce@example.com",
      "reason":          "bounce",
      "detail":          "550 5.1.1 user unknown",
      "created_at":      "2026-05-15T10:30:00Z"
    },
    {
      "organization_id": "org_8d41c7a2-3f6",
      "address":         "optout@example.com",
      "reason":          "manual",
      "created_at":      "2026-05-10T08:00:00Z"
    }
  ]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.

---

# Add suppression

> Suppress an address, e.g.

Source: https://sndr.sh/docs/api/suppressions/add-suppression

`POST https://api.sndr.sh/v1/suppressions`

Suppress an address, e.g. an opt-out collected outside SNDR. Returns 201; an address that is already suppressed keeps its original reason.

Scope: `send`

**Body** (JSON)

- `address` (string, required): Email address to suppress. Stored lowercase.
- `reason` (string): Why it is suppressed. Defaults to manual.
- `detail` (string): Optional note shown in the list.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/v1/suppressions' \
  -H "Authorization: Bearer $SNDR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"address": "optout@example.com", "detail": "Unsubscribed via support ticket"}'
```

**Response** (201)

```json
{
  "address": "optout@example.com",
  "reason":  "manual"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `invalid_request` (400): Body is not valid JSON, or address is missing or not an email.
- `insufficient_scope` (403): The API key is missing the send scope.

---

# Remove suppression

> Remove an address so emails to it are attempted again.

Source: https://sndr.sh/docs/api/suppressions/remove-suppression

`DELETE https://api.sndr.sh/v1/suppressions/{addr}`

Remove an address so emails to it are attempted again. Returns 204 even if the address was not suppressed.

Scope: `send`

**Path parameters**

- `addr` (string, required): The email address, e.g. optout@example.com. A percent-encoded @ (%40) works too.

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/v1/suppressions/optout@example.com' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (204)

No content.

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the send scope.

---

# Analytics

> Totals for sends, deliveries, bounces and complaints.

Source: https://sndr.sh/docs/api/analytics

- [Get analytics](https://sndr.sh/docs/api/analytics/get-analytics) `GET /v1/analytics`: Counts emails created in the window by status; sent counts every email, whatever its status.

---

# Get analytics

> Counts emails created in the window by status; sent counts every email, whatever its status.

Source: https://sndr.sh/docs/api/analytics/get-analytics

`GET https://api.sndr.sh/v1/analytics`

Counts emails created in the window by status; sent counts every email, whatever its status. inbox_rate is delivered / sent. Open and click tracking is not available.

Scope: `read`

**Query parameters**

- `range` (string): Window: 1d | 7d | 30d | 90d. Default 30d (also used for unknown values). The window used is returned as range.

**Request**

```bash
curl 'https://api.sndr.sh/v1/analytics?range=7d' \
  -H "Authorization: Bearer $SNDR_API_KEY"
```

**Response** (200)

```json
{
  "range":      "7d",
  "sent":       2140,
  "delivered":  2118,
  "bounced":    9,
  "failed":     11,
  "complained": 2,
  "inbox_rate": 0.9897,
  "as_of":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid API key.
- `insufficient_scope` (403): The API key is missing the read scope.

---

# Introduction

> Connect your platform to SNDR accounts with OAuth 2.0 and act on your users’ behalf.

Source: https://sndr.sh/docs/cranl

Your users approve access on a SNDR consent page. You get an access token scoped to their workspace and call the same resources as the public API, under `/api/cranl/v1`.

> **Note:** Partner credentials (`client_id` and `client_secret`) are issued by SNDR. [Contact us](https://sndr.sh/contact) to register an app.

- [Overview](https://sndr.sh/docs/cranl/overview): Base URL, scopes, limits and the flow in five steps.
- [Authentication](https://sndr.sh/docs/cranl/authentication): The OAuth 2.0 authorization code flow, with PKCE.
- [Tokens](https://sndr.sh/docs/cranl/tokens): Refresh, rotate and revoke tokens.
- [Errors](https://sndr.sh/docs/cranl/errors): OAuth and resource error codes.

Generating a client? Use the [OpenAPI spec](https://sndr.sh/docs/cranl/openapi.json).

---

# Overview

> Base URL, credential format, scopes, rate limits, and a five-step quickstart.

Source: https://sndr.sh/docs/cranl/overview

The SNDR Partner API lets your platform act on behalf of SNDR users — sending transactional emails, managing contacts, domains, templates, broadcasts, webhooks, and more — via a standard OAuth 2.0 Authorization Code flow.

> **Note:** Credentials are admin-issued. There is no self-service registration. Contact your SNDR account manager to receive a client_id and a one-time client_secret.

## Base URL

```bash
https://api.sndr.sh
```

## Quickstart

### 1. Get credentials

SNDR issues your `client_id` and a one-time `client_secret`. Store the secret in a vault; it can’t be shown again.

### 2. Send the user to SNDR

Redirect to `GET /api/cranl/oauth/authorize` with `client_id`, `redirect_uri`, `scope`, `state` and, ideally, a PKCE `code_challenge`.

### 3. The user approves

They sign in to SNDR if needed and approve your app on the consent page.

### 4. Handle the callback

SNDR redirects to your `redirect_uri` with a short-lived `code` and your `state`. Check that `state` matches.

### 5. Get tokens

From your backend, `POST /api/cranl/oauth/token` to exchange the code for an `access_token` and a `refresh_token`.

### 6. Call the API

Send `Authorization: Bearer <access_token>` to any `/api/cranl/v1` endpoint.

## Discovery (RFC 8414)

Fetch server metadata at startup rather than hardcoding endpoint URLs. Public — no authentication required.

```bash
curl 'https://api.sndr.sh/.well-known/oauth-authorization-server'
```

```json
{
  "issuer":                                "https://api.sndr.sh",
  "authorization_endpoint":               "https://app.sndr.sh/cranl/authorize",
  "token_endpoint":                        "https://api.sndr.sh/api/cranl/oauth/token",
  "revocation_endpoint":                   "https://api.sndr.sh/api/cranl/oauth/revoke",
  "scopes_supported":                      ["read", "send"],
  "response_types_supported":              ["code"],
  "grant_types_supported":                 ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported":      ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"]
}
```

## Scopes

| Scope | Allows |
| --- | --- |
| `read` | All `GET` endpoints: emails, analytics, domains, templates, contacts, contact groups, broadcasts, webhooks, suppressions. |
| `send` | Sending email, and creating, updating or deleting any resource above. |

## Credential format

All credentials (client_id, client_secret, access_token, refresh_token) share the format sndr_<32 alphanumeric characters> — 37 characters total.

## Rate limits

| Path | Limit |
| --- | --- |
| `/api/cranl/oauth/*` | 30 requests a minute per IP. |
| `/api/cranl/v1/*` | 300 requests a minute per IP. Over the limit you get `429` with a plain-text body and a `Retry-After` header. |

- Resource quotas come from the connected user's SNDR plan. A full plan cap (domains, templates, webhooks) returns 402 plan_limit_reached; a used-up monthly email quota returns 402 quota_exceeded.

---

# Authentication

> Complete OAuth 2.0 Authorization Code flow with optional PKCE.

Source: https://sndr.sh/docs/cranl/authentication

The Partner API uses OAuth 2.0 Authorization Code flow. Your backend never handles user credentials — SNDR manages login and the user grants permission on a hosted consent page.

![OAuth flow: your app redirects the user to SNDR, the user approves, SNDR redirects back with a code, your backend exchanges it for tokens, then calls the API with the access token.](https://sndr.sh/docs/images/oauth-flow.svg)

## Step 1 — Redirect the user

```bash
GET https://api.sndr.sh/api/cranl/oauth/authorize
  ?client_id=sndr_your_client_id
  &redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback
  &failure_redirect_uri=https%3A%2F%2Fyour-app.com%2Ffailed
  &scope=read+send
  &state=random_csrf_token
  &code_challenge=BASE64URL_SHA256_of_verifier
  &code_challenge_method=S256
```

- `client_id` (string, required): Your app’s client ID (`sndr_...`).
- `redirect_uri` (string, required): Where the user returns with `?code` after approving. Must exactly match a URI on your app’s allowlist.
- `scope` (string, required): Space-separated scopes: `read`, `send`.
- `state` (string): A random value you check when the user returns, to block CSRF. Sent back unchanged. Strongly recommended.
- `failure_redirect_uri` (string): Where the user returns with `?error` after denying. Must match your failure allowlist. If omitted, your first failure URI is used, or `redirect_uri` when none is set.
- `code_challenge` (string): PKCE challenge: `BASE64URL(SHA-256(code_verifier))`. Recommended.
- `code_challenge_method` (string): Must be `S256` when you send `code_challenge`.

> **Note:** If the user is not logged in, they are sent to the SNDR login page first and automatically returned to the consent page. Your redirect_uri, failure_redirect_uri, and state survive the login redirect.

## Step 2 — Handle the callback

On approval, the user is sent to your success redirect_uri:

```bash
GET https://your-app.com/callback
  ?code=short_lived_authorization_code
  &state=random_csrf_token
```

On denial or a recoverable error, the user is sent to your failure_redirect_uri (or, if none is configured, back to redirect_uri with an ?error param):

```bash
GET https://your-app.com/failed
  ?error=access_denied
  &error_description=User+denied+access
  &state=random_csrf_token
```

### Success vs failure URLs

Each app has two allowlists, both managed in the SNDR admin: a success allowlist (redirect_uris) and an optional failure allowlist (failure_redirect_uris). Approvals always return to a success URL with ?code; denials and recoverable errors return to a failure URL with ?error & ?state. Both are exact-match. If you register no failure URI, failures fall back to the success URL carrying an ?error param (standard OAuth behavior), so existing integrations keep working unchanged.

> **Warning:** Always verify that the state parameter matches what you sent — on both the success and failure callback. A mismatch means a CSRF attack — reject the request.

## Step 3 — Exchange the code for tokens

From your backend only — never from the browser. The code is single-use and expires in 10 minutes.

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=sndr_your_client_id' \
  --data-urlencode 'client_secret=sndr_your_client_secret' \
  --data-urlencode 'code=short_lived_authorization_code' \
  --data-urlencode 'redirect_uri=https://your-app.com/callback' \
  --data-urlencode 'code_verifier=your_pkce_verifier'
```

```json
{
  "access_token":  "sndr_access_token_here",
  "token_type":    "Bearer",
  "expires_in":    3600,
  "refresh_token": "sndr_refresh_token_here",
  "scope":         "read send"
}
```

## PKCE (recommended)

```js
// Node.js
const crypto = require('crypto')
const verifier  = crypto.randomBytes(64).toString('base64url')
const challenge = crypto.createHash('sha256').update(verifier).digest('base64url')
// send challenge in the auth URL, verifier in the token exchange
```

> **Warning:** If code_challenge was present in the authorization URL, code_verifier is required on token exchange. Omitting it returns 400 invalid_grant.

---

# Token management

> Access token lifetime, refresh rotation, revocation, and security practices.

Source: https://sndr.sh/docs/cranl/tokens

## Access tokens

Access tokens expire after 1 hour. Pass one in every resource request:

```bash
Authorization: Bearer sndr_your_access_token
```

> **Note:** Refresh proactively at ~55 minutes rather than waiting for a 401 — this prevents failed requests during peak load.

## Refreshing tokens

Refresh tokens are valid for 30 days and are rotated on every use — the old token is immediately invalidated. Always persist the new pair.

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=sndr_your_client_id' \
  --data-urlencode 'client_secret=sndr_your_client_secret' \
  --data-urlencode 'refresh_token=sndr_your_refresh_token'
```

```json
{
  "access_token":  "sndr_new_access_token",
  "token_type":    "Bearer",
  "expires_in":    3600,
  "refresh_token": "sndr_new_refresh_token",
  "scope":         "read send"
}
```

> **Warning:** If the refresh token expires (30 days) or is revoked, the user must complete the OAuth flow again. Plan accordingly.

## Revoking tokens

Revoke an access or refresh token immediately. Per RFC 7009, always returns 200 OK even for unknown tokens.

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/oauth/revoke' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=sndr_token_to_revoke' \
  --data-urlencode 'client_id=sndr_your_client_id' \
  --data-urlencode 'client_secret=sndr_your_client_secret'
```

## Security checklist

- Use PKCE. Send code_challenge on authorize and code_verifier on token exchange.
- Validate state. Reject callbacks where state does not match — it is a CSRF attack.
- Secrets in a vault. Never expose client_secret or tokens in client-side code, logs, or version control.
- Token exchange is server-side only. Never call /oauth/token from the browser.
- Revoke on disconnect. Call revoke when a user disconnects your integration.
- Handle 401 gracefully. Attempt one refresh on 401 token_expired before surfacing an error.

---

# Me

> Connected user, organization, plan, and the upgrade URL.

Source: https://sndr.sh/docs/cranl/me

Use the /me endpoint to display account context in your UI and to surface the plan upgrade link.

- [Get account](https://sndr.sh/docs/cranl/me/get-account) `GET /api/cranl/v1/me`: Returns the connected user, their organization (current plan slug and billing/upgrade URL), and the scopes granted to your token.

## Upgrading the plan

organization.upgrade_url is a ready-to-use link to the connected user’s SNDR billing page. When a request fails with 402 plan_limit_reached or 402 quota_exceeded, send the user to this URL to upgrade — for example, render it as an “Upgrade plan” button in your UI. The URL always points at the user’s own SNDR account.

> **Note:** upgrade_url is derived from SNDR’s dashboard URL at runtime — treat it as opaque and link to it directly rather than constructing your own billing URL.

---

# Get account

> Returns the connected user, their organization (current plan slug and billing/upgrade URL), and the scopes granted to your token.

Source: https://sndr.sh/docs/cranl/me/get-account

`GET https://api.sndr.sh/api/cranl/v1/me`

Returns the connected user, their organization (current plan slug and billing/upgrade URL), and the scopes granted to your token.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/me' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "user": {
    "id":         "usr_5b2f8c1e-9a3",
    "email":      "founder@acme.com",
    "name":       "Alex Johnson",
    "created_at": "2026-01-15T10:30:00Z"
  },
  "organization": {
    "id":          "org_8d41c7a2-3f6",
    "name":        "Acme Corp",
    "plan":        "pro",
    "upgrade_url": "https://app.sndr.sh/billing"
  },
  "scopes": ["read", "send"]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `not_found` (404): The connected user or organization no longer exists.

---

# Emails

> Send transactional emails and retrieve delivery history.

Source: https://sndr.sh/docs/cranl/emails

Send transactional emails on behalf of the connected SNDR account. The from address must use a domain added and verified on that account, and every to, cc and bcc address counts toward its monthly email quota.

An email’s status is one of queued, in_progress, sent, delivered, failed, bounced or complained. Use webhooks to be told when it changes.

- [Send email](https://sndr.sh/docs/cranl/emails/send-email) `POST /api/cranl/v1/send`: Queue an email for delivery.
- [List emails](https://sndr.sh/docs/cranl/emails/list-emails) `GET /api/cranl/v1/emails`: List emails sent from the connected account, newest first.
- [Get email](https://sndr.sh/docs/cranl/emails/get-email) `GET /api/cranl/v1/emails/{id}`: Retrieve one email with its current status.

---

# Send email

> Queue an email for delivery.

Source: https://sndr.sh/docs/cranl/emails/send-email

`POST https://api.sndr.sh/api/cranl/v1/send`

Queue an email for delivery. Returns 202 Accepted with the queued Email. Send an Idempotency-Key header to make retries safe: a repeat with the same key within 24 hours returns the first response.

Scope: `send`

**Body** (JSON)

- `from` (string, required): Sender, as an address or "Name <address>". Its domain must be added and verified on the connected account.
- `to` (string[], required): Recipient addresses, 1–1000, plain format (no display names). Must be an array, even for one recipient.
- `cc` (string[]): CC addresses, max 100.
- `bcc` (string[]): BCC addresses, max 100. to + cc + bcc together may not exceed 1000.
- `subject` (string): Subject line, single line, max 998 bytes. Required unless the template provides one.
- `html` (string): HTML body. Send html, text or both, unless template_id provides them.
- `text` (string): Plain-text body.
- `reply_to` (string): Reply-To address.
- `template_id` (string): Saved template ID (tpl_...). Its subject, html and text fill any of those fields you leave empty.
- `variables` (object): Values for {{ name }} placeholders in subject, html and text, e.g. {"first_name":"Alex"}. {{ user.name }} reads nested objects; unknown placeholders are left as is.
- `headers` (object): Extra headers as string pairs, e.g. {"X-Entity-Ref-ID":"1234"}. No CR/LF allowed; standard headers such as From, To, Subject, Reply-To or List-Unsubscribe are ignored.
- `tags` (object[]): Objects with string values, e.g. [{"name":"category","value":"welcome"}]. Accepted but not stored or returned yet.
- `attachments` (object[]): Up to 10 files as {filename, content, content_type?}. content is standard base64; content_type defaults to application/octet-stream. Max 10 MiB decoded in total; the whole request max 16 MiB.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/send' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1234-confirmation' \
  -d '{
    "from":      "Acme <noreply@acme.com>",
    "to":        ["customer@example.com"],
    "reply_to":  "support@acme.com",
    "subject":   "Your order #{{ order_id }} is confirmed",
    "html":      "<h1>Thanks, {{ first_name }}!</h1><p>Order #{{ order_id }} is being prepared.</p>",
    "text":      "Thanks, {{ first_name }}! Order #{{ order_id }} is being prepared.",
    "variables": { "first_name": "Alex", "order_id": "1234" }
  }'
```

**Response** (202)

```json
{
  "id":              "em_3f9c1a2b-7d4",
  "organization_id": "org_8d41c7a2-3f6",
  "from":            "\"Acme\" <noreply@acme.com>",
  "to":              ["customer@example.com"],
  "subject":         "Your order #1234 is confirmed",
  "status":          "queued",
  "domain_id":       "dom_a7c2e910-4b1",
  "created_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body failed validation — e.g. to sent as a string, an invalid address, no subject or body, over 1000 recipients, CR/LF in a header field, unknown template_id, or a bad attachment.
- `suppressed` (400): Every to address is on the suppression list. Suppressed cc/bcc addresses are dropped silently.
- `quota_exceeded` (402): The monthly email quota is used up. It resets on the 1st of the month (UTC).
- `insufficient_scope` (403): Token is missing the send scope.
- `domain_not_linked` (403): The from domain has not been added to the connected account.
- `domain_not_verified` (403): The from domain is added but its DNS records are not verified yet.
- `quarantine_active` (403): Sending is paused for this account. Contact SNDR support.
- `forbidden` (403): A recipient is on a known spam-trap list. Remove it and retry.
- `payload_too_large` (413): The request, or the rendered html + text, is over 16 MiB.
- `send_velocity` (429): Sending too fast for this account. Back off and retry.
- `sends_frozen` (503): Sending is temporarily paused platform-wide. Retry later.

---

# List emails

> List emails sent from the connected account, newest first.

Source: https://sndr.sh/docs/cranl/emails/list-emails

`GET https://api.sndr.sh/api/cranl/v1/emails`

List emails sent from the connected account, newest first. Cursor-paginated: pass next_cursor back as cursor while has_more is true.

Scope: `read`

**Query parameters**

- `limit` (integer): Page size. Default 50, max 200.
- `cursor` (string): The next_cursor value from the previous page. Omit for the first page.

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/emails?limit=1' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "em_3f9c1a2b-7d4",
      "organization_id": "org_8d41c7a2-3f6",
      "from":            "\"Acme\" <noreply@acme.com>",
      "to":              ["customer@example.com"],
      "subject":         "Your order #1234 is confirmed",
      "status":          "delivered",
      "domain_id":       "dom_a7c2e910-4b1",
      "created_at":      "2026-06-01T12:00:00Z",
      "delivered_at":    "2026-06-01T12:00:04Z"
    }
  ],
  "next_cursor": "eyJ0cyI6IjIwMjYtMDYtMDFUMTI6MDA6MDBaIiwiaWQiOiJlbV8zZjljMWEyYi03ZDQifQ",
  "has_more":    true,
  "count":       1,
  "limit":       1
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `validation_failed` (422): limit is above 200, or cursor is not a value returned as next_cursor.

---

# Get email

> Retrieve one email with its current status.

Source: https://sndr.sh/docs/cranl/emails/get-email

`GET https://api.sndr.sh/api/cranl/v1/emails/{id}`

Retrieve one email with its current status. error explains a failed or bounced email; message bodies are not returned.

Scope: `read`

**Path parameters**

- `id` (string, required): Email ID (em_...), as returned by POST /send.

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/emails/em_3f9c1a2b-7d4' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "id":              "em_3f9c1a2b-7d4",
  "organization_id": "org_8d41c7a2-3f6",
  "from":            "\"Acme\" <noreply@acme.com>",
  "to":              ["customer@example.com"],
  "cc":              ["accounts@example.com"],
  "subject":         "Your order #1234 is confirmed",
  "status":          "delivered",
  "domain_id":       "dom_a7c2e910-4b1",
  "created_at":      "2026-06-01T12:00:00Z",
  "delivered_at":    "2026-06-01T12:00:04Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Analytics

> Aggregate email performance metrics for the connected account.

Source: https://sndr.sh/docs/cranl/analytics

Retrieve email counts by status over a recent time window. Metrics cover all emails sent from the connected account.

- [Get analytics](https://sndr.sh/docs/cranl/analytics/get-analytics) `GET /api/cranl/v1/analytics`: Counts emails created in the window by status; sent counts every email, whatever its status.

---

# Get analytics

> Counts emails created in the window by status; sent counts every email, whatever its status.

Source: https://sndr.sh/docs/cranl/analytics/get-analytics

`GET https://api.sndr.sh/api/cranl/v1/analytics`

Counts emails created in the window by status; sent counts every email, whatever its status. inbox_rate is delivered / sent. Open and click tracking is not available.

Scope: `read`

**Query parameters**

- `range` (string): Window: 1d | 7d | 30d | 90d. Default 30d (also used for unknown values). The window used is returned as range.

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/analytics?range=7d' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "range":      "7d",
  "sent":       2140,
  "delivered":  2118,
  "bounced":    9,
  "failed":     11,
  "complained": 2,
  "inbox_rate": 0.9897,
  "as_of":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.

---

# Domains

> Add, verify, and remove sending domains on the connected account.

Source: https://sndr.sh/docs/cranl/domains

A domain must be added and verified before it can be used in from addresses. Verification checks the SPF, DKIM and DMARC records, and all three must pass. TLS-RPT, MTA-STS and BIMI records are optional extras.

> **Note:** DNS propagation typically takes a few minutes but can take up to 48 hours. Call the verify endpoint after publishing the records to check status.

- [List domains](https://sndr.sh/docs/cranl/domains/list-domains) `GET /api/cranl/v1/domains`: List all sending domains on the connected account with their status and DNS records.
- [Add domain](https://sndr.sh/docs/cranl/domains/add-domain) `POST /api/cranl/v1/domains`: Add a sending domain.
- [Verify domain](https://sndr.sh/docs/cranl/domains/verify-domain) `POST /api/cranl/v1/domains/{id}/verify`: Run the DNS checks now and return the updated domain.
- [Delete domain](https://sndr.sh/docs/cranl/domains/delete-domain) `DELETE /api/cranl/v1/domains/{id}`: Remove a sending domain.

---

# List domains

> List all sending domains on the connected account with their status and DNS records.

Source: https://sndr.sh/docs/cranl/domains/list-domains

`GET https://api.sndr.sh/api/cranl/v1/domains`

List all sending domains on the connected account with their status and DNS records. Not paginated.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/domains' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "dom_a7c2e910-4b1",
      "organization_id": "org_8d41c7a2-3f6",
      "name":            "mail.acme.com",
      "status":          "verified",
      "region":          "us-east-1",
      "spf_status":      "verified",
      "dkim_status":     "verified",
      "dmarc_status":    "verified",
      "mx_status":       "verified",
      "tls_rpt_status":  "failed",
      "mta_sts_status":  "failed",
      "bimi_status":     "failed",
      "records": [
        {
          "type":     "TXT",
          "name":     "mail.acme.com",
          "value":    "v=spf1 include:_spf.sndr.sh ~all",
          "status":   "verified",
          "hint":     "Add include:_spf.sndr.sh to your existing SPF record, or use this value if no SPF record exists. Keep one SPF record and retain your other mail providers.",
          "required": true,
          "label":    "SPF"
        }
      ],
      "created_at": "2026-01-20T09:00:00Z"
    }
  ]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.

---

# Add domain

> Add a sending domain.

Source: https://sndr.sh/docs/cranl/domains/add-domain

`POST https://api.sndr.sh/api/cranl/v1/domains`

Add a sending domain. Returns 201 with the domain (status pending) and the DNS records to publish; required ones have required: true.

Scope: `send`

**Body** (JSON)

- `name` (string, required): Domain or subdomain to send from, e.g. mail.acme.com.
- `region` (string): Region label stored on the domain. Defaults to us-east-1.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/domains' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"name": "mail.acme.com"}'
```

**Response** (201)

```json
{
  "id":              "dom_a7c2e910-4b1",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "mail.acme.com",
  "status":          "pending",
  "region":          "us-east-1",
  "spf_status":      "unknown",
  "dkim_status":     "unknown",
  "dmarc_status":    "unknown",
  "mx_status":       "unknown",
  "tls_rpt_status":  "unknown",
  "mta_sts_status":  "unknown",
  "bimi_status":     "unknown",
  "records": [
    {
      "type":     "TXT",
      "name":     "mail.acme.com",
      "value":    "v=spf1 include:_spf.sndr.sh ~all",
      "status":   "unknown",
      "hint":     "Add include:_spf.sndr.sh to your existing SPF record, or use this value if no SPF record exists. Keep one SPF record and retain your other mail providers.",
      "required": true,
      "label":    "SPF"
    },
    {
      "type":     "TXT",
      "name":     "sndr._domainkey.mail.acme.com",
      "value":    "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "status":   "unknown",
      "hint":     "DKIM signing key — every outgoing message is signed with it.",
      "required": true,
      "label":    "DKIM"
    },
    {
      "type":     "TXT",
      "name":     "_dmarc.mail.acme.com",
      "value":    "v=DMARC1; p=quarantine; rua=mailto:dmarc@mail.acme.com; ruf=mailto:dmarc@mail.acme.com; pct=100; adkim=r; aspf=r",
      "status":   "unknown",
      "hint":     "Policy that ties SPF + DKIM together. Tells receivers what to do with messages that fail.",
      "required": true,
      "label":    "DMARC"
    }
  ],
  "created_at": "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, or name is missing or not a valid domain name.
- `plan_limit_reached` (402): The plan’s domain limit is reached.
- `insufficient_scope` (403): Token is missing the send scope.
- `conflict` (409): This domain is already added to the connected account.

---

# Verify domain

> Run the DNS checks now and return the updated domain.

Source: https://sndr.sh/docs/cranl/domains/verify-domain

`POST https://api.sndr.sh/api/cranl/v1/domains/{id}/verify`

Run the DNS checks now and return the updated domain. status becomes verified when SPF, DKIM and DMARC all pass, otherwise it stays pending; each check is verified or failed.

Scope: `send`

**Path parameters**

- `id` (string, required): Domain ID (dom_...).

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/domains/dom_a7c2e910-4b1/verify' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "id":              "dom_a7c2e910-4b1",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "mail.acme.com",
  "status":          "pending",
  "region":          "us-east-1",
  "spf_status":      "verified",
  "dkim_status":     "verified",
  "dmarc_status":    "failed",
  "mx_status":       "verified",
  "tls_rpt_status":  "failed",
  "mta_sts_status":  "failed",
  "bimi_status":     "failed",
  "records": [
    {
      "type":     "TXT",
      "name":     "_dmarc.mail.acme.com",
      "value":    "v=DMARC1; p=quarantine; rua=mailto:dmarc@mail.acme.com; ruf=mailto:dmarc@mail.acme.com; pct=100; adkim=r; aspf=r",
      "status":   "failed",
      "hint":     "Policy that ties SPF + DKIM together. Tells receivers what to do with messages that fail.",
      "required": true,
      "label":    "DMARC"
    }
  ],
  "created_at": "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Delete domain

> Remove a sending domain.

Source: https://sndr.sh/docs/cranl/domains/delete-domain

`DELETE https://api.sndr.sh/api/cranl/v1/domains/{id}`

Remove a sending domain. Emails already sent are unaffected, but the domain can no longer be used as a from address.

Scope: `send`

**Path parameters**

- `id` (string, required): Domain ID (dom_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/api/cranl/v1/domains/dom_a7c2e910-4b1' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (204)

No content.

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Templates

> Create and manage reusable email templates with variable interpolation.

Source: https://sndr.sh/docs/cranl/templates

Templates store a reusable subject plus an HTML and/or plain-text body with {{ variable_name }} placeholders. Pass template_id and variables to POST /send to fill them at send time.

- [List templates](https://sndr.sh/docs/cranl/templates/list-templates) `GET /api/cranl/v1/templates`: List all templates on the connected account, most recently updated first.
- [Create template](https://sndr.sh/docs/cranl/templates/create-template) `POST /api/cranl/v1/templates`: Create a template.
- [Get template](https://sndr.sh/docs/cranl/templates/get-template) `GET /api/cranl/v1/templates/{id}`: Retrieve one template, including its html and text body.
- [Update template](https://sndr.sh/docs/cranl/templates/update-template) `PATCH /api/cranl/v1/templates/{id}`: Update the fields you send; omitted fields keep their value.
- [Delete template](https://sndr.sh/docs/cranl/templates/delete-template) `DELETE /api/cranl/v1/templates/{id}`: Permanently delete a template.

---

# List templates

> List all templates on the connected account, most recently updated first.

Source: https://sndr.sh/docs/cranl/templates/list-templates

`GET https://api.sndr.sh/api/cranl/v1/templates`

List all templates on the connected account, most recently updated first. Not paginated.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/templates' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "tpl_c19e5d34-82a",
      "organization_id": "org_8d41c7a2-3f6",
      "name":            "Order confirmation",
      "subject":         "Your order #{{ order_id }} is confirmed",
      "html":            "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
      "text":            "Hi {{ first_name }}, order #{{ order_id }} confirmed.",
      "version":         3,
      "created_at":      "2026-02-10T14:00:00Z",
      "updated_at":      "2026-05-01T09:00:00Z"
    }
  ]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.

---

# Create template

> Create a template.

Source: https://sndr.sh/docs/cranl/templates/create-template

`POST https://api.sndr.sh/api/cranl/v1/templates`

Create a template. Returns 201 with the template. HTML is sanitized on save: scripts, <style> blocks and event handlers are removed; inline styles stay.

Scope: `send`

**Body** (JSON)

- `name` (string, required): Internal name (not shown to recipients), 1–200 characters.
- `subject` (string, required): Subject line, max 998 characters. Supports {{ variable }} placeholders.
- `html` (string): HTML body. Either html or text is required.
- `text` (string): Plain-text body.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/templates' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "name":    "Order confirmation",
    "subject": "Your order #{{ order_id }} is confirmed",
    "html":    "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
    "text":    "Hi {{ first_name }}, order #{{ order_id }} confirmed."
  }'
```

**Response** (201)

```json
{
  "id":              "tpl_c19e5d34-82a",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "Order confirmation",
  "subject":         "Your order #{{ order_id }} is confirmed",
  "html":            "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
  "text":            "Hi {{ first_name }}, order #{{ order_id }} confirmed.",
  "version":         1,
  "created_at":      "2026-06-01T12:00:00Z",
  "updated_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `plan_limit_reached` (402): The plan’s template limit is reached.
- `insufficient_scope` (403): Token is missing the send scope.
- `validation_failed` (422): name or subject is missing or too long, or both html and text are empty.

---

# Get template

> Retrieve one template, including its html and text body.

Source: https://sndr.sh/docs/cranl/templates/get-template

`GET https://api.sndr.sh/api/cranl/v1/templates/{id}`

Retrieve one template, including its html and text body.

Scope: `read`

**Path parameters**

- `id` (string, required): Template ID (tpl_...).

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/templates/tpl_c19e5d34-82a' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "id":              "tpl_c19e5d34-82a",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "Order confirmation",
  "subject":         "Your order #{{ order_id }} is confirmed",
  "html":            "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
  "text":            "Hi {{ first_name }}, order #{{ order_id }} confirmed.",
  "version":         3,
  "created_at":      "2026-02-10T14:00:00Z",
  "updated_at":      "2026-05-01T09:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Update template

> Update the fields you send; omitted fields keep their value.

Source: https://sndr.sh/docs/cranl/templates/update-template

`PATCH https://api.sndr.sh/api/cranl/v1/templates/{id}`

Update the fields you send; omitted fields keep their value. Empty html or text values are ignored, so a body cannot be cleared. Each update increments version.

Scope: `send`

**Path parameters**

- `id` (string, required): Template ID (tpl_...).

**Body** (JSON)

- `name` (string): New internal name, 1–200 characters.
- `subject` (string): New subject line, max 998 characters.
- `html` (string): New HTML body (sanitized on save).
- `text` (string): New plain-text body.

**Request**

```bash
curl -X PATCH 'https://api.sndr.sh/api/cranl/v1/templates/tpl_c19e5d34-82a' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"subject": "Order #{{ order_id }} has shipped"}'
```

**Response** (200)

```json
{
  "id":              "tpl_c19e5d34-82a",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "Order confirmation",
  "subject":         "Order #{{ order_id }} has shipped",
  "html":            "<h1>Hi {{ first_name }},</h1><p>Order #{{ order_id }} confirmed.</p>",
  "text":            "Hi {{ first_name }}, order #{{ order_id }} confirmed.",
  "version":         4,
  "created_at":      "2026-02-10T14:00:00Z",
  "updated_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `validation_failed` (422): name or subject is empty or too long.

---

# Delete template

> Permanently delete a template.

Source: https://sndr.sh/docs/cranl/templates/delete-template

`DELETE https://api.sndr.sh/api/cranl/v1/templates/{id}`

Permanently delete a template. Emails already sent are unaffected; later sends with this template_id fail with invalid_request.

Scope: `send`

**Path parameters**

- `id` (string, required): Template ID (tpl_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/api/cranl/v1/templates/tpl_c19e5d34-82a' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (204)

No content.

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Contacts

> Create, manage, and bulk-import subscriber contacts.

Source: https://sndr.sh/docs/cranl/contacts

Contacts are the people you send broadcasts to: an email address, optional names, a subscription status and free-form attributes. A contact can belong to any number of contact groups.

- [List contacts](https://sndr.sh/docs/cranl/contacts/list-contacts) `GET /api/cranl/v1/contacts`: List contacts on the connected account, newest first.
- [Create contact](https://sndr.sh/docs/cranl/contacts/create-contact) `POST /api/cranl/v1/contacts`: Create one contact.
- [Import contacts](https://sndr.sh/docs/cranl/contacts/import-contacts) `POST /api/cranl/v1/contacts/bulk`: Upsert up to 500 contacts by email.
- [Get contact](https://sndr.sh/docs/cranl/contacts/get-contact) `GET /api/cranl/v1/contacts/{id}`: Retrieve one contact by ID.
- [Update contact](https://sndr.sh/docs/cranl/contacts/update-contact) `PATCH /api/cranl/v1/contacts/{id}`: Update the fields you send; omitted fields are unchanged.
- [Delete contact](https://sndr.sh/docs/cranl/contacts/delete-contact) `DELETE /api/cranl/v1/contacts/{id}`: Permanently delete a contact and its group memberships.

---

# List contacts

> List contacts on the connected account, newest first.

Source: https://sndr.sh/docs/cranl/contacts/list-contacts

`GET https://api.sndr.sh/api/cranl/v1/contacts`

List contacts on the connected account, newest first. Cursor-paginated; counts holds account-wide totals per status.

Scope: `read`

**Query parameters**

- `limit` (integer): Page size. Default 50, max 200.
- `cursor` (string): The next_cursor value from the previous page. Omit for the first page.
- `status` (string): Only contacts with this status: subscribed | unsubscribed | bounced | complained.
- `group_id` (string): Only contacts in this group (grp_...).
- `q` (string): Case-insensitive search in email, first name and last name.

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/contacts?status=subscribed&limit=20' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "con_0e6b7f21-c58",
      "organization_id": "org_8d41c7a2-3f6",
      "email":           "jane@example.com",
      "first_name":      "Jane",
      "last_name":       "Doe",
      "attributes":      { "plan": "pro", "city": "Berlin" },
      "status":          "subscribed",
      "source":          "checkout",
      "created_at":      "2026-03-01T10:00:00Z",
      "updated_at":      "2026-03-01T10:00:00Z"
    }
  ],
  "has_more": false,
  "count":    1,
  "limit":    20,
  "counts":   { "subscribed": 1, "unsubscribed": 0, "bounced": 0, "complained": 0 }
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `validation_failed` (422): limit is above 200, or cursor is not a value returned as next_cursor.

---

# Create contact

> Create one contact.

Source: https://sndr.sh/docs/cranl/contacts/create-contact

`POST https://api.sndr.sh/api/cranl/v1/contacts`

Create one contact. Returns 201 with the contact, or 409 if the email already exists — use POST /contacts/bulk to upsert.

Scope: `send`

**Body** (JSON)

- `email` (string, required): Email address. Stored lowercase and unique per account.
- `first_name` (string): First name, max 100 characters.
- `last_name` (string): Last name, max 100 characters.
- `status` (string): subscribed (default), unsubscribed, bounced or complained. Only subscribed contacts receive broadcasts.
- `attributes` (object): Free-form key-value data, e.g. {"plan":"pro"}.
- `source` (string): Label for where the contact came from. Defaults to manual.
- `group_ids` (string[]): Groups (grp_...) to add the new contact to. Unknown IDs are ignored.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/contacts' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "email":      "jane@example.com",
    "first_name": "Jane",
    "last_name":  "Doe",
    "attributes": { "plan": "pro", "city": "Berlin" },
    "source":     "checkout",
    "group_ids":  ["grp_4d8a0c5e-1f7"]
  }'
```

**Response** (201)

```json
{
  "id":              "con_0e6b7f21-c58",
  "organization_id": "org_8d41c7a2-3f6",
  "email":           "jane@example.com",
  "first_name":      "Jane",
  "last_name":       "Doe",
  "attributes":      { "plan": "pro", "city": "Berlin" },
  "status":          "subscribed",
  "source":          "checkout",
  "created_at":      "2026-06-01T12:00:00Z",
  "updated_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): Token is missing the send scope.
- `conflict` (409): A contact with this email already exists.
- `validation_failed` (422): email is missing or invalid, a name is over 100 characters, or status is not one of the four values.

---

# Import contacts

> Upsert up to 500 contacts by email.

Source: https://sndr.sh/docs/cranl/contacts/import-contacts

`POST https://api.sndr.sh/api/cranl/v1/contacts/bulk`

Upsert up to 500 contacts by email. For existing contacts, attributes are merged and first_name, last_name and status are updated only when the row sets them, so an unsubscribed contact stays unsubscribed. New contacts default to subscribed.

Scope: `send`

**Body** (JSON)

- `contacts` (object[], required): Contacts as {email, first_name?, last_name?, status?, attributes?}, 1–500 per request.
- `source` (string): Source label for newly created contacts. Defaults to manual.
- `group_ids` (string[]): Groups (grp_...) to add every contact in the batch to.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/contacts/bulk' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "contacts": [
      { "email": "alice@example.com", "first_name": "Alice", "attributes": { "tier": "gold" } },
      { "email": "bob@example.com",   "first_name": "Bob" }
    ],
    "source":    "import",
    "group_ids": ["grp_4d8a0c5e-1f7"]
  }'
```

**Response** (200)

```json
{
  "inserted": 1,
  "updated":  1,
  "skipped":  0
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `chunk_too_large` (400): More than 500 contacts in one request. Split the import.
- `insufficient_scope` (403): Token is missing the send scope.
- `validation_failed` (422): contacts is empty, or a row has a missing or invalid email or an unknown status (fields names each row, e.g. row.<index>.email). Nothing is saved.

---

# Get contact

> Retrieve one contact by ID.

Source: https://sndr.sh/docs/cranl/contacts/get-contact

`GET https://api.sndr.sh/api/cranl/v1/contacts/{id}`

Retrieve one contact by ID.

Scope: `read`

**Path parameters**

- `id` (string, required): Contact ID (con_...).

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/contacts/con_0e6b7f21-c58' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "id":              "con_0e6b7f21-c58",
  "organization_id": "org_8d41c7a2-3f6",
  "email":           "jane@example.com",
  "first_name":      "Jane",
  "last_name":       "Doe",
  "attributes":      { "plan": "pro", "city": "Berlin" },
  "status":          "subscribed",
  "source":          "checkout",
  "created_at":      "2026-03-01T10:00:00Z",
  "updated_at":      "2026-03-01T10:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Update contact

> Update the fields you send; omitted fields are unchanged.

Source: https://sndr.sh/docs/cranl/contacts/update-contact

`PATCH https://api.sndr.sh/api/cranl/v1/contacts/{id}`

Update the fields you send; omitted fields are unchanged. The email address cannot be changed.

Scope: `send`

**Path parameters**

- `id` (string, required): Contact ID (con_...).

**Body** (JSON)

- `first_name` (string): New first name, max 100 characters.
- `last_name` (string): New last name, max 100 characters.
- `status` (string): subscribed, unsubscribed, bounced or complained.
- `attributes` (object): Replaces the whole attributes object (keys are not merged).

**Request**

```bash
curl -X PATCH 'https://api.sndr.sh/api/cranl/v1/contacts/con_0e6b7f21-c58' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"status": "unsubscribed"}'
```

**Response** (200)

```json
{
  "id":              "con_0e6b7f21-c58",
  "organization_id": "org_8d41c7a2-3f6",
  "email":           "jane@example.com",
  "first_name":      "Jane",
  "last_name":       "Doe",
  "attributes":      { "plan": "pro", "city": "Berlin" },
  "status":          "unsubscribed",
  "source":          "checkout",
  "created_at":      "2026-03-01T10:00:00Z",
  "updated_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `validation_failed` (422): status is not one of the allowed values, or a name is over 100 characters.

---

# Delete contact

> Permanently delete a contact and its group memberships.

Source: https://sndr.sh/docs/cranl/contacts/delete-contact

`DELETE https://api.sndr.sh/api/cranl/v1/contacts/{id}`

Permanently delete a contact and its group memberships.

Scope: `send`

**Path parameters**

- `id` (string, required): Contact ID (con_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/api/cranl/v1/contacts/con_0e6b7f21-c58' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "status": "ok"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Contact Groups

> Organize contacts into segments for targeted broadcasts.

Source: https://sndr.sh/docs/cranl/contact-groups

Contact groups are lists of contacts. Every broadcast targets one group, and a contact can belong to several groups at once.

- [List contact groups](https://sndr.sh/docs/cranl/contact-groups/list-contact-groups) `GET /api/cranl/v1/contact-groups`: List all contact groups on the connected account, newest first, with member counts.
- [Create contact group](https://sndr.sh/docs/cranl/contact-groups/create-contact-group) `POST /api/cranl/v1/contact-groups`: Create a contact group.
- [Get contact group](https://sndr.sh/docs/cranl/contact-groups/get-contact-group) `GET /api/cranl/v1/contact-groups/{id}`: Retrieve one contact group with its member count.
- [Update contact group](https://sndr.sh/docs/cranl/contact-groups/update-contact-group) `PATCH /api/cranl/v1/contact-groups/{id}`: Update the group’s name and/or description.
- [Delete contact group](https://sndr.sh/docs/cranl/contact-groups/delete-contact-group) `DELETE /api/cranl/v1/contact-groups/{id}`: Delete a group and its memberships.
- [List group members](https://sndr.sh/docs/cranl/contact-groups/list-group-members) `GET /api/cranl/v1/contact-groups/{id}/members`: List the contacts in a group, most recently added first.
- [Add group members](https://sndr.sh/docs/cranl/contact-groups/add-group-members) `POST /api/cranl/v1/contact-groups/{id}/members`: Add contacts to a group by ID.
- [Remove group members](https://sndr.sh/docs/cranl/contact-groups/remove-group-members) `DELETE /api/cranl/v1/contact-groups/{id}/members`: Remove contacts from a group.

---

# List contact groups

> List all contact groups on the connected account, newest first, with member counts.

Source: https://sndr.sh/docs/cranl/contact-groups/list-contact-groups

`GET https://api.sndr.sh/api/cranl/v1/contact-groups`

List all contact groups on the connected account, newest first, with member counts. Not paginated.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/contact-groups' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "grp_4d8a0c5e-1f7",
      "organization_id": "org_8d41c7a2-3f6",
      "name":            "Newsletter",
      "slug":            "newsletter",
      "description":     "Opted in at checkout",
      "member_count":    4200,
      "created_at":      "2026-01-10T08:00:00Z"
    }
  ]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.

---

# Create contact group

> Create a contact group.

Source: https://sndr.sh/docs/cranl/contact-groups/create-contact-group

`POST https://api.sndr.sh/api/cranl/v1/contact-groups`

Create a contact group. Returns 201 with the group.

Scope: `send`

**Body** (JSON)

- `name` (string, required): Group name, 1–80 characters. Names with the same slug (e.g. "VIP" and "vip") conflict.
- `description` (string): Optional internal note.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/contact-groups' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"name": "VIP customers", "description": "Accounts over $10k ARR"}'
```

**Response** (201)

```json
{
  "id":              "grp_4d8a0c5e-1f7",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "VIP customers",
  "slug":            "vip-customers",
  "description":     "Accounts over $10k ARR",
  "member_count":    0,
  "created_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, or name is missing or over 80 characters.
- `insufficient_scope` (403): Token is missing the send scope.
- `name_taken` (409): A group with the same name (slug) already exists.

---

# Get contact group

> Retrieve one contact group with its member count.

Source: https://sndr.sh/docs/cranl/contact-groups/get-contact-group

`GET https://api.sndr.sh/api/cranl/v1/contact-groups/{id}`

Retrieve one contact group with its member count.

Scope: `read`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/contact-groups/grp_4d8a0c5e-1f7' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "id":              "grp_4d8a0c5e-1f7",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "VIP customers",
  "slug":            "vip-customers",
  "description":     "Accounts over $10k ARR",
  "member_count":    142,
  "created_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Update contact group

> Update the group’s name and/or description.

Source: https://sndr.sh/docs/cranl/contact-groups/update-contact-group

`PATCH https://api.sndr.sh/api/cranl/v1/contact-groups/{id}`

Update the group’s name and/or description. Omitted fields keep their value; the name cannot be empty. The slug does not change.

Scope: `send`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Body** (JSON)

- `name` (string): New name. Omitting it clears the name.
- `description` (string): New description. Omitting it clears the description.

**Request**

```bash
curl -X PATCH 'https://api.sndr.sh/api/cranl/v1/contact-groups/grp_4d8a0c5e-1f7' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Enterprise customers", "description": "Accounts over $10k ARR"}'
```

**Response** (200)

```json
{
  "id":              "grp_4d8a0c5e-1f7",
  "organization_id": "org_8d41c7a2-3f6",
  "name":            "Enterprise customers",
  "slug":            "vip-customers",
  "description":     "Accounts over $10k ARR",
  "member_count":    142,
  "created_at":      "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Delete contact group

> Delete a group and its memberships.

Source: https://sndr.sh/docs/cranl/contact-groups/delete-contact-group

`DELETE https://api.sndr.sh/api/cranl/v1/contact-groups/{id}`

Delete a group and its memberships. The contacts themselves are kept. A group that a broadcast still targets cannot be deleted.

Scope: `send`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/api/cranl/v1/contact-groups/grp_4d8a0c5e-1f7' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "status": "ok"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `group_in_use` (409): A broadcast still targets this group. Delete or retarget the broadcast first.

---

# List group members

> List the contacts in a group, most recently added first.

Source: https://sndr.sh/docs/cranl/contact-groups/list-group-members

`GET https://api.sndr.sh/api/cranl/v1/contact-groups/{id}/members`

List the contacts in a group, most recently added first. Offset-paginated; total is the group size. An unknown group returns an empty list.

Scope: `read`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Query parameters**

- `limit` (integer): Page size. Default 50, max 500 (larger values fall back to 50).
- `offset` (integer): Number of rows to skip. Default 0.

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/contact-groups/grp_4d8a0c5e-1f7/members?limit=50&offset=0' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "con_0e6b7f21-c58",
      "organization_id": "org_8d41c7a2-3f6",
      "email":           "jane@example.com",
      "first_name":      "Jane",
      "last_name":       "Doe",
      "attributes":      { "plan": "pro" },
      "status":          "subscribed",
      "source":          "checkout",
      "created_at":      "2026-03-01T10:00:00Z",
      "updated_at":      "2026-03-01T10:00:00Z"
    }
  ],
  "total": 142
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.

---

# Add group members

> Add contacts to a group by ID.

Source: https://sndr.sh/docs/cranl/contact-groups/add-group-members

`POST https://api.sndr.sh/api/cranl/v1/contact-groups/{id}/members`

Add contacts to a group by ID. Contacts already in the group or not in the account are skipped; added counts new memberships only.

Scope: `send`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Body** (JSON)

- `contact_ids` (string[], required): Contact IDs (con_...) to add, at least one.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/contact-groups/grp_4d8a0c5e-1f7/members' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids": ["con_0e6b7f21-c58", "con_71c3b9e4-a02"]}'
```

**Response** (200)

```json
{
  "added": 2
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, or contact_ids is missing or empty.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Remove group members

> Remove contacts from a group.

Source: https://sndr.sh/docs/cranl/contact-groups/remove-group-members

`DELETE https://api.sndr.sh/api/cranl/v1/contact-groups/{id}/members`

Remove contacts from a group. The contacts themselves are kept. IDs that are not members are ignored.

Scope: `send`

**Path parameters**

- `id` (string, required): Group ID (grp_...).

**Body** (JSON)

- `contact_ids` (string[], required): Contact IDs (con_...) to remove, at least one.

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/api/cranl/v1/contact-groups/grp_4d8a0c5e-1f7/members' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids": ["con_0e6b7f21-c58"]}'
```

**Response** (200)

```json
{
  "status": "ok"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, or contact_ids is missing or empty.
- `insufficient_scope` (403): Token is missing the send scope.

---

# Broadcasts

> Create and send bulk email campaigns to contact groups.

Source: https://sndr.sh/docs/cranl/broadcasts

A broadcast sends one email to every subscribed contact in a contact group. Create it as a draft, edit it while it is a draft, then call the send endpoint to queue it for immediate delivery.

> **Warning:** Only drafts can be edited or deleted. After the send call the status moves queued → sending → sent. Each recipient goes through POST /send, so domain verification, suppressions and the monthly email quota apply per recipient.

- [List broadcasts](https://sndr.sh/docs/cranl/broadcasts/list-broadcasts) `GET /api/cranl/v1/broadcasts`: List broadcasts on the connected account, newest first.
- [Create broadcast](https://sndr.sh/docs/cranl/broadcasts/create-broadcast) `POST /api/cranl/v1/broadcasts`: Create a draft broadcast.
- [Get broadcast](https://sndr.sh/docs/cranl/broadcasts/get-broadcast) `GET /api/cranl/v1/broadcasts/{id}`: Retrieve one broadcast with its body and send progress (total_recipients, sent_count, failed_count).
- [Update broadcast](https://sndr.sh/docs/cranl/broadcasts/update-broadcast) `PATCH /api/cranl/v1/broadcasts/{id}`: Update a draft broadcast.
- [Delete broadcast](https://sndr.sh/docs/cranl/broadcasts/delete-broadcast) `DELETE /api/cranl/v1/broadcasts/{id}`: Delete a draft broadcast.
- [Send broadcast](https://sndr.sh/docs/cranl/broadcasts/send-broadcast) `POST /api/cranl/v1/broadcasts/{id}/send`: Queue a draft for immediate delivery to the group’s currently subscribed contacts.
- [List broadcast recipients](https://sndr.sh/docs/cranl/broadcasts/list-broadcast-recipients) `GET /api/cranl/v1/broadcasts/{id}/recipients`: List per-recipient delivery rows in queue order.

---

# List broadcasts

> List broadcasts on the connected account, newest first.

Source: https://sndr.sh/docs/cranl/broadcasts/list-broadcasts

`GET https://api.sndr.sh/api/cranl/v1/broadcasts`

List broadcasts on the connected account, newest first. Cursor-paginated. status is draft, queued, sending or sent.

Scope: `read`

**Query parameters**

- `limit` (integer): Page size. Default 50, max 200.
- `cursor` (string): The next_cursor value from the previous page. Omit for the first page.

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/broadcasts' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":               "bca_9b3e6d12-a40",
      "organization_id":  "org_8d41c7a2-3f6",
      "name":             "June newsletter",
      "group_id":         "grp_4d8a0c5e-1f7",
      "from_email":       "hello@acme.com",
      "subject":          "June product update",
      "html":             "<h1>June update</h1><p>Here is what is new.</p>",
      "status":           "sent",
      "total_recipients": 4200,
      "sent_count":       4188,
      "failed_count":     12,
      "created_at":       "2026-05-28T14:00:00Z",
      "started_at":       "2026-06-01T09:00:00Z",
      "completed_at":     "2026-06-01T09:42:10Z"
    }
  ],
  "has_more": false,
  "count":    1,
  "limit":    50
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `validation_failed` (422): limit is above 200, or cursor is not a value returned as next_cursor.

---

# Create broadcast

> Create a draft broadcast.

Source: https://sndr.sh/docs/cranl/broadcasts/create-broadcast

`POST https://api.sndr.sh/api/cranl/v1/broadcasts`

Create a draft broadcast. Returns 201 with the broadcast. The from domain is not checked here; if it is not verified, every recipient fails at send time.

Scope: `send`

**Body** (JSON)

- `name` (string, required): Internal campaign name, 1–120 characters.
- `group_id` (string, required): Contact group to send to (grp_...). Must belong to the connected account.
- `from_email` (string, required): Sender, as an address or "Name <address>", on a verified domain.
- `subject` (string, required): Subject line, 1–500 characters.
- `html` (string): HTML body. Required unless text or template_id is set. {{email}}, {{first_name}}, {{last_name}} and any contact attribute (e.g. {{plan}}) are filled in per recipient.
- `text` (string): Plain-text body.
- `template_id` (string): Saved template (tpl_...) whose html and text are used when the broadcast has no body.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/broadcasts' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "name":       "June newsletter",
    "group_id":   "grp_4d8a0c5e-1f7",
    "from_email": "Acme <hello@acme.com>",
    "subject":    "June product update",
    "html":       "<h1>June update</h1><p>Here is what is new.</p>"
  }'
```

**Response** (201)

```json
{
  "id":               "bca_9b3e6d12-a40",
  "organization_id":  "org_8d41c7a2-3f6",
  "name":             "June newsletter",
  "group_id":         "grp_4d8a0c5e-1f7",
  "from_email":       "\"Acme\" <hello@acme.com>",
  "subject":          "June product update",
  "html":             "<h1>June update</h1><p>Here is what is new.</p>",
  "status":           "draft",
  "total_recipients": 0,
  "sent_count":       0,
  "failed_count":     0,
  "created_at":       "2026-06-01T12:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `insufficient_scope` (403): Token is missing the send scope.
- `validation_failed` (422): A required field is missing or too long, from_email is invalid, there is no body or template, or group_id is not in this account.

---

# Get broadcast

> Retrieve one broadcast with its body and send progress (total_recipients, sent_count, failed_count).

Source: https://sndr.sh/docs/cranl/broadcasts/get-broadcast

`GET https://api.sndr.sh/api/cranl/v1/broadcasts/{id}`

Retrieve one broadcast with its body and send progress (total_recipients, sent_count, failed_count).

Scope: `read`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/broadcasts/bca_9b3e6d12-a40' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "id":               "bca_9b3e6d12-a40",
  "organization_id":  "org_8d41c7a2-3f6",
  "name":             "June newsletter",
  "group_id":         "grp_4d8a0c5e-1f7",
  "from_email":       "hello@acme.com",
  "subject":          "June product update",
  "html":             "<h1>June update</h1><p>Here is what is new.</p>",
  "status":           "sending",
  "total_recipients": 4200,
  "sent_count":       1630,
  "failed_count":     4,
  "created_at":       "2026-05-28T14:00:00Z",
  "started_at":       "2026-06-01T09:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Update broadcast

> Update a draft broadcast.

Source: https://sndr.sh/docs/cranl/broadcasts/update-broadcast

`PATCH https://api.sndr.sh/api/cranl/v1/broadcasts/{id}`

Update a draft broadcast. Send only the fields to change; it returns the updated broadcast.

Scope: `send`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Body** (JSON)

- `name` (string): New internal name, 1–120 characters.
- `group_id` (string): New target group (grp_...).
- `from_email` (string): New sender, as an address or "Name <address>".
- `subject` (string): New subject line, 1–500 characters.
- `template_id` (string): New template ID (tpl_...).
- `html` (string): New HTML body.
- `text` (string): New plain-text body.

**Request**

```bash
curl -X PATCH 'https://api.sndr.sh/api/cranl/v1/broadcasts/bca_9b3e6d12-a40' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"subject": "June product update: highlights"}'
```

**Response** (200)

```json
{
  "id":               "bca_9b3e6d12-a40",
  "organization_id":  "org_8d41c7a2-3f6",
  "name":             "June newsletter",
  "group_id":         "grp_4d8a0c5e-1f7",
  "from_email":       "hello@acme.com",
  "subject":          "June product update: highlights",
  "html":             "<h1>June update</h1><p>Here is what is new.</p>",
  "status":           "draft",
  "total_recipients": 0,
  "sent_count":       0,
  "failed_count":     0,
  "created_at":       "2026-05-28T14:00:00Z"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, has an unknown field, or a field has the wrong type.
- `not_editable` (400): The broadcast is no longer a draft.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `validation_failed` (422): name or subject is empty or too long, or from_email is invalid.

---

# Delete broadcast

> Delete a draft broadcast.

Source: https://sndr.sh/docs/cranl/broadcasts/delete-broadcast

`DELETE https://api.sndr.sh/api/cranl/v1/broadcasts/{id}`

Delete a draft broadcast. Broadcasts past draft cannot be deleted.

Scope: `send`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/api/cranl/v1/broadcasts/bca_9b3e6d12-a40' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "status": "ok"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): The broadcast does not exist or is no longer a draft.

---

# Send broadcast

> Queue a draft for immediate delivery to the group’s currently subscribed contacts.

Source: https://sndr.sh/docs/cranl/broadcasts/send-broadcast

`POST https://api.sndr.sh/api/cranl/v1/broadcasts/{id}/send`

Queue a draft for immediate delivery to the group’s currently subscribed contacts. Takes no body; scheduling is not supported. recipients is the number of contacts queued.

Scope: `send`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/broadcasts/bca_9b3e6d12-a40/send' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "status":     "queued",
  "recipients": 4200
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `empty_audience` (400): The group has no subscribed contacts. The broadcast stays in draft, so add contacts and send it again.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `cannot_queue` (409): The broadcast is not a draft.

---

# List broadcast recipients

> List per-recipient delivery rows in queue order.

Source: https://sndr.sh/docs/cranl/broadcasts/list-broadcast-recipients

`GET https://api.sndr.sh/api/cranl/v1/broadcasts/{id}/recipients`

List per-recipient delivery rows in queue order. Offset-paginated; status is pending, sending, sent or failed, and email_id links to GET /emails/{id}. An unknown broadcast returns an empty list.

Scope: `read`

**Path parameters**

- `id` (string, required): Broadcast ID (bca_...).

**Query parameters**

- `limit` (integer): Page size. Default 50, max 500 (larger values fall back to 50).
- `offset` (integer): Number of rows to skip. Default 0.

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/broadcasts/bca_9b3e6d12-a40/recipients?limit=50&offset=0' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":           "br_7f2c9a41e8d0",
      "broadcast_id": "bca_9b3e6d12-a40",
      "contact_id":   "con_0e6b7f21-c58",
      "email":        "jane@example.com",
      "variables":    {},
      "email_id":     "em_d2a8f6c1-3b9",
      "status":       "sent",
      "sent_at":      "2026-06-01T09:01:12Z",
      "created_at":   "2026-06-01T09:00:00Z"
    }
  ],
  "total": 4200
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.

---

# Webhooks

> Register HTTP endpoints that receive real-time email events.

Source: https://sndr.sh/docs/cranl/webhooks

Webhooks POST a JSON event to your HTTPS endpoint when an email’s status changes. Respond with a 2xx within 10 seconds; other responses are retried, up to 12 attempts in total. Every request is signed with HMAC-SHA256 so you can verify it came from SNDR.

## Signature verification

Each request carries X-Sndr-Signature: t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of "<t>.<raw body>", keyed with the webhook secret. While a staged key exists, a second signature v1s is added; accept the request if any signature matches.

```js
const crypto = require('crypto')

// header  = req.headers['x-sndr-signature']
// rawBody = raw request body as a string, before JSON.parse
function verifySignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false
  const expected = crypto.createHmac('sha256', secret)
    .update(parts.t + '.' + rawBody)
    .digest('hex')
  return Object.entries(parts).some(([key, sig]) =>
    key.startsWith('v1') &&
    sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
}
```

## Event payload

```json
{
  "id":         "evt_5c1e9a7b-2d4",
  "type":       "email.delivered",
  "created_at": "2026-06-01T12:00:04Z",
  "data": {
    "email_id": "em_3f9c1a2b-7d4",
    "to":       ["customer@example.com"]
  }
}
```

email.bounced and email.failed events carry data.email_id and data.error instead of data.to.

## Supported events

- email.delivered — the receiving mail server accepted the email.
- email.bounced — the recipient address was rejected as invalid (hard bounce).
- email.failed — delivery failed for another reason.
- email.unsubscribed — a recipient unsubscribed using the link in an email.
- email.queued and email.complained — accepted when subscribing, but not currently sent.

- [List webhooks](https://sndr.sh/docs/cranl/webhooks/list-webhooks) `GET /api/cranl/v1/webhooks`: List all webhooks on the connected account.
- [Create webhook](https://sndr.sh/docs/cranl/webhooks/create-webhook) `POST /api/cranl/v1/webhooks`: Register a webhook.
- [Delete webhook](https://sndr.sh/docs/cranl/webhooks/delete-webhook) `DELETE /api/cranl/v1/webhooks/{id}`: Delete a webhook.
- [List signing keys](https://sndr.sh/docs/cranl/webhooks/list-signing-keys) `GET /api/cranl/v1/webhooks/{id}/signing-keys`: List the webhook’s rotation keys (status primary, secondary or retired) without secrets.
- [Stage signing key](https://sndr.sh/docs/cranl/webhooks/stage-signing-key) `POST /api/cranl/v1/webhooks/{id}/signing-keys/stage`: Create a secondary key and return its secret once.
- [Promote signing key](https://sndr.sh/docs/cranl/webhooks/promote-signing-key) `POST /api/cranl/v1/webhooks/{id}/signing-keys/{key_id}/promote`: Make a secondary key the primary.
- [Retire signing key](https://sndr.sh/docs/cranl/webhooks/retire-signing-key) `POST /api/cranl/v1/webhooks/{id}/signing-keys/{key_id}/retire`: Retire a secondary key without promoting it.

---

# List webhooks

> List all webhooks on the connected account.

Source: https://sndr.sh/docs/cranl/webhooks/list-webhooks

`GET https://api.sndr.sh/api/cranl/v1/webhooks`

List all webhooks on the connected account. Secrets are not returned; secret_prefix shows which secret a webhook was created with.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/webhooks' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "id":              "wh_2a7d4e9c-6b1",
      "organization_id": "org_8d41c7a2-3f6",
      "url":             "https://your-app.com/webhooks/sndr",
      "events":          ["email.delivered", "email.bounced", "email.failed"],
      "secret_prefix":   "whsec_Xk9pQ2",
      "active":          true,
      "created_at":      "2026-03-10T10:00:00Z"
    }
  ],
  "has_more": false,
  "count":    1,
  "limit":    1
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.

---

# Create webhook

> Register a webhook.

Source: https://sndr.sh/docs/cranl/webhooks/create-webhook

`POST https://api.sndr.sh/api/cranl/v1/webhooks`

Register a webhook. Returns 201 with the webhook and its signing secret. This is the only time the full secret is shown, so store it now.

Scope: `send`

**Body** (JSON)

- `url` (string, required): Public HTTPS URL. Hosts that resolve to private, loopback or link-local addresses are rejected.
- `events` (string[], required): Events to receive, at least one of: email.delivered, email.bounced, email.failed, email.unsubscribed (email.queued and email.complained are accepted but not sent).

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/webhooks' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "url":    "https://your-app.com/webhooks/sndr",
    "events": ["email.delivered", "email.bounced", "email.failed"]
  }'
```

**Response** (201)

```json
{
  "id":              "wh_2a7d4e9c-6b1",
  "organization_id": "org_8d41c7a2-3f6",
  "url":             "https://your-app.com/webhooks/sndr",
  "events":          ["email.delivered", "email.bounced", "email.failed"],
  "secret_prefix":   "whsec_Xk9pQ2",
  "active":          true,
  "created_at":      "2026-06-01T12:00:00Z",
  "secret":          "Xk9pQ2vLr8TzW4mN1bYcE7hJ0aSdFgUi"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, url is missing or not a URL, or an event name is not supported.
- `plan_limit_reached` (402): The plan’s webhook limit is reached.
- `insufficient_scope` (403): Token is missing the send scope.
- `validation_failed` (422): url is not https, cannot be resolved, or points at a private address.

---

# Delete webhook

> Delete a webhook.

Source: https://sndr.sh/docs/cranl/webhooks/delete-webhook

`DELETE https://api.sndr.sh/api/cranl/v1/webhooks/{id}`

Delete a webhook. No further events are sent to its URL.

Scope: `send`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/api/cranl/v1/webhooks/wh_2a7d4e9c-6b1' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (204)

No content.

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# List signing keys

> List the webhook’s rotation keys (status primary, secondary or retired) without secrets.

Source: https://sndr.sh/docs/cranl/webhooks/list-signing-keys

`GET https://api.sndr.sh/api/cranl/v1/webhooks/{id}/signing-keys`

List the webhook’s rotation keys (status primary, secondary or retired) without secrets. A new webhook has no rows until you stage a key; its creation secret signs as primary until then.

Scope: `read`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/webhooks/wh_2a7d4e9c-6b1/signing-keys' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "webhook_id":  "wh_2a7d4e9c-6b1",
  "webhook_url": "https://your-app.com/webhooks/sndr",
  "data": [
    {
      "id":              "whk_61d0a9c7-5e4",
      "webhook_id":      "wh_2a7d4e9c-6b1",
      "status":          "secondary",
      "created_at":      "2026-06-01T13:00:00Z",
      "created_by":      "usr_5b2f8c1e-9a3",
      "rotation_reason": "scheduled rotation"
    }
  ],
  "count": 1
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Stage signing key

> Create a secondary key and return its secret once.

Source: https://sndr.sh/docs/cranl/webhooks/stage-signing-key

`POST https://api.sndr.sh/api/cranl/v1/webhooks/{id}/signing-keys/stage`

Create a secondary key and return its secret once. Events are signed with both keys (v1 and v1s) until you promote or retire it. The body is optional.

Scope: `send`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).

**Body** (JSON)

- `reason` (string): Short label stored with the key. Defaults to customer.
- `notes` (string): Optional free-form note.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/webhooks/wh_2a7d4e9c-6b1/signing-keys/stage' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "scheduled rotation"}'
```

**Response** (201)

```json
{
  "id":              "whk_61d0a9c7-5e4",
  "webhook_id":      "wh_2a7d4e9c-6b1",
  "status":          "secondary",
  "created_at":      "2026-06-01T13:00:00Z",
  "created_by":      "usr_5b2f8c1e-9a3",
  "rotation_reason": "scheduled rotation",
  "secret":          "Qm3vT8xZ1cR6yH0nB5wL9kD2fJ7sA4gP"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is missing or not valid JSON (send {} for the defaults).
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.

---

# Promote signing key

> Make a secondary key the primary.

Source: https://sndr.sh/docs/cranl/webhooks/promote-signing-key

`POST https://api.sndr.sh/api/cranl/v1/webhooks/{id}/signing-keys/{key_id}/promote`

Make a secondary key the primary. The previous primary is retired at once, so update your receiver to the new secret first.

Scope: `send`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).
- `key_id` (string, required): Secondary key ID (whk_...) from the stage call.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/webhooks/wh_2a7d4e9c-6b1/signing-keys/whk_61d0a9c7-5e4/promote' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "id":     "whk_61d0a9c7-5e4",
  "status": "primary"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `conflict` (409): The key is not a secondary key.

---

# Retire signing key

> Retire a secondary key without promoting it.

Source: https://sndr.sh/docs/cranl/webhooks/retire-signing-key

`POST https://api.sndr.sh/api/cranl/v1/webhooks/{id}/signing-keys/{key_id}/retire`

Retire a secondary key without promoting it. The primary key cannot be retired; promote a replacement instead.

Scope: `send`

**Path parameters**

- `id` (string, required): Webhook ID (wh_...).
- `key_id` (string, required): Secondary key ID (whk_...).

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/webhooks/wh_2a7d4e9c-6b1/signing-keys/whk_61d0a9c7-5e4/retire' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "id":     "whk_61d0a9c7-5e4",
  "status": "retired"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.
- `not_found` (404): Resource does not exist or belongs to a different account.
- `conflict` (409): The key is not a secondary key (it is the primary or already retired).

---

# Suppressions

> Manage the suppression list that blocks emails to specific addresses.

Source: https://sndr.sh/docs/cranl/suppressions

SNDR does not send to suppressed addresses. Addresses are added automatically on hard bounces and one-click unsubscribes. You can also add them yourself (e.g. opt-outs collected elsewhere) or remove one that was added in error.

> **Warning:** Removing a suppression for an address that hard-bounced or complained may harm your sender reputation. Only remove suppressions you are confident are safe.

- [List suppressions](https://sndr.sh/docs/cranl/suppressions/list-suppressions) `GET /api/cranl/v1/suppressions`: List every suppressed address on the connected account, newest first.
- [Add suppression](https://sndr.sh/docs/cranl/suppressions/add-suppression) `POST /api/cranl/v1/suppressions`: Suppress an address, e.g.
- [Remove suppression](https://sndr.sh/docs/cranl/suppressions/remove-suppression) `DELETE /api/cranl/v1/suppressions/{addr}`: Remove an address so emails to it are attempted again.

---

# List suppressions

> List every suppressed address on the connected account, newest first.

Source: https://sndr.sh/docs/cranl/suppressions/list-suppressions

`GET https://api.sndr.sh/api/cranl/v1/suppressions`

List every suppressed address on the connected account, newest first. Not paginated. reason is bounce, unsubscribe, manual, or the value set when it was added.

Scope: `read`

**Request**

```bash
curl 'https://api.sndr.sh/api/cranl/v1/suppressions' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (200)

```json
{
  "data": [
    {
      "organization_id": "org_8d41c7a2-3f6",
      "address":         "hard-bounce@example.com",
      "reason":          "bounce",
      "detail":          "550 5.1.1 user unknown",
      "created_at":      "2026-05-15T10:30:00Z"
    },
    {
      "organization_id": "org_8d41c7a2-3f6",
      "address":         "optout@example.com",
      "reason":          "manual",
      "created_at":      "2026-05-10T08:00:00Z"
    }
  ]
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the read scope.

---

# Add suppression

> Suppress an address, e.g.

Source: https://sndr.sh/docs/cranl/suppressions/add-suppression

`POST https://api.sndr.sh/api/cranl/v1/suppressions`

Suppress an address, e.g. an opt-out collected outside SNDR. Returns 201; an address that is already suppressed keeps its original reason.

Scope: `send`

**Body** (JSON)

- `address` (string, required): Email address to suppress. Stored lowercase.
- `reason` (string): Why it is suppressed. Defaults to manual.
- `detail` (string): Optional note shown in the list.

**Request**

```bash
curl -X POST 'https://api.sndr.sh/api/cranl/v1/suppressions' \
  -H 'Authorization: Bearer sndr_your_access_token' \
  -H 'Content-Type: application/json' \
  -d '{"address": "optout@example.com", "detail": "Unsubscribed via support ticket"}'
```

**Response** (201)

```json
{
  "address": "optout@example.com",
  "reason":  "manual"
}
```

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `invalid_request` (400): Body is not valid JSON, or address is missing or not an email.
- `insufficient_scope` (403): Token is missing the send scope.

---

# Remove suppression

> Remove an address so emails to it are attempted again.

Source: https://sndr.sh/docs/cranl/suppressions/remove-suppression

`DELETE https://api.sndr.sh/api/cranl/v1/suppressions/{addr}`

Remove an address so emails to it are attempted again. Returns 204 even if the address was not suppressed.

Scope: `send`

**Path parameters**

- `addr` (string, required): The email address, e.g. optout@example.com. A percent-encoded @ (%40) works too.

**Request**

```bash
curl -X DELETE 'https://api.sndr.sh/api/cranl/v1/suppressions/optout@example.com' \
  -H 'Authorization: Bearer sndr_your_access_token'
```

**Response** (204)

No content.

**Errors**

- `unauthenticated` (401): Missing or invalid Bearer token.
- `token_expired` (401): Access token expired — exchange the refresh token for a new pair.
- `token_revoked` (401): Token was explicitly revoked.
- `insufficient_scope` (403): Token is missing the send scope.

---

# Error codes

> Every error code returned by the Partner API and how to handle it.

Source: https://sndr.sh/docs/cranl/errors

All errors use a consistent JSON envelope (the only exception is the per-IP rate limit, which returns a plain-text 429):

```json
{
  "error": {
    "code":       "invalid_grant",
    "message":    "Authorization code has already been used",
    "request_id": "req_01HXKQ8B3N",
    "docs_url":   "https://docs.sndr.sh/errors/invalid_grant"
  }
}
```

Include request_id in any support request — it links the failure to server-side logs. Validation errors also carry field (one input) or fields (a map of input to message).

## OAuth errors

- invalid_client (401) — Unknown or inactive client_id, or wrong client_secret.
- invalid_grant (400) — Auth code expired (10 min TTL), already used, PKCE mismatch, or refresh token invalid.
- invalid_scope (400) — Scope not in the app's scopes_allowed list.
- access_denied — User clicked Deny (redirect parameter, not a JSON body). Restart the flow if the user changes their mind.
- unsupported_grant_type (400) — Only authorization_code and refresh_token are accepted.
- invalid_request (400) — Missing required parameter or malformed body.

## Resource errors

- unauthenticated (401) — Missing Authorization header, or the Bearer token is unknown.
- token_expired (401) — Access token passed its 1-hour TTL. Exchange the refresh token.
- token_revoked (401) — Token was explicitly revoked or the user disconnected the integration.
- insufficient_scope (403) — Token lacks the required scope (read or send).
- not_found (404) — Resource does not exist or belongs to a different account.
- invalid_request (400) — Body is not valid JSON, has an unknown field or a wrong type, or a send request failed validation. The message gives the detail.
- validation_failed (422) — A field failed validation; field or fields names the input. Also returned for a bad limit or cursor.
- conflict (409) — Duplicate resource (e.g. contact email or domain already exists) or an invalid signing-key transition.
- name_taken (409) — A contact group with the same name already exists.
- chunk_too_large (400) — More than 500 contacts in one bulk import.
- suppressed (400) — Every to address of a send is on the suppression list.
- domain_not_linked (403) / domain_not_verified (403) — The from domain is not added, or not verified yet.
- quarantine_active (403) — Sending is paused for this account. Contact SNDR support.
- not_editable (400) — Tried to edit a broadcast that is no longer a draft.
- cannot_queue (409) — Tried to send a broadcast that is not a draft.
- empty_audience (400) — The broadcast’s group has no subscribed contacts.
- plan_limit_reached (402) — A plan cap (domains, templates, webhooks) is reached. Send the user to upgrade_url from GET /me.
- quota_exceeded (402) — The monthly email quota is used up. It resets on the 1st of the month (UTC).
- payload_too_large (413) — A send request is over 16 MiB.
- send_velocity (429) — Sending too fast for this account. Back off and retry.
- 429 with a plain-text body — Per-IP rate limit. Wait for the Retry-After header.
- sends_frozen (503) — Sending is temporarily paused platform-wide. Retry later.
- server_error / internal (500) — Internal error. Retry with exponential backoff and quote request_id.

## Retry strategy

- 401 token_expired — Refresh once, then retry the original request.
- 429 (rate limit or send_velocity) — Wait for the Retry-After duration (or back off), then retry.
- 402 quota_exceeded / plan_limit_reached — Do not retry. The email quota resets on the 1st (UTC); plan caps need an upgrade.
- 500 / 503 — Retry with exponential backoff: 1s → 2s → 4s → 8s → stop after 5 attempts. Send an Idempotency-Key on POST /send so a retry never sends twice.
- All other 4xx — Fix the request; do not retry.

> **Note:** POST /api/cranl/oauth/revoke always returns 200 OK per RFC 7009 — even for unknown or already-revoked tokens.