Skip to Content

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.

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 in the API reference.

Example

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

Arguments

ArgumentTypeDescription
accountIdstringAccount ULID identifier.. The path's {accountId}.
slugstringThe template's name within this account.. The path's {slug}.
bodyTemplatesSendBodyThe request's body.

Options

The last argument, options, a TemplatesSendOptions, takes:

OptionTypeSent asDescription
deliveryIdstringheader x-delivery-idIdempotency 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).

Answer

Awaited, it is the API's JSON, MailTemplateSend. It is an ApiPromise: .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).

Errors

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

Types

TemplatesSendBody

/** 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

/** 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.