Inbox Previews API

Use the Cloud API to manage a project's Inbox Previews defaults from your backend. Keep your API key server-side and see Authentication before making requests.

An editor's features.inboxPreviews init config can override these defaults for that editor instance.

Read the defaults

GET /v3/projects/:id

The response includes data.inboxPreviews. A null value means the recommended email clients or automatic data region is active.

Update the defaults

curl --request PATCH 'https://api.unlayer.com/v3/projects/1234' \
  --header 'Authorization: Bearer unlayer_sk_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "inboxPreviews": {
      "clients": ["outlook19", "iphone16gmail_26"],
      "dataRegion": "eu"
    }
  }'

Field	Value
clients	A non-empty list of current IDs, or null to use the recommended set.
dataRegion	us, eu, or null to choose automatically from the project region.

Both fields are optional. Omitted fields stay unchanged. Unknown client IDs return 400 VALIDATION_ERROR without changing the project.

Paid plans accept up to 20 email clients in one run. Free plans accept up to three when Inbox Previews is explicitly enabled. Customer Success can configure an account-specific exception, but the platform never accepts more than 20. This per-run limit is separate from the billing-period allowance. A larger selection returns 400 VALIDATION_ERROR without changing the project.

Automatic region selection follows the project's custom storage region when available, then its asset region. It never guesses from a user's location. A region change affects future runs only; existing previews stay in their original region.

See the API reference for the full request and response schemas.

Read usage

Credits are shared by the whole workspace; these endpoints report one project's share.

GET /v3/projects/:id/inbox-previews/usage?start=2026-08-01&end=2026-08-31

Returns the project's generations, credits, daily trend, usage by email client, and usage by end user. Dates are inclusive, up to 366 days, and default to the last 30 days. Page the end-user list with limit (default and maximum 100) and offset (up to 100,000). Add end_user_id=customer-123 to scope everything to one end user; send the same ID you gave the editor.

Two billing models can appear in one period, and total_credits combines them:

• Per device (current): one credit per selected email client. Broken down in per_device_credits; email_clients and end_users cover these runs only.
• Per generation (previous model): one credit per accepted LIVE generation, none for TEST. Broken down in per_generation_credits. Rows recorded before generation-level reporting are counted in per_generation_credit_details_unavailable rather than shown as zero.

total_device_credits and the daily device_credits are kept as aliases for the per-device part.

GET /v3/projects/:id/inbox-previews/usage/runs?start=2026-08-01&end=2026-08-31

Lists individual generations with the same filters, 25 per page by default.

Field	Per-device run	Per-generation run
billing_model	per-device	per-generation
credits_used, credit_details_available	Credits charged	Credits charged, or unavailable for old rows
clients	The selected email clients	The clients the provider reported
viewed_clients, automatically_viewed_clients, interactively_viewed_clients, click_viewed_clients, navigation_viewed_clients	Which were viewed and how (auto, any interaction, thumbnail click, previous/next controls), or null without view tracking	null
end_user_id, template_id, data_region	When known	null
configuration_source	editor, console, api, project, or recommended	previous-billing-model

Provider details and internal costs are never exposed. The project's Usage page in Console shows the same data with the same filters, plus a CSV export of whatever the page shows.

Remove end-user attribution

To fulfill an end-user erasure request without changing the project's billing totals:

DELETE /v3/projects/:id/inbox-previews/usage/end-users
Content-Type: application/json

{"end_user_id":"customer-123"}

Send the same source ID that was supplied to the editor; whitespace and long IDs are normalized the same way as generation. This permanently removes the stored ID from matching usage rows. Generation and device-credit totals remain unchanged. End-user attribution is also removed automatically after 13 months.

Email-client IDs

The catalog changes as email clients and devices evolve. Use this live list when setting clients:

Loading the current email-client catalog…

You can also fetch the catalog directly:

curl 'https://api.unlayer.com/v2/editor/inbox-previews/clients'