Create Preview Run
Render this template’s email content on each of the requested devices.
Returns as soon as the run exists and its render is queued — the screenshots are produced asynchronously. Poll GET /notifications/{id}/previews/runs/{previewRunId} until every result reaches a terminal status.
Name the devices either with device_set_id, for a saved set, or with device_ids, for a one-off list. Exactly one of the two is required. Inline device_ids must be ids listed by GET /previews/devices; any other id is a 422, refused before the run exists or is billed.
A template that does not exist is a 404. One that exists but cannot be previewed — not a Design Studio template, no email channel, or no such template_version — is a 422, also refused before the run exists or is billed.
Preview runs are a metered add-on. A workspace without it, or with its billing suspended, receives a 402.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
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.
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
Template ID (nt_ prefix). Must be a Design Studio template.
Body
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.
A saved device set naming the devices to render on. Mutually exclusive with device_ids.
The devices to render on, by PreviewDevice.id, for a one-off run. Mutually exclusive with device_set_id.
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.
"draft"
Render the template's content for this locale, e.g. "fr-FR".
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.
Unique identifier for the preview run.
The template that was rendered.
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.
PENDING, RENDERED, SUBMITTED, COMPLETED, FAILED The devices this run was submitted for, snapshotted when the run was created.
ISO-8601 timestamp of when the run was created.
The version of the template that was rendered — draft, or a zero-padded published version such as v002. Absent until the render settles.
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.
TEMPLATE_NOT_SUPPORTED, NO_EMAIL_CHANNEL, RENDER_FAILED, ALL_DEVICES_UNSUPPORTED, VENDOR_ERROR