Device Preview for email

Device Preview renders your template on real email clients and returns a screenshot from each one. Every screenshot comes from the real app, such as Outlook on Windows, not a simulation. You can run a preview two ways:

In the editor: check a template while you design it. Pick a set of clients in Design Studio, run the preview, and fix what breaks before you publish.
With the API: run the same previews from code. An AI agent can preview a template, review the screenshots, and fix what it finds. You can also show the screenshots in your own product, such as next to an email editor your customers use.

Both share the same target sets and history, so a run started from either one shows up in the editor.

A Device Preview run showing one email rendered on Apple Mail, Gmail, and Outlook, in light and dark mode — A Device Preview run across desktop, mobile, and webmail clients

Run a preview in the editor

Open a template in and click the device icon in the toolbar. Previews render whatever is in the editor right now, including unpublished changes. Choose a target set, the group of clients you want to render on. Every workspace starts with Courier Recommended, an 8-client set spanning desktop, mobile, and webmail in both light and dark mode. Build your own from the full catalog. If your template is , choose which translation to render. Set test values for any variables, such as profile.name.

A variable without a test value renders as nothing, so a greeting reads “Hi , your order has shipped.” That’s the most common reason a preview looks broken when the template is fine.

Click Run preview. Screenshots load as they return, and a full run takes 10 to 120 seconds. Outlook clients are often the last to come back.

Review the results

Click a screenshot to open it full size, then use the arrows to move through the run. Download any screenshot from the results page.

Find past runs

Click Preview history for past runs, including runs started from the API. Each shows when it ran, how many clients it covered, and which template version it rendered. Use it to see whether a rendering problem is new or shipped several versions ago.

Build a target set

Create your own target sets to focus on the variations you care about. You might keep one for Outlook versions, another for dark mode across mobile, and a third for the clients most of your users are on. Open the Targets dropdown and click Create new set. Name it, filter the catalog by Mobile, Web, or Application, then add the clients you want. Use the pencil icon to edit a set later. Sets are shared with your workspace and scoped to the you’re in. The API calls them device sets, and calls each client a device.

Run a preview with the API

The API runs the same previews as the editor: start a run on a template, check it until every device has reported, then download the screenshots. The template must be a Design Studio template with an email channel. Runs use the API key’s environment, the same way target sets do.

Start a run

List your device sets with and take the id of the set named Courier Recommended. Every workspace has one, with its own ID in each environment, so look it up by name:

{
  "results": [
    {
      "id": "pvs_01m0g557g5f6fsvbzx13fnk5p3",
      "name": "Courier Recommended",
      "device_ids": [
        "pvd_0rk8bz6ywhbydvhfh6xv0bw8ep",
        "pvd_36m3f6jvvdb5ntjg4ktpwekqws",
        "pvd_6qa25njzggbbbs4kf8azs92qn4",
        "pvd_02h2ecnn2rbgy9x1eptdr0py9z",
        "pvd_5yvs8k8jv9axkv5xsptpd51mvg",
        "pvd_4khhpethbyarsb5z4a354t8er8",
        "pvd_60wzmxv9cjbrbr87w8d7rmrdv9",
        "pvd_4s7rvnng7hbjn8eca8npw4b9pq"
      ],
      "created_at": "2026-08-20T17:58:00.453Z",
      "updated_at": "2026-08-20T17:58:00.453Z"
    }
  ]
}

Start the run with . Send an Idempotency-Key so a retried request returns the same run instead of starting a second one. Use a new key for each run: a repeated key within 25 hours returns the earlier run. Pass test values in data:

data.profile fills {{profile.*}} variables, such as {{profile.name}}.
data.tenant fills {{tenant.*}} variables, such as {{tenant.name}}.
Every other key fills your template’s own data variables, such as order_id.

const run = await client.notifications.previews.runs.create("nt_01m3d2j79dfk1th1a2r7h494ye", {
  device_set_id: "pvs_01m0g557g5f6fsvbzx13fnk5p3",
  data: {
    profile: { name: "Sarah Bennett", email: "sarah@acme-corp.com" },
    tenant: { name: "Acme Corp" },
    order_id: "ORD-1234",
  },
  "Idempotency-Key": "preview-order-shipped-001",
});

console.log(run.id, run.status); // "pvr_...", "PENDING"

run = client.notifications.previews.runs.create(
    id="nt_01m3d2j79dfk1th1a2r7h494ye",
    device_set_id="pvs_01m0g557g5f6fsvbzx13fnk5p3",
    data={
        "profile": {"name": "Sarah Bennett", "email": "sarah@acme-corp.com"},
        "tenant": {"name": "Acme Corp"},
        "order_id": "ORD-1234",
    },
    idempotency_key="preview-order-shipped-001",
)

print(run.id, run.status)  # "pvr_...", "PENDING"

curl -X POST https://api.courier.com/notifications/nt_01m3d2j79dfk1th1a2r7h494ye/previews/runs \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: preview-order-shipped-001" \
  -d '{
    "device_set_id": "pvs_01m0g557g5f6fsvbzx13fnk5p3",
    "data": {
      "profile": { "name": "Sarah Bennett", "email": "sarah@acme-corp.com" },
      "tenant": { "name": "Acme Corp" },
      "order_id": "ORD-1234"
    }
  }'

run = courier.notifications.previews.runs.create(
  "nt_01m3d2j79dfk1th1a2r7h494ye",
  device_set_id: "pvs_01m0g557g5f6fsvbzx13fnk5p3",
  data: {
    profile: {name: "Sarah Bennett", email: "sarah@acme-corp.com"},
    tenant: {name: "Acme Corp"},
    order_id: "ORD-1234"
  },
  idempotency_key: "preview-order-shipped-001"
)

run, err := client.Notifications.Previews.Runs.New(
	context.TODO(),
	"nt_01m3d2j79dfk1th1a2r7h494ye",
	courier.NotificationPreviewRunNewParams{
		CreatePreviewRunRequest: courier.CreatePreviewRunRequestParam{
			DeviceSetID: courier.String("pvs_01m0g557g5f6fsvbzx13fnk5p3"),
			Data: map[string]any{
				"profile":  map[string]any{"name": "Sarah Bennett", "email": "sarah@acme-corp.com"},
				"tenant":   map[string]any{"name": "Acme Corp"},
				"order_id": "ORD-1234",
			},
		},
		IdempotencyKey: courier.String("preview-order-shipped-001"),
	},
)

RunCreateParams params = RunCreateParams.builder()
    .id("nt_01m3d2j79dfk1th1a2r7h494ye")
    .idempotencyKey("preview-order-shipped-001")
    .createPreviewRunRequest(CreatePreviewRunRequest.builder()
        .deviceSetId("pvs_01m0g557g5f6fsvbzx13fnk5p3")
        .data(CreatePreviewRunRequest.Data.builder()
            .putAdditionalProperty("profile", JsonValue.from(java.util.Map.of(
                "name", "Sarah Bennett", "email", "sarah@acme-corp.com")))
            .putAdditionalProperty("tenant", JsonValue.from(java.util.Map.of("name", "Acme Corp")))
            .putAdditionalProperty("order_id", JsonValue.from("ORD-1234"))
            .build())
        .build())
    .build();
PreviewRun run = client.notifications().previews().runs().create(params);

$run = $client->notifications->previews->runs->create(
  'nt_01m3d2j79dfk1th1a2r7h494ye',
  deviceSetID: 'pvs_01m0g557g5f6fsvbzx13fnk5p3',
  data: [
    'profile' => ['name' => 'Sarah Bennett', 'email' => 'sarah@acme-corp.com'],
    'tenant' => ['name' => 'Acme Corp'],
    'order_id' => 'ORD-1234',
  ],
  idempotencyKey: 'preview-order-shipped-001',
);

var run = await client.Notifications.Previews.Runs.Create(new RunCreateParams
{
    ID = "nt_01m3d2j79dfk1th1a2r7h494ye",
    DeviceSetID = "pvs_01m0g557g5f6fsvbzx13fnk5p3",
    Data = new Dictionary<string, JsonElement>
    {
        { "profile", JsonSerializer.SerializeToElement(new { name = "Sarah Bennett", email = "sarah@acme-corp.com" }) },
        { "tenant", JsonSerializer.SerializeToElement(new { name = "Acme Corp" }) },
        { "order_id", JsonSerializer.SerializeToElement("ORD-1234") },
    },
    IdempotencyKey = "preview-order-shipped-001",
});

courier notifications:previews:runs create \
  --api-key "$COURIER_API_KEY" \
  --id nt_01m3d2j79dfk1th1a2r7h494ye \
  --device-set-id pvs_01m0g557g5f6fsvbzx13fnk5p3 \
  --data '{"profile": {"name": "Sarah Bennett", "email": "sarah@acme-corp.com"}, "tenant": {"name": "Acme Corp"}, "order_id": "ORD-1234"}' \
  --idempotency-key preview-order-shipped-001

With Courier MCP, run a device preview of template nt_01m3d2j79dfk1th1a2r7h494ye on the Courier Recommended set, as Sarah Bennett (sarah@acme-corp.com) at Acme Corp with order ORD-1234.

The run comes back right away with status PENDING and the devices it will render on:

{
  "id": "pvr_01m3d2j8zve8nb25sqfmckfc3g",
  "template_id": "nt_01m3d2j79dfk1th1a2r7h494ye",
  "status": "PENDING",
  "device_ids": [
    "pvd_0rk8bz6ywhbydvhfh6xv0bw8ep",
    "pvd_36m3f6jvvdb5ntjg4ktpwekqws",
    "pvd_6qa25njzggbbbs4kf8azs92qn4",
    "pvd_02h2ecnn2rbgy9x1eptdr0py9z",
    "pvd_5yvs8k8jv9axkv5xsptpd51mvg",
    "pvd_4khhpethbyarsb5z4a354t8er8",
    "pvd_60wzmxv9cjbrbr87w8d7rmrdv9",
    "pvd_4s7rvnng7hbjn8eca8npw4b9pq"
  ],
  "created_at": "2026-09-25T20:02:04.411Z"
}

It renders the latest draft unless you pass template_version: published for the live version, or a published version such as v002. A locale renders that translation.

Get the results

A run takes 10 to 120 seconds, and screenshots come back one device at a time. Read the run with every 10 seconds, for up to 5 minutes.

const detail = await client.notifications.previews.runs.retrieve("pvr_01m3d2j8zve8nb25sqfmckfc3g", {
  id: "nt_01m3d2j79dfk1th1a2r7h494ye",
});

console.log(detail.status, detail.results);

detail = client.notifications.previews.runs.retrieve(
    preview_run_id="pvr_01m3d2j8zve8nb25sqfmckfc3g",
    id="nt_01m3d2j79dfk1th1a2r7h494ye",
)

print(detail.status, detail.results)

curl https://api.courier.com/notifications/nt_01m3d2j79dfk1th1a2r7h494ye/previews/runs/pvr_01m3d2j8zve8nb25sqfmckfc3g \
  -H "Authorization: Bearer $COURIER_API_KEY"

detail = courier.notifications.previews.runs.retrieve(
  "pvr_01m3d2j8zve8nb25sqfmckfc3g",
  id: "nt_01m3d2j79dfk1th1a2r7h494ye"
)

detail, err := client.Notifications.Previews.Runs.Get(
	context.TODO(),
	"pvr_01m3d2j8zve8nb25sqfmckfc3g",
	courier.NotificationPreviewRunGetParams{
		ID: "nt_01m3d2j79dfk1th1a2r7h494ye",
	},
)

RunRetrieveParams params = RunRetrieveParams.builder()
    .id("nt_01m3d2j79dfk1th1a2r7h494ye")
    .previewRunId("pvr_01m3d2j8zve8nb25sqfmckfc3g")
    .build();
PreviewRunDetail detail = client.notifications().previews().runs().retrieve(params);

$detail = $client->notifications->previews->runs->retrieve(
  'pvr_01m3d2j8zve8nb25sqfmckfc3g',
  id: 'nt_01m3d2j79dfk1th1a2r7h494ye',
);

var detail = await client.Notifications.Previews.Runs.Retrieve(new RunRetrieveParams
{
    ID = "nt_01m3d2j79dfk1th1a2r7h494ye",
    PreviewRunID = "pvr_01m3d2j8zve8nb25sqfmckfc3g",
});

courier notifications:previews:runs retrieve \
  --api-key "$COURIER_API_KEY" \
  --id nt_01m3d2j79dfk1th1a2r7h494ye \
  --preview-run-id pvr_01m3d2j8zve8nb25sqfmckfc3g

With Courier MCP, get preview run pvr_01m3d2j8zve8nb25sqfmckfc3g for template nt_01m3d2j79dfk1th1a2r7h494ye and show me each device's screenshot.

Each device has its own entry in results, in no fixed order, so match entries by device_id. A finished device carries a screenshot_url and a thumbnail_url, and one still rendering has both set to null. This run was read partway through, with 2 of its 8 results shown:

{
  "id": "pvr_01m3d2j8zve8nb25sqfmckfc3g",
  "template_id": "nt_01m3d2j79dfk1th1a2r7h494ye",
  "template_version": "draft",
  "status": "SUBMITTED",
  "device_ids": [
    "pvd_0rk8bz6ywhbydvhfh6xv0bw8ep",
    "pvd_36m3f6jvvdb5ntjg4ktpwekqws",
    "pvd_6qa25njzggbbbs4kf8azs92qn4",
    "pvd_02h2ecnn2rbgy9x1eptdr0py9z",
    "pvd_5yvs8k8jv9axkv5xsptpd51mvg",
    "pvd_4khhpethbyarsb5z4a354t8er8",
    "pvd_60wzmxv9cjbrbr87w8d7rmrdv9",
    "pvd_4s7rvnng7hbjn8eca8npw4b9pq"
  ],
  "created_at": "2026-09-25T20:02:04.411Z",
  "results": [
    {
      "device_id": "pvd_4khhpethbyarsb5z4a354t8er8",
      "status": "COMPLETED",
      "thumbnail_url": "https://….s3.us-east-1.amazonaws.com/…/thumbnail.png?X-Amz-…",
      "screenshot_url": "https://….s3.us-east-1.amazonaws.com/…/default.png?X-Amz-…"
    },
    {
      "device_id": "pvd_60wzmxv9cjbrbr87w8d7rmrdv9",
      "status": "PROCESSING",
      "thumbnail_url": null,
      "screenshot_url": null
    }
  ]
}

The run is done when its status is COMPLETED or FAILED. Each device settles on its own, and one device failing doesn’t fail the run:

Result status	Meaning
`PENDING`, `PROCESSING`	Still rendering
`COMPLETED`	The screenshot is ready
`TIMED_OUT`	The device didn’t report in time
`UNSUPPORTED`	The device has been retired
`FAILED`	The render failed on that device

This loop checks every 10 seconds for up to 5 minutes, then prints each device’s screenshot:

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const deadline = Date.now() + 5 * 60 * 1000;
const read = () => client.notifications.previews.runs.retrieve(run.id, { id: run.template_id });

await wait(10_000);
let detail = await read();
while (!["COMPLETED", "FAILED"].includes(detail.status) && Date.now() < deadline) {
  await wait(10_000);
  detail = await read();
}

for (const result of detail.results) {
  console.log(result.device_id, result.status, result.screenshot_url ?? "");
}

import time

deadline = time.monotonic() + 5 * 60

def read():
    return client.notifications.previews.runs.retrieve(preview_run_id=run.id, id=run.template_id)

time.sleep(10)
detail = read()
while detail.status not in ("COMPLETED", "FAILED") and time.monotonic() < deadline:
    time.sleep(10)
    detail = read()

for result in detail.results:
    print(result.device_id, result.status, result.screenshot_url or "")

URL="https://api.courier.com/notifications/nt_01m3d2j79dfk1th1a2r7h494ye/previews/runs/pvr_01m3d2j8zve8nb25sqfmckfc3g"

sleep 10
for attempt in $(seq 1 30); do
  RUN=$(curl -s "$URL" -H "Authorization: Bearer $COURIER_API_KEY")
  STATUS=$(echo "$RUN" | jq -r '.status')
  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then break; fi
  sleep 10
done

echo "$RUN" | jq -r '.results[] | "\(.device_id) \(.status) \(.screenshot_url // "")"'

Download screenshots when you read the run. screenshot_url and thumbnail_url are temporary signed links, so read the run again for fresh ones later. Most screenshots are PNG files, but check each file’s Content-Type rather than its extension.

Check email previews with an AI agent

An agent can run a preview, read the screenshots, and fix what it finds. Connect it through the when it works in a chat or code editor, or have it call the API above when it runs in your own code or CI. With MCP, ask for the preview and the review in one prompt:

With Courier MCP, run a device preview of template nt_01m3d2j79dfk1th1a2r7h494ye on the Courier Recommended set, as Sarah Bennett at Acme Corp with order ORD-1234. Check the run every 10 seconds for up to 5 minutes. Review each screenshot and tell me what's broken on each client.

Ask it to check for blank gaps from missing variables, copy that doesn’t match its section, broken images, Outlook layout breaks, mobile stacking, dark mode contrast, and the subject line.

Customize the devices

Courier Recommended covers the common clients. To focus on others, list the full catalog with . Each device has a pvd_ ID and fields to filter on: category, app, platform, os, os_version, and theme. For a one-off run, pass device_ids instead of device_set_id. Send exactly one of the two. To reuse a list, save it with . It shows up in the editor’s Targets dropdown too:

{
  "name": "Outlook desktop",
  "device_ids": [
    "pvd_6jftknaab7a55she2qg907nfna",
    "pvd_0f36p8bvkgbynrgt24nh59ajd0",
    "pvd_3j67g4gq17bmyvhddgngpbbjx6",
    "pvd_17j3h8qhx5ajkvxbswyya6zcjn"
  ]
}

replaces a set’s name and devices in full. archives it, and runs that used it keep their own copy of its devices. Courier Recommended can’t be changed, so copy its devices into your own set to adjust them.

Errors

Courier checks a run request before the run exists, so a rejected request isn’t billed.

Status	When	Message
`400`	Both or neither of `device_set_id` and `device_ids`	`provide exactly one of device_set_id or device_ids`
`400`	A field the request doesn’t take, such as `template_id`	`Unrecognized key: "template_id"`
`400`	A malformed version, such as `v2`	`template_version: Invalid input`
`402`	The previews add-on isn’t enabled	`the cross-client previews add-on is required for this workspace`
`404`	The template, device set, or run doesn’t exist
`409`	Changing or archiving Courier Recommended	`device set … is the Courier default set and cannot be changed or archived`
`422`	A device ID that isn’t in the catalog	`unknown device id: pvd_…`
`422`	A version the template doesn’t have	`template … has no version v009`
`422`	A template that isn’t a Design Studio template	`not a Design Studio template`

Preview HTML you already have

You don’t need to send through Courier to use Device Preview. Bring the HTML email you send from any platform, turn it into a template, and preview it like any other. In the editor, create an email template, open the , paste your markup, and run a preview. With the API, create the template with . Put a meta element for the subject and an html element for the markup inside the email channel. Reference test values by name, such as {{profile.name}} and {{order_id}}:

{
  "notification": {
    "name": "Order shipped",
    "tags": [],
    "brand": null,
    "subscription": null,
    "routing": null,
    "content": {
      "version": "2022-01-01",
      "elements": [
        {
          "type": "channel",
          "channel": "email",
          "elements": [
            { "type": "meta", "title": "Your order has shipped" },
            { "type": "html", "content": "<table role=\"presentation\" width=\"600\"><tr><td>Hi {{profile.name}}, order {{order_id}} is on its way.</td></tr></table>" }
          ]
        }
      ]
    }
  },
  "state": "DRAFT"
}

Then start a run on the new template’s id.

Pricing

Device Preview is a paid monthly add-on. Enable it in the console under Settings → Billing. Each device in a run is one preview. The add-on comes in three tiers. Each includes a set number of previews per month, and anything beyond that is billed per preview. Included previews reset each month and don’t roll over.

Monthly price	Previews included	Overage per preview
$20	100	$0.20
$50	400	$0.15
$100	1,000	$0.12

Supported clients

A client is one combination of app, device, OS, browser, and color mode. The tables below list the current catalog, and always returns the latest one as new devices and OS versions are added.

Desktop applications

App	Device	OS	Modes
Apple Mail 16	Mac	macOS 13	Light, Dark
Outlook 2016	PC	Windows 10	Light
Outlook 2016 (120 dpi)	PC	Windows 10	Light
Outlook 2019	PC	Windows 10	Light
Outlook 2019 (120 dpi)	PC	Windows 10	Light
Outlook 2021	PC	Windows 11	Light, Dark
Outlook 2024	PC	Windows 11	Light, Dark
Outlook Microsoft 365	Mac	macOS 13	Light, Dark
Outlook Microsoft 365	PC	Windows 11	Light, Dark
Outlook Office 365	PC	Windows 10	Light, Dark

Mobile applications

App	OS	Devices	Modes
Apple Mail	iOS 16	iPhone 14, iPhone 14 Pro, iPhone 14 Pro Max	Light, Dark
Apple Mail	iOS 17	iPhone 15, iPhone 15 Plus, iPhone 15 Pro, iPhone 15 Pro Max	Light, Dark
Apple Mail	iOS 18	iPhone 16, iPhone 16 Pro, iPhone 16 Pro Max	Light, Dark
Apple Mail	iOS 26	iPhone 17, iPhone 17 Pro, iPhone 17 Pro Max	Light, Dark
Apple Mail	iOS 27	iPhone 18 Pro	Light, Dark
Gmail	iOS 26	iPhone 16	Light, Dark
Gmail	Android 12	Pixel 6	Light, Dark
Gmail	Android 13	Pixel 7	Light, Dark
Gmail	Android 14	Pixel 8	Light, Dark
Gmail	Android 15	Pixel 9	Light, Dark
Gmail	Android 16	Pixel 10	Light, Dark
Outlook	iOS 15	iPhone 13	Light, Dark

Webmail

Service	Browsers	OS	Modes
AOL.com	Chrome, Edge, Firefox	Windows 10	Light, Dark
Free.fr	Chrome, Edge, Firefox	Windows 10	Light, Dark
Gmail.com	Chrome, Edge, Firefox	Windows 10	Light, Dark
GMX	Chrome, Edge, Firefox	Windows 10	Light
Libero	Chrome, Edge, Firefox	Windows 10	Light
Microsoft365.com	Chrome, Edge, Firefox	Windows 10	Light, Dark
Outlook.com	Chrome, Edge, Firefox	Windows 10	Light, Dark
T-Online	Chrome, Edge, Firefox	Windows 10	Light
Web.de	Chrome, Edge, Firefox	Windows 10	Light
Yahoo.com	Chrome, Edge, Firefox	Windows 10	Light, Dark

Limits & behavior

Each run records the version it rendered. That’s the published version if your draft matches it, or draft if the draft has unpublished changes.
Preview history is kept for one year. Runs can’t be cancelled or deleted.
Screenshots vary by client. Some show the full inbox, others only the email body.

Get started

Send messages

Journeys

Broadcasts

Design

In-app

Recipients

Tenants

Monitoring

Workspaces

Resources

Device Preview for email

Run a preview in the editor

Review the results

Find past runs

Build a target set

Run a preview with the API

Start a run

Get the results

Check email previews with an AI agent

Customize the devices

Errors

Preview HTML you already have

Pricing

Supported clients

Desktop applications

Mobile applications

Webmail

Limits & behavior

​Run a preview in the editor

​Review the results

​Find past runs

​Build a target set

​Run a preview with the API

​Start a run

​Get the results

​Check email previews with an AI agent

​Customize the devices

​Errors

​Preview HTML you already have

​Pricing

​Supported clients

​Desktop applications

​Mobile applications

​Webmail

​Limits & behavior

Run a preview in the editor

Review the results

Find past runs

Build a target set

Run a preview with the API

Start a run

Get the results

Check email previews with an AI agent

Customize the devices

Errors

Preview HTML you already have

Pricing

Supported clients

Desktop applications

Mobile applications

Webmail

Limits & behavior