Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

A unique key that makes this request idempotent. If Courier receives another request with the same Idempotency-Key, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry POST requests after network failures without risking duplicate sends. The key is scoped to this endpoint.

x-idempotency-expiration
string

How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when Idempotency-Key is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year.

Path Parameters

id
string
required

Template ID (nt_ prefix). Must be a Design Studio template.

Body

application/json

Request body for creating a preview run of the template in the path. Provide exactly one of device_set_id or device_ids. The template is the path's {id}; a template_id here is an unknown key and a 400.

device_set_id
string

A saved device set naming the devices to render on. Mutually exclusive with device_ids.

device_ids
string[]

The devices to render on, by PreviewDevice.id, for a one-off run. Mutually exclusive with device_set_id.

template_version
string

Which version of the template to render. Omit for the latest saved draft, which always exists and is what the editor shows. published renders the live version; a zero-padded v002 renders that specific publish. Versions are 1-based, so v000 is not a version, and the unpadded v2 is rejected — that spelling belongs to journeys' AutomationVersionId, a different scheme in which v0 means published.

Example:

"draft"

locale
string

Render the template's content for this locale, e.g. "fr-FR".

data
object

Template variables to render with, the same shape as the data object on a send.

Response

Created

One render of a template across a set of devices. Billable.

id
string
required

Unique identifier for the preview run.

template_id
string
required

The template that was rendered.

status
enum<string>
required

Where the run itself has got to. PENDING and RENDERED mean Courier is still preparing the email, SUBMITTED means it is with the rendering service, and COMPLETED means every device has reported. FAILED is the run as a whole failing — an individual device failing never fails the run.

Available options:
PENDING,
RENDERED,
SUBMITTED,
COMPLETED,
FAILED
device_ids
string[]
required

The devices this run was submitted for, snapshotted when the run was created.

created_at
string
required

ISO-8601 timestamp of when the run was created.

template_version
string

The version of the template that was rendered — draft, or a zero-padded published version such as v002. Absent until the render settles.

failure_reason
enum<string>

Why the run failed, when status is FAILED. NO_EMAIL_CHANNEL and TEMPLATE_NOT_SUPPORTED mean there was nothing to render; ALL_DEVICES_UNSUPPORTED means every requested device has been retired and the request can be fixed by choosing others.

Available options:
TEMPLATE_NOT_SUPPORTED,
NO_EMAIL_CHANNEL,
RENDER_FAILED,
ALL_DEVICES_UNSUPPORTED,
VENDOR_ERROR