# templates.send

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.

```ts
openemail.templates.send(
  accountId: string,
  slug: string,
  body: TemplatesSendBody,
  options?: TemplatesSendOptions,
): ApiPromise<MailTemplateSend>
```

It calls `POST /accounts/{accountId}/templates/{slug}/send`: [Send a template to one or more recipients](/docs/api/templates/post_TemplateSend) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `accountId` | `string` | Account ULID identifier.. The path's `{accountId}`. |
| `slug` | `string` | The template's name within this account.. The path's `{slug}`. |
| `body` | [`TemplatesSendBody`](#templatessendbody) | The request's body. |

## Options

The last argument, `options`, a `TemplatesSendOptions`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `deliveryId` | `string` | header `x-delivery-id` | 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. |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`MailTemplateSend`](/docs/sdks/typescript/types/mail-template-send). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Retries

When a call gives no `deliveryId` (the `x-delivery-id` header), the client makes one, the same for each of the call's retries, so it is retried like a read: the API converges on one send. Give your own to make your own retries safe too ([retries and idempotent sends](/docs/sdks/typescript/errors#retries-and-idempotent-sends)).

## Errors

| Status | What it means |
| --- | --- |
| `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 |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | sending_disabled: the account's From is frozen |
| `404` | not_found, including a sender mailbox torn down before the first message (a later recipient's row says mailbox_gone instead) |
| `411` | length_required: Content-Length is required |
| `413` | too_large: the JSON body exceeds 2 MiB |
| `429` | sending_paused or rate_limited on the first message, with Retry-After: nothing was sent, retry the whole call |
| `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) |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### TemplatesSendBody

```ts
/** The body of `templates.send`. */
type TemplatesSendBody = {
  bounce?: boolean
  /** 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. */
  headers?: Record<string, string>
  /** Language tag, e.g. `en` or `de-AT`. Stored lowercased. */
  lang?: string | null
  replyTo?: string | null
  /** Keep a Sent copy. Default FALSE here, unlike /send. */
  save?: boolean
  /** One message is built per entry, and an address may appear once. No cc or bcc: personalisation makes shared bytes meaningless. */
  to: TemplatesSendBodyToItem[]
  vars?: Record<string, string | number | boolean | null>
}
```

### TemplatesSendBodyToItem

```ts
/** The API's `TemplatesSendBodyToItem`, as the document describes it. */
type TemplatesSendBodyToItem = {
  email: string
  name?: string | null
  vars?: Record<string, string | number | boolean | null>
}
```

It names these types of the API, each on a page of its own: [`MailTemplateSend`](/docs/sdks/typescript/types/mail-template-send).
