# Send a template to one or more recipients

Renders the template once per recipient, with that recipient's own variables layered over the shared ones, and sends each as its own message, now. There is no `sendAt`: scheduling belongs to the mailbox product, and an unknown key is refused.

## `POST /api/v1/accounts/{accountId}/templates/{slug}/send`

### Path parameters

- `accountId` (string, required) — Account ULID identifier.
- `slug` (string, required, 1–64 chars, pattern `^[a-z0-9][a-z0-9_-]*$`) — The template's name within this account.

### Header parameters

- `x-delivery-id` (string) — Idempotency key. Each recipient's message derives its own from this, the template and the recipient's address, so a retry converges per recipient whatever the order or subset of the list it carries, and the same key used for a different template is a different message. At most 200 characters; `#` is reserved. A retry does not get around a sending hold: while the sender is paused or disabled it is refused like any submission, and once the hold lifts it continues without a second charge.

### Request body (required)

`application/json`

- `to` (object[], required, min 1 items, max 50 items) — One message is built per entry, and an address may appear once. No cc or bcc: personalisation makes shared bytes meaningless.
  - `email` (string <email>, required)
  - `name` (string | null, max 200 chars)
  - `vars` (object)
- `bounce` (boolean)
- `headers` (object) — Extra headers for every message. Auto-Submitted, X-Auto-Response-Suppress and Content-Language are the route's own and are refused in any spelling.
- `lang` (string | null, 2–35 chars, pattern `^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$`) — Language tag, e.g. `en` or `de-AT`. Stored lowercased.
- `replyTo` (string | null, max 320 chars)
- `save` (boolean) — Keep a Sent copy. Default FALSE here, unlike /send.
- `vars` (object)

### Responses

**200** — Every recipient was accepted

`application/json` → MailTemplateSend

- `deliveryId` (string, required) — The batch id; retry with it to converge only the failures
- `langUsed` (string, required)
- `results` (MailTemplateSendRow[], required)
  - `address` (string, required)
  - `deliveryId` (string, required) — This recipient's leg key, the same shape /send answers
  - `status` ("delivered" | "queued" | "filtered" | "failed", required)
  - `error` (string) — Why, when failed. 'sending_paused' and 'sending_disabled' mean a hold on the sender (mailbox, domain or account) landed while the request was running: recipients already handled keep their status and the rest are refused. 'sending_paused' is temporary: retry with the same delivery id once the hold lifts. 'sending_disabled' is permanent. A sending_paused row is temporary even where it carries no `retryAfterSeconds`.
  - `retryAfterSeconds` (integer) — Set on the rows a temporary refusal stopped: retry this recipient after this long
  - `sentCopy` ("saved" | "duplicate" | "over_quota")
- `slug` (string, required)
- `templateVersion` (integer, required)

**207** — Mixed: at least one recipient failed. Retry with the same delivery id to converge only the failures; rows a temporary refusal stopped carry `retryAfterSeconds`, and the response carries `Retry-After`. A hold that lands mid-batch fails the recipient being sent with sending_paused or sending_disabled and refuses the rest

`application/json` → MailTemplateSend

- `deliveryId` (string, required) — The batch id; retry with it to converge only the failures
- `langUsed` (string, required)
- `results` (MailTemplateSendRow[], required)
  - `address` (string, required)
  - `deliveryId` (string, required) — This recipient's leg key, the same shape /send answers
  - `status` ("delivered" | "queued" | "filtered" | "failed", required)
  - `error` (string) — Why, when failed. 'sending_paused' and 'sending_disabled' mean a hold on the sender (mailbox, domain or account) landed while the request was running: recipients already handled keep their status and the rest are refused. 'sending_paused' is temporary: retry with the same delivery id once the hold lifts. 'sending_disabled' is permanent. A sending_paused row is temporary even where it carries no `retryAfterSeconds`.
  - `retryAfterSeconds` (integer) — Set on the rows a temporary refusal stopped: retry this recipient after this long
  - `sentCopy` ("saved" | "duplicate" | "over_quota")
- `slug` (string, required)
- `templateVersion` (integer, required)

**400** — missing_variable, rendered_too_large, rendered_subject_too_long or template_invalid (refused before ANY recipient is touched: one template serves the whole batch, so a render fault is one cause and not fifty failures), duplicate_recipient, reserved_header, no_variant_for_language, from_not_sendable, reserved_delivery_id, delivery_id_too_long, validation_failed for an unknown key, or the first message's own refusal as /send answers it

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**403** — sending_disabled: the account's From is frozen

`application/json` → ErrorBody

**404** — not_found, including a sender mailbox torn down before the first message (a later recipient's row says mailbox_gone instead)

`application/json` → ErrorBody

**411** — length_required: Content-Length is required

`application/json` → ErrorBody

**413** — too_large: the JSON body exceeds 2 MiB

`application/json` → ErrorBody

**429** — sending_paused or rate_limited on the first message, with Retry-After: nothing was sent, retry the whole call

`application/json` → ErrorBody

**503** — mailbox_closing or mailbox_reopening on the first message, with Retry-After: retry the whole call. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X POST 'https://api.open.email/api/v1/accounts/{accountId}/templates/{slug}/send' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": [
      {
        "email": "user@example.com"
      }
    ]
  }'
```

## TypeScript SDK

[`openemail.templates.send`](/docs/sdks/typescript/templates/send)

```ts
const mailTemplateSend = await openemail.templates.send(accountId, slug, { to: [{ email: 'ada@example.com' }] })
```
