{
"components": {
"parameters": {
"Page": {
"name": "page",
"in": "query",
"description": "The page number of results you want to display. Use with `limit`.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
"Limit": {
"name": "limit",
"in": "query",
"description": "The maximum number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 1000
}
},
"DirectDescendantsOnly": {
"name": "direct_descendants_only",
"in": "query",
"description": "When `true`, the response includes only the immediate children of the parent folder. When `false`, it includes the parent folder's entire subtree.",
"schema": {
"type": "boolean",
"default": false
}
},
"folder_id": {
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the folder.",
"schema": {
"type": "string",
"format": "uuid"
}
},
"email_id": {
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
},
"email_variant_id": {
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
},
"component_id": {
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the component.",
"schema": {
"type": "string",
"format": "uuid"
}
},
"sms_id": {
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the SMS.",
"schema": {
"type": "string",
"format": "uuid"
}
},
"inbox_id": {
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the inbox message. If the message has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
},
"run_id": {
"name": "run_id",
"in": "path",
"required": true,
"description": "The ID of the inbox preview job, returned by [Send for inbox previews](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/).",
"schema": {
"type": "integer"
}
},
"preview_client_id": {
"name": "client_id",
"in": "path",
"required": true,
"description": "The device identifier for the capture, matching a value from `client_ids` in the response of [Send for inbox previews](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/).",
"schema": {
"type": "string"
}
},
"version_id": {
"name": "version_id",
"in": "path",
"required": true,
"description": "The UUID of the version.",
"schema": {
"type": "string",
"format": "uuid"
}
},
"Language": {
"name": "language",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "A [language code](/journeys/channels/localization/attribute/#supported-languages) that indicates the language of your translated email"
},
"ParentFolderID": {
"name": "parent_folder_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Filter by parent folder. Must reference an existing folder. If not set, the response filters by the root level directory.\n\nTo list only items in the root folder, leave `parent_folder_id` unset and only set `direct_descendants_only` to `true`.\n"
},
"SortBy": {
"name": "sort_by",
"in": "query",
"schema": {
"type": "string",
"enum": [
"created",
"updated",
"name"
],
"default": "created"
}
},
"SortOrder": {
"name": "sort_order",
"in": "query",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
"CreatedBefore": {
"name": "created_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created before this time. Must be a unix timestamp.",
"example": 1773856017
},
"CreatedAfter": {
"name": "created_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created after this time. Must be a unix timestamp.",
"example": 1773856017
},
"UpdatedBefore": {
"name": "updated_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated before this time. Must be a unix timestamp.",
"example": 1773856017
},
"UpdatedAfter": {
"name": "updated_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated after this time. Must be a unix timestamp.",
"example": 1773856017
}
},
"schemas": {
"Error": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The UUID of the parent folder.\n\nOmit if you want no change to where the folder or file is located. Include `null` to move it to your root directory. Or add the UUID of another folder to move it there.\n"
},
"Folder": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the folder was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of folder"
},
"name": {
"type": "string",
"description": "The name of the folder."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory."
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the folder."
}
},
"example": {
"created": 1714732800,
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Product Announcements",
"parent_folder_id": null,
"updated": 1714732800
}
},
"EmailSummary": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the email was created.",
"example": 1714732800
},
"has_translations": {
"type": "boolean",
"description": "Whether the email has translations"
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of email",
"example": "sdflkj345"
},
"is_linked": {
"type": "boolean",
"description": "Whether the email is linked to a workflow (automation, broadcast, etc)"
},
"is_template": {
"type": "boolean",
"description": "Whether the email is a template"
},
"name": {
"type": "string",
"description": "The name of the email"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the email.",
"example": 1714732800
}
}
},
"Email": {
"type": "object",
"properties": {
"available_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of [language codes](/journeys/channels/localization/attribute/#supported-languages) that reflect the languages this default email has been translated to.",
"example": [
"en",
"es"
]
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the email was created.",
"example": 1773856017
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the email.",
"example": "sdflkj345"
},
"is_linked": {
"type": "boolean",
"description": "Whether the email is currently linked to a workflow (automation, broadcast, etc).\n"
},
"is_template": {
"type": "boolean",
"description": "Whether the email is a reusable template."
},
"name": {
"type": "string",
"description": "Display name of the email."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder, or `null` if the email is in your root directory.\n"
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of ``.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `![]()
` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of ``.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
},
"updated": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the email.",
"example": 1773856017
}
}
},
"EmailCreate": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name of the email."
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"envelope": {
"type": "object",
"description": "The envelope of your email, like from and to addresses.",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID. Must reference an existing identity. You can find this in *Workspace Settings > Email* under your From Addresses.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient email address. Defaults to `{{customer.email}}`` if not set.\n"
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Reply-to identity ID. Must reference an existing identity from *Workspace Settings > Email* under your From Addresses.\n"
}
}
},
"is_template": {
"type": "boolean",
"default": false,
"description": "Whether the email is a reusable template."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder. Omit or pass `null` to create at root."
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
}
}
},
"EmailUpdate": {
"type": "object",
"properties": {
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"envelope": {
"type": "object",
"description": "The envelope of your email, like from and to addresses.",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID. Must reference an existing identity. You can find this in *Workspace Settings > Email* under your From Addresses.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient email address. Defaults to `{{customer.email}}`` if not set.\n"
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Reply-to identity ID. Must reference an existing identity from *Workspace Settings > Email* under your From Addresses.\n"
}
}
},
"is_template": {
"type": "boolean",
"description": "Whether the email is a reusable template."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name of the email."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The UUID of the parent folder.\n\nOmit if you want no change to where the folder or file is located. Include `null` to move it to your root directory. Or add the UUID of another folder to move it there.\n"
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
}
}
},
"EmailContent": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"EmailEnvelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"EmailEnvelopeInput": {
"type": "object",
"description": "The envelope of your email, like from and to addresses.",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID. Must reference an existing identity. You can find this in *Workspace Settings > Email* under your From Addresses.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient email address. Defaults to `{{customer.email}}`` if not set.\n"
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Reply-to identity ID. Must reference an existing identity from *Workspace Settings > Email* under your From Addresses.\n"
}
}
},
"EmailHeader": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"EmailTranslation": {
"type": "object",
"properties": {
"available_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of [language codes](/journeys/channels/localization/attribute/#supported-languages) that reflect the languages this default email has been translated to.",
"example": [
"en",
"es"
]
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"created": {
"type": "integer",
"description": "Unix timestamp of when the translation was created.",
"example": 1773856017
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"is_linked": {
"type": "boolean",
"description": "Whether the translation is linked to a workflow (automation, broadcast, etc)"
},
"is_template": {
"type": "boolean",
"description": "Whether the translation is a template"
},
"language": {
"type": "string",
"description": "The [language code](/journeys/channels/localization/attribute/#supported-languages) of the translation",
"example": "fr"
},
"language_group_id": {
"type": "string",
"format": "uuid",
"description": "ID of the parent email that groups all translations. Same as the id in the path parameter."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder, or `null` if the email is in your root directory."
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
},
"updated": {
"type": "integer",
"description": "Unix timestamp of the last update to the translation.",
"example": 1773856017
}
}
},
"Sms": {
"type": "object",
"required": [
"id",
"name",
"is_linked",
"parent_folder_id",
"content",
"recipient",
"sender_id",
"created",
"updated"
],
"properties": {
"content": {
"type": "string",
"description": "The message, written as SMS markup.",
"example": "<x-sms><x-sms-body>Hi {{customer.first_name}}, your order has shipped.</x-sms-body></x-sms>"
},
"created": {
"type": "integer",
"format": "int64",
"description": "When you created the SMS, as a Unix timestamp in seconds.",
"example": 1790000000
},
"id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the SMS."
},
"is_linked": {
"type": "boolean",
"description": "Whether you've linked the SMS to a workflow, like a transactional message, a one-time send, or an automation action."
},
"name": {
"type": "string",
"description": "The friendly name your team sees for the SMS in Design Studio.",
"example": "Order shipped"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the folder that contains the SMS, or `null` if the SMS is at the root level."
},
"recipient": {
"type": "string",
"description": "Liquid that resolves to the phone number of the person you're messaging. An empty string means Customer.io sends to `{{customer.phone}}`.",
"example": "{{customer.phone}}"
},
"sender_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The ID of the sender identity the SMS sends from, or `null` if you haven't set a sender.",
"example": 2
},
"updated": {
"type": "integer",
"format": "int64",
"description": "When the SMS last changed, as a Unix timestamp in seconds.",
"example": 1790000000
}
}
},
"ComponentSummary": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the component was created.",
"example": 1773856017
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of the component",
"example": "e89b-12d3"
},
"name": {
"type": "string",
"description": "Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.",
"example": "Custom footer"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "ID of the parent folder, or `null` if the component is in your root directory.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"tag": {
"type": "string",
"description": "The component tag name, used to reference your component in an email.",
"example": "custom-footer"
},
"updated": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the component.",
"example": 1773856019
}
}
},
"Component": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "HTML content"
},
"created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the component was created.",
"example": 1773856017
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of the component",
"example": "e89b-12d3"
},
"name": {
"type": "string",
"description": "Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.",
"example": "Custom footer"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "ID of the parent folder, or `null` if the component is in your root directory.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"tag": {
"type": "string",
"description": "The component tag name, used to reference your component in an email.",
"example": "custom-footer"
},
"updated": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the component."
}
}
},
"Transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
},
"ListMeta": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"description": "The filters applied in your request.",
"example": {
"parent_folder_id": "123e4567-e89b-12d3-a456-426614174000",
"direct_descendants_only": true,
"sort_by": "created",
"sort_order": "desc",
"created_before": 1714732800,
"created_after": null,
"updated_before": null,
"updated_after": null
}
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "The number of results per page."
},
"page": {
"type": "integer",
"description": "The page number of results you're on."
},
"total": {
"type": "integer",
"description": "The total number of folders."
}
}
}
}
},
"LinkTarget": {
"type": "object",
"description": "The workflow to link the content to.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "The kind of workflow to link. Provide the matching ID field for the type you choose. Use `campaign_action` for an automation or API-triggered broadcast.\n",
"enum": [
"transactional_message",
"newsletter",
"campaign_action"
]
},
"action_id": {
"type": "integer",
"description": "The ID of the action in the automation or API-triggered broadcast to link your content to. Required when `type` is `campaign_action`."
},
"newsletter_id": {
"type": "integer",
"description": "The ID of the one-time send to link your content to. Required when `type` is `newsletter`."
},
"transactional_message_id": {
"type": "integer",
"description": "The ID of the transactional message to link your content to. Required when `type` is `transactional_message`."
}
},
"example": {
"type": "campaign_action",
"action_id": 42
}
},
"LinkTargetResponse": {
"type": "object",
"description": "The workflow linked to the message. The response returns `campaign_action` for an automation or an API-triggered broadcast.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "The type of workflow linked.\n",
"enum": [
"transactional_message",
"newsletter",
"campaign_action"
]
},
"action_id": {
"type": "integer",
"description": "The ID of the action in the automation or API-triggered broadcast that was linked."
},
"newsletter_id": {
"type": "integer",
"description": "The ID of the one-time send linked."
},
"transactional_message_id": {
"type": "integer",
"description": "The ID of the transactional message linked."
}
},
"example": {
"type": "campaign_action",
"action_id": 42
}
},
"LinkRequest": {
"type": "object",
"required": [
"target"
],
"properties": {
"target": {
"type": "object",
"description": "The workflow to link the content to.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "The kind of workflow to link. Provide the matching ID field for the type you choose. Use `campaign_action` for an automation or API-triggered broadcast.\n",
"enum": [
"transactional_message",
"newsletter",
"campaign_action"
]
},
"action_id": {
"type": "integer",
"description": "The ID of the action in the automation or API-triggered broadcast to link your content to. Required when `type` is `campaign_action`."
},
"newsletter_id": {
"type": "integer",
"description": "The ID of the one-time send to link your content to. Required when `type` is `newsletter`."
},
"transactional_message_id": {
"type": "integer",
"description": "The ID of the transactional message to link your content to. Required when `type` is `transactional_message`."
}
},
"example": {
"type": "campaign_action",
"action_id": 42
}
},
"force": {
"type": "boolean",
"description": "Replace an existing link if the workflow or action is already linked to *different* Design Studio content.\n",
"default": false
}
},
"example": {
"target": {
"type": "campaign_action",
"action_id": 42
},
"force": false
}
},
"LinkResponse": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the linked message."
},
"target": {
"type": "object",
"description": "The workflow linked to the message. The response returns `campaign_action` for an automation or an API-triggered broadcast.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "The type of workflow linked.\n",
"enum": [
"transactional_message",
"newsletter",
"campaign_action"
]
},
"action_id": {
"type": "integer",
"description": "The ID of the action in the automation or API-triggered broadcast that was linked."
},
"newsletter_id": {
"type": "integer",
"description": "The ID of the one-time send linked."
},
"transactional_message_id": {
"type": "integer",
"description": "The ID of the transactional message linked."
}
},
"example": {
"type": "campaign_action",
"action_id": 42
}
},
"template_id": {
"type": "integer",
"description": "The ID of the workflow template the content is now linked to."
}
},
"example": {
"node_id": "123e4567-e89b-12d3-a456-426614174000",
"target": {
"type": "campaign_action",
"action_id": 42
},
"template_id": 987654
}
},
"PublishMapping": {
"type": "object",
"description": "A single node-to-template-version mapping produced by the publish process.",
"properties": {
"language": {
"type": "string",
"description": "The language code of the published node. Empty for the default-language email."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the published email node (default or translation)."
},
"template_id": {
"type": "integer",
"description": "The ID of the workflow template that received the content."
},
"version_id": {
"type": "string",
"description": "The identifier of the template version created by the publish."
}
}
},
"PublishResponse": {
"type": "object",
"properties": {
"mappings": {
"type": "array",
"description": "The template versions created by the publish. Present when `status` is `done`.",
"items": {
"type": "object",
"description": "A single node-to-template-version mapping produced by the publish process.",
"properties": {
"language": {
"type": "string",
"description": "The language code of the published node. Empty for the default-language email."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the published email node (default or translation)."
},
"template_id": {
"type": "integer",
"description": "The ID of the workflow template that received the content."
},
"version_id": {
"type": "string",
"description": "The identifier of the template version created by the publish."
}
}
}
},
"publish_id": {
"type": "string",
"description": "An opaque ID to poll for completion with [Get publish status](/integrations/api/design-studio/tag/email-email-link-and-publish/getPublishStatus/). Present when `status` is `pending`."
},
"status": {
"type": "string",
"description": "Returns `done` when the publish process finished within the request window. Returns `pending` when publish is still running for a multi-language email (poll with `publish_id`).\n",
"enum": [
"done",
"pending"
]
}
},
"example": {
"mappings": [
{
"language": "",
"node_id": "123e4567-e89b-12d3-a456-426614174000",
"template_id": 987654,
"version_id": "v_01H8XK"
}
],
"status": "done"
}
},
"PublishStatusResponse": {
"type": "object",
"properties": {
"mappings": {
"type": "array",
"description": "The template versions created by the publish. Present when `status` is `done`.",
"items": {
"type": "object",
"description": "A single node-to-template-version mapping produced by the publish process.",
"properties": {
"language": {
"type": "string",
"description": "The language code of the published node. Empty for the default-language email."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the published email node (default or translation)."
},
"template_id": {
"type": "integer",
"description": "The ID of the workflow template that received the content."
},
"version_id": {
"type": "string",
"description": "The identifier of the template version created by the publish."
}
}
}
},
"status": {
"type": "string",
"description": "`pending` while the publish is still running; `done` when it has finished.\n",
"enum": [
"pending",
"done"
]
}
},
"example": {
"mappings": [
{
"language": "",
"node_id": "123e4567-e89b-12d3-a456-426614174000",
"template_id": 987654,
"version_id": "v_01H8XK"
}
],
"status": "done"
}
},
"ChannelPublishResponse": {
"type": "object",
"description": "The result of the publish process.",
"properties": {
"template_ids": {
"type": "array",
"description": "The IDs of the workflow templates that received the content.",
"items": {
"type": "integer"
}
},
"version_id": {
"type": "string",
"description": "The identifier of the template version created by the publish process."
}
},
"example": {
"template_ids": [
987654
],
"version_id": "v_01H8XK"
}
},
"UnpublishedChangesResponse": {
"type": "object",
"properties": {
"has_unpublished_changes": {
"type": "boolean",
"description": "Indicates whether the email or any of its translations has content changes that haven't been published."
}
},
"example": {
"has_unpublished_changes": true
}
},
"InboxPreviewClient": {
"type": "object",
"description": "An email client available for inbox previews.",
"properties": {
"browser": {
"type": "string",
"description": "Browser used to render the client. Populates when `category` is `Web`.",
"example": ""
},
"category": {
"type": "string",
"enum": [
"Mobile",
"Application",
"Web"
],
"description": "Where the client renders. `Mobile` is a phone's native mail app, for example the Gmail App on Android devices. `Application` is a desktop native mail app, for example Apple Mail on macOS. `Web` is webmail viewed in a desktop browser, for example Gmail.com in Firefox, and includes a `browser` value.\n",
"example": "Mobile"
},
"client": {
"type": "string",
"description": "Name of the email client and device.",
"example": "Gmail App Pixel 6"
},
"id": {
"type": "string",
"description": "Identifier to pass in `client_ids` when you send for an inbox preview.",
"example": "android12_gmailapp_pixel6_dm"
},
"os": {
"type": "string",
"description": "Operating system the client runs on. Look for `(Dark Mode)` if you want to locate preview options for dark mode.\n",
"example": "Android 12 (Dark Mode)"
}
}
},
"InboxPreviewCreditPool": {
"type": "object",
"description": "Credits available for generating inbox previews.",
"properties": {
"credits_original": {
"type": "integer",
"description": "Credits originally granted for a tier."
},
"credits_remaining": {
"type": "integer",
"description": "Credits left to spend from this tier."
},
"expires_at": {
"type": [
"integer",
"null"
],
"format": "Unix timestamp",
"description": "When this pool's credits expire, if ever. Expiry is set per pool, not per tier—a purchased pool typically doesn't expire, but a free pool support granted can carry an expiration date. The monthly allowance's `expires_at` also reads `null` when Customer.io can't resolve your current billing period; that's a transient read issue, not a sign the allowance never expires."
},
"tier": {
"type": "string",
"enum": [
"free",
"paid"
],
"description": "The credit tier this pool belongs to. The [`free` tier](/accounts/billing/inbox-previews/) covers two kinds of pools, the monthly allowance of 25 credits every account gets and any free pools Customer.io support has granted. Because of that, `free` can appear more than once in the response. The `paid` tier covers credits purchased for the account."
}
},
"example": [
{
"tier": "free",
"credits_original": 25,
"credits_remaining": 0,
"expires_at": 1715769600
},
{
"tier": "paid",
"credits_original": 100,
"credits_remaining": 90,
"expires_at": null
}
]
},
"InboxPreviewTile": {
"type": "object",
"description": "The data for a single preview.",
"properties": {
"browser": {
"type": "string",
"description": "Browser used to render the client, when applicable. Populates when `category` is `Web`."
},
"cached": {
"type": "boolean",
"description": "Set when the item wasn't newly generated in this preview job because it had already been generated. Omitted when `false`."
},
"category": {
"type": "string",
"enum": [
"Mobile",
"Application",
"Web"
],
"description": "Client category. `Mobile` is a phone's native mail app, for example the Gmail App on Android devices. `Application` is a desktop native mail app, for example Apple Mail on macOS. `Web` is webmail viewed in a desktop browser, for example Gmail.com in Firefox, and includes a `browser` value."
},
"client_id": {
"type": "string",
"description": "The preview identifier, matching a value from `client_ids` in the submit request."
},
"display_name": {
"type": "string",
"description": "Human-readable name of the client and device used to render the preview."
},
"error": {
"type": "object",
"description": "Details for a tile whose rendering failed.",
"properties": {
"message": {
"type": "string",
"description": "A human-readable explanation, safe to show to a user."
},
"type": {
"type": "string",
"enum": [
"bounced",
"vendor_timeout",
"client_rejected",
"vendor_request",
"abandoned",
"expired",
"other"
],
"description": "Why this device has no screenshot:\n - `bounced`: the vendor rendered the device and reported a bounce.\n - `vendor_timeout`: submitted to the vendor, but didn't finish in time.\n - `client_rejected`: the vendor refused the device id.\n - `vendor_request`: the submission to the vendor itself failed.\n - `abandoned`: submitted, but the outcome is unknown.\n - `expired`: the screenshot rendered successfully but has since aged out of its retention window and is no longer available. Unlike the other types, this isn't a render failure.\n - `other`: any other cause.\n\nA tile with any of these types (except `expired`) was refunded its credit.\n"
}
}
},
"full_thumbnail": {
"type": "string",
"description": "Capture URL for a reduced, full-length version of the default screenshot. Omitted unless the render completed."
},
"os": {
"type": "string",
"description": "Operating system the client runs on."
},
"screenshots": {
"type": "object",
"description": "Capture URLs keyed by image name—the full-size screenshot under `default`, plus a key per extra image the device renders. This is the only place the full-size URL appears; `thumbnail` and `full_thumbnail` are reduced variants. Omitted unless the render completed.",
"additionalProperties": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"Pending",
"Processing",
"Complete",
"Bounced"
],
"description": "The vendor's own status for this device's render. Only `Complete` and `Bounced` are terminal."
},
"thumbnail": {
"type": "string",
"description": "Capture URL for a reduced-size version of the default screenshot. Useful for grid/list views where you don't want to load full-size screenshots. Omitted unless the render completed."
}
}
},
"InboxPreviewError": {
"type": "object",
"description": "Details for a tile whose rendering failed.",
"properties": {
"message": {
"type": "string",
"description": "A human-readable explanation, safe to show to a user."
},
"type": {
"type": "string",
"enum": [
"bounced",
"vendor_timeout",
"client_rejected",
"vendor_request",
"abandoned",
"expired",
"other"
],
"description": "Why this device has no screenshot:\n - `bounced`: the vendor rendered the device and reported a bounce.\n - `vendor_timeout`: submitted to the vendor, but didn't finish in time.\n - `client_rejected`: the vendor refused the device id.\n - `vendor_request`: the submission to the vendor itself failed.\n - `abandoned`: submitted, but the outcome is unknown.\n - `expired`: the screenshot rendered successfully but has since aged out of its retention window and is no longer available. Unlike the other types, this isn't a render failure.\n - `other`: any other cause.\n\nA tile with any of these types (except `expired`) was refunded its credit.\n"
}
}
},
"InboxPreviewJob": {
"type": "object",
"description": "The status and results of an Inbox Previews job.",
"properties": {
"client_ids": {
"type": "array",
"description": "The device identifiers requested for this job.",
"items": {
"type": "string"
}
},
"created_at": {
"type": "integer",
"format": "Unix timestamp",
"description": "When you submitted the preview job."
},
"is_processed": {
"type": "boolean",
"description": "`true` once every device has settled, for the email in the path—a multi-language run reports each of its emails separately, so this doesn't reflect the whole run when it covers more than one. Poll this field, and see the endpoint description for how often, and for when to give up.\n"
},
"name": {
"type": "string",
"description": "The batch label provided when you sent an email for previews. Empty if none was given."
},
"previews": {
"type": "array",
"description": "One object per requested preview.",
"items": {
"type": "object",
"description": "The data for a single preview.",
"properties": {
"browser": {
"type": "string",
"description": "Browser used to render the client, when applicable. Populates when `category` is `Web`."
},
"cached": {
"type": "boolean",
"description": "Set when the item wasn't newly generated in this preview job because it had already been generated. Omitted when `false`."
},
"category": {
"type": "string",
"enum": [
"Mobile",
"Application",
"Web"
],
"description": "Client category. `Mobile` is a phone's native mail app, for example the Gmail App on Android devices. `Application` is a desktop native mail app, for example Apple Mail on macOS. `Web` is webmail viewed in a desktop browser, for example Gmail.com in Firefox, and includes a `browser` value."
},
"client_id": {
"type": "string",
"description": "The preview identifier, matching a value from `client_ids` in the submit request."
},
"display_name": {
"type": "string",
"description": "Human-readable name of the client and device used to render the preview."
},
"error": {
"type": "object",
"description": "Details for a tile whose rendering failed.",
"properties": {
"message": {
"type": "string",
"description": "A human-readable explanation, safe to show to a user."
},
"type": {
"type": "string",
"enum": [
"bounced",
"vendor_timeout",
"client_rejected",
"vendor_request",
"abandoned",
"expired",
"other"
],
"description": "Why this device has no screenshot:\n - `bounced`: the vendor rendered the device and reported a bounce.\n - `vendor_timeout`: submitted to the vendor, but didn't finish in time.\n - `client_rejected`: the vendor refused the device id.\n - `vendor_request`: the submission to the vendor itself failed.\n - `abandoned`: submitted, but the outcome is unknown.\n - `expired`: the screenshot rendered successfully but has since aged out of its retention window and is no longer available. Unlike the other types, this isn't a render failure.\n - `other`: any other cause.\n\nA tile with any of these types (except `expired`) was refunded its credit.\n"
}
}
},
"full_thumbnail": {
"type": "string",
"description": "Capture URL for a reduced, full-length version of the default screenshot. Omitted unless the render completed."
},
"os": {
"type": "string",
"description": "Operating system the client runs on."
},
"screenshots": {
"type": "object",
"description": "Capture URLs keyed by image name—the full-size screenshot under `default`, plus a key per extra image the device renders. This is the only place the full-size URL appears; `thumbnail` and `full_thumbnail` are reduced variants. Omitted unless the render completed.",
"additionalProperties": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"Pending",
"Processing",
"Complete",
"Bounced"
],
"description": "The vendor's own status for this device's render. Only `Complete` and `Bounced` are terminal."
},
"thumbnail": {
"type": "string",
"description": "Capture URL for a reduced-size version of the default screenshot. Useful for grid/list views where you don't want to load full-size screenshots. Omitted unless the render completed."
}
}
}
},
"run_id": {
"type": "integer",
"description": "ID of the preview job."
},
"total_previews_bounced": {
"type": "integer",
"description": "Previews that produced no screenshot, whether the vendor bounced them or they failed on Customer.io's side. Their credits are refunded when the run settles."
},
"total_previews_cached": {
"type": "integer",
"description": "Previews served from an earlier run's screenshot. Not charged, and not counted in `total_previews_succeeded`."
},
"total_previews_ready": {
"type": "integer",
"description": "How many previews show a screenshot you can fetch, counted from the tiles themselves. This is the progress count to compare against `total_previews_requested`—`total_previews_succeeded` alone reads `0` on a fully cached run. It isn't the completion signal; `is_processed` is. Because a tile can be served by an earlier screenshot of the same content while this run's own render is still in flight, this can reach `total_previews_requested` before the run finishes.\n"
},
"total_previews_requested": {
"type": "integer",
"description": "Previews requested in the job, for the email in the path. On a settled run, this is normally `total_previews_cached` + `total_previews_succeeded` + `total_previews_bounced`."
},
"total_previews_succeeded": {
"type": "integer",
"description": "Previews this run generated itself, excluding cached ones. A fully cached run reports `0` here even though every tile is `Complete`—compare `total_previews_ready` against `total_previews_requested` instead to track progress."
},
"updated_at": {
"type": "integer",
"format": "Unix timestamp",
"description": "When the job's status was last updated."
}
}
},
"InboxPreviewJobSummary": {
"type": "object",
"description": "A summary entry in the inbox previews job history.",
"properties": {
"created_at": {
"type": "integer",
"format": "Unix timestamp",
"description": "When the job was submitted."
},
"is_processed": {
"type": "boolean",
"description": "`true` once every device of every counted node has settled. Under a `node_id` filter, \"counted\" means the matched nodes only.\n"
},
"name": {
"type": "string",
"description": "The batch label provided when the job was submitted."
},
"node_count": {
"type": "integer",
"description": "How many email nodes the run covers—more than one for a multi-language run. Under a `node_id` filter, how many of them matched."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The email node the run covers, or the first of them when it covers several. Under a `node_id` filter, this is the matched node."
},
"run_id": {
"type": "integer",
"description": "ID of the preview job."
},
"total_previews_bounced": {
"type": "integer",
"description": "Previews that produced no screenshot, whether the vendor bounced them or they failed on Customer.io's side, as stored when each node settled. Their credits are refunded."
},
"total_previews_cached": {
"type": "integer",
"description": "Previews served from an earlier run's screenshot. Not charged, and not counted in `total_previews_succeeded`."
},
"total_previews_ready": {
"type": "integer",
"description": "`total_previews_cached` + `total_previews_succeeded`, from the counters stored on the run. The cached half is final as soon as the run exists; the succeeded half counts only nodes that have settled, so a run still generating reads low until `is_processed` is `true`. This list can't see a tile served by an earlier screenshot of the same content, so it can read lower than [Get an inbox preview job](/integrations/api/design-studio/tag/email-testing/getInboxPreviewJob/) reports for the same run—poll the run for the authoritative count.\n"
},
"total_previews_requested": {
"type": "integer",
"description": "Previews requested across the counted nodes. On a settled run, this is normally `total_previews_cached` + `total_previews_succeeded` + `total_previews_bounced`."
},
"total_previews_succeeded": {
"type": "integer",
"description": "Previews this run generated itself, as stored when each node settled. Excludes cached ones, and counts only nodes that have settled—so a run still generating reads `0` here even once some devices are done."
},
"updated_at": {
"type": "integer",
"format": "Unix timestamp",
"description": "When the job's status was last updated."
}
}
},
"InboxPreviewJobsMeta": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "The `limit` used for this page."
},
"next_cursor": {
"type": "string",
"description": "Pass this as `cursor` to fetch the next page. Omitted when there are no more results."
}
}
}
}
},
"EmailRenderResponse": {
"type": "object",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML variant. Omitted unless you added an AMP version when you [created the email](/integrations/api/design-studio/tag/emails/createEmail/)."
},
"html": {
"type": "string",
"description": "Full HTML with liquid tags left intact."
},
"language": {
"type": "string",
"description": "Language code if the node is a translation (for example, `\"es\"`). Omitted for default-language nodes."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the rendered email node."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `\"EMAIL\"`."
},
"text": {
"type": "string",
"description": "Plain text version of the email. Omitted unless you added a plain text version when you [created the email](/integrations/api/design-studio/tag/emails/createEmail/)."
}
},
"example": {
"html": "<!doctype html>\n<html lang=\"und\">...\n<p>{{customer.first_name}}, welcome!</p>\n...\n</html>",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL",
"text": "<html><head></head><body style=\"margin:0\"><div style=\"font-size:16px;line-height:1.5;font-family:Arial,Helvetica,sans-serif;white-space:pre-wrap;padding:10px;\">{{customer.first_name}}, welcome!</div></body></html>"
}
},
"EmailPreviewRequest": {
"type": "object",
"properties": {
"campaign": {
"type": "object",
"description": "Campaign metadata for `{{campaign.*}}`."
},
"customer": {
"type": "object",
"description": "Customer profile attributes for `{{customer.*}}` variables."
},
"event": {
"type": "object",
"description": "Event attributes for `{{event.*}}`."
},
"journey": {
"type": "object",
"description": "Journey metadata for `{{journey.*}}`."
},
"lax": {
"type": "boolean",
"default": false,
"description": "Set to `true` if you want undefined variables to resolve to an empty string instead of reporting an error; this can help you focus on more important errors when you don't provide sample data or fallback values. Liquid *syntax* errors (like broken tags and invalid filters) are always reported as errors.\n"
},
"message": {
"type": "object",
"description": "Message metadata for `{{message.*}}`."
},
"objects": {
"type": "object",
"description": "Related objects for `{{objects.*}}`."
},
"trigger": {
"type": "object",
"description": "Trigger data for `{{trigger.*}}`."
}
},
"example": {
"customer": {
"first_name": "Jane",
"email": "jane@example.com",
"plan": "enterprise"
},
"event": {
"name": "order_completed",
"total": 149.99
}
}
},
"EmailPreviewResponse": {
"type": "object",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML variant with liquid evaluated. Omitted if the email doesn't have an AMP version."
},
"errors": {
"type": "object",
"description": "Per-field Liquid error arrays. All 15 fields are always present; an empty array means no errors for that field.",
"properties": {
"bcc": {
"type": "array",
"items": {
"type": "string"
},
"description": "BCC field Liquid errors."
},
"body": {
"type": "array",
"items": {
"type": "string"
},
"description": "HTML body Liquid errors."
},
"body_amp": {
"type": "array",
"items": {
"type": "string"
},
"description": "AMP body Liquid errors."
},
"body_plain": {
"type": "array",
"items": {
"type": "string"
},
"description": "Plain-text body Liquid errors."
},
"cc": {
"type": "array",
"items": {
"type": "string"
},
"description": "CC field Liquid errors."
},
"event": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event data Liquid errors."
},
"from": {
"type": "array",
"items": {
"type": "string"
},
"description": "From address Liquid errors."
},
"layout": {
"type": "array",
"items": {
"type": "string"
},
"description": "Layout template errors."
},
"message": {
"type": "array",
"items": {
"type": "string"
},
"description": "Message-level errors."
},
"preheader_text": {
"type": "array",
"items": {
"type": "string"
},
"description": "Preheader Liquid errors."
},
"reply_to": {
"type": "array",
"items": {
"type": "string"
},
"description": "Reply-to address Liquid errors."
},
"snippets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Snippet rendering errors."
},
"subject": {
"type": "array",
"items": {
"type": "string"
},
"description": "Subject line Liquid errors."
},
"to": {
"type": "array",
"items": {
"type": "string"
},
"description": "Recipient field Liquid errors, for example `\"undefined variable: customer.email\"`.\n"
},
"trigger": {
"type": "array",
"items": {
"type": "string"
},
"description": "Trigger data Liquid errors."
}
}
},
"from": {
"type": "string",
"description": "Resolved from address, for example `\"Name <email>\"`. Omitted when the email doesn't include a from address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "array",
"items": {
"type": "string"
},
"description": "Errors in the header name."
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"description": "Errors in the header value."
}
}
},
"description": "One entry per custom header that has Liquid errors. Omitted when there are none."
},
"html": {
"type": "string",
"description": "Final HTML with Liquid evaluated, the preheader injected, and dangerous tags removed."
},
"language": {
"type": "string",
"description": "Language code if the node is a translation. Omitted for default-language nodes."
},
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Problems with this link, like a relative URL or liquid tags that were URL-encoded. Empty when the link is fine."
},
"text": {
"type": "string",
"description": "The link's visible text."
},
"tracked": {
"type": "boolean",
"description": "Whether Customer.io rewrites this link for click tracking when you send the email."
},
"url": {
"type": "string",
"description": "The link URL after liquid evaluation."
}
}
},
"description": "Every link in the evaluated HTML body, with any per-link problems."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the previewed email node."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `\"EMAIL\"`."
},
"plaintext_body": {
"type": "string",
"description": "The plain-text part a recipient would get—your plain text version with HTML tags stripped, or text generated from the final HTML if the email doesn't have one. Omitted when empty."
},
"preheader_text": {
"type": "string",
"description": "Evaluated preheader text. Omitted when the email doesn't include preheaders."
},
"subject": {
"type": "string",
"description": "Evaluated subject line."
},
"text": {
"type": "string",
"description": "Plain-text body with liquid evaluated. Omitted if the email doesn't have a plain text version."
}
},
"example": {
"errors": {
"bcc": [],
"body": [],
"body_amp": [],
"body_plain": [],
"cc": [],
"event": [],
"from": [],
"layout": [],
"message": [],
"preheader_text": [],
"reply_to": [],
"snippets": [],
"subject": [],
"to": [],
"trigger": []
},
"from": "\"No reply\" <noreply@example.com>",
"html": "<!DOCTYPE html>...<p>Purchase info</p>...",
"links": [
{
"errors": [],
"text": "View your order",
"tracked": true,
"url": "https://example.com/orders"
}
],
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL",
"plaintext_body": "Thanks for your recent purchase!",
"subject": "Order Confirmation",
"text": "<html><head></head><body style=\"margin:0\"><div style=\"font-size:16px;line-height:1.5;font-family:Arial,Helvetica,sans-serif;white-space:pre-wrap;padding:10px;\">Thanks for your recent purchase!</div></body></html>"
}
},
"EmailPreviewErrors": {
"type": "object",
"description": "Per-field Liquid error arrays. All 15 fields are always present; an empty array means no errors for that field.",
"properties": {
"bcc": {
"type": "array",
"items": {
"type": "string"
},
"description": "BCC field Liquid errors."
},
"body": {
"type": "array",
"items": {
"type": "string"
},
"description": "HTML body Liquid errors."
},
"body_amp": {
"type": "array",
"items": {
"type": "string"
},
"description": "AMP body Liquid errors."
},
"body_plain": {
"type": "array",
"items": {
"type": "string"
},
"description": "Plain-text body Liquid errors."
},
"cc": {
"type": "array",
"items": {
"type": "string"
},
"description": "CC field Liquid errors."
},
"event": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event data Liquid errors."
},
"from": {
"type": "array",
"items": {
"type": "string"
},
"description": "From address Liquid errors."
},
"layout": {
"type": "array",
"items": {
"type": "string"
},
"description": "Layout template errors."
},
"message": {
"type": "array",
"items": {
"type": "string"
},
"description": "Message-level errors."
},
"preheader_text": {
"type": "array",
"items": {
"type": "string"
},
"description": "Preheader Liquid errors."
},
"reply_to": {
"type": "array",
"items": {
"type": "string"
},
"description": "Reply-to address Liquid errors."
},
"snippets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Snippet rendering errors."
},
"subject": {
"type": "array",
"items": {
"type": "string"
},
"description": "Subject line Liquid errors."
},
"to": {
"type": "array",
"items": {
"type": "string"
},
"description": "Recipient field Liquid errors, for example `\"undefined variable: customer.email\"`.\n"
},
"trigger": {
"type": "array",
"items": {
"type": "string"
},
"description": "Trigger data Liquid errors."
}
}
},
"EmailPreviewHeaderError": {
"type": "object",
"properties": {
"name": {
"type": "array",
"items": {
"type": "string"
},
"description": "Errors in the header name."
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"description": "Errors in the header value."
}
}
},
"EmailPreviewLink": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Problems with this link, like a relative URL or liquid tags that were URL-encoded. Empty when the link is fine."
},
"text": {
"type": "string",
"description": "The link's visible text."
},
"tracked": {
"type": "boolean",
"description": "Whether Customer.io rewrites this link for click tracking when you send the email."
},
"url": {
"type": "string",
"description": "The link URL after liquid evaluation."
}
}
},
"TestSendEmailRequest": {
"type": "object",
"required": [
"to"
],
"properties": {
"to": {
"type": "array",
"items": {
"type": "string"
},
"description": "The email addresses you want to send the test to. You can send to up to 25 addresses per request; up to three addresses on a trial account; or a single address (the account owner's address or your workspace's delivery address) if your account isn't verified yet.\n"
},
"customer": {
"type": [
"object",
"null"
],
"description": "Sample profile attributes for `customer.*` liquid variables, as a flat object of values. Encode a nested value as a JSON string. You can pass this alongside `customer_id`: Customer.io uses the profile's attributes, and a value here overrides the profile's value for the same key.\n",
"additionalProperties": true
},
"customer_id": {
"type": [
"string",
"null"
],
"description": "The person whose profile attributes fill in `customer.*` liquid variables. Pass the person's `cio_id` or the `id` that identifies them in your workspace. If nobody matches, the request fails. When you omit this field and don't pass `customer` values, the email renders with empty `customer.*` values and the response includes a warning.\n"
},
"event": {
"type": [
"object",
"null"
],
"description": "Sample event data for `event.*` liquid variables. The `event` key references trigger data for event-triggered automations.\n",
"additionalProperties": true
},
"lax": {
"type": "boolean",
"default": false,
"description": "Set to `true` to render a liquid variable your sample data doesn't cover as an empty string rather than failing the request. Only applies when you pass `customer_id` or `customer`; without sample data, the email renders this way anyway and the response includes a warning.\n"
},
"prepend_test": {
"type": "boolean",
"default": false,
"description": "Set to `true` to add `[TEST]` to the start of the subject line."
},
"tracked": {
"type": "boolean",
"description": "Set to `true` to add a tracking pixel or `false` to leave it out. If you don't pass this field, Customer.io uses the tracking setting of the workflow message the email is linked to, and adds the pixel when the email isn't linked to a workflow message. Customer.io never adds the pixel for unverified accounts.\n"
},
"trigger": {
"type": [
"object",
"null"
],
"description": "Sample trigger data for `trigger.*` liquid variables. The `trigger` key references trigger data for these specific workflows: API-triggered broadcasts or transactional messages.\n",
"additionalProperties": true
}
}
},
"TestSendEmailResponse": {
"type": "object",
"properties": {
"accepted": {
"type": "boolean",
"description": "Always `true` in a 200 response. Anything that stops the send returns a 4xx instead. Acceptance isn't proof of delivery."
},
"from": {
"type": "string",
"description": "The rendered `From` header the test was sent with.\n"
},
"language": {
"type": "string",
"description": "The language code if the message is a language variant. Omitted for the default-language node."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The email node that was tested."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "The response represents an email."
},
"subject": {
"type": "string",
"description": "The rendered subject line, including the `[TEST]` prefix if you set `prepend_test`."
},
"to": {
"type": "array",
"items": {
"type": "string"
},
"description": "The recipients the test was sent to."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "The ways this test differs from a real send. Customer.io delivered the email anyway, so read these before you trust what landed in the inbox. You might see that no profile data was available, that context a test send can't supply rendered as empty strings (like `campaign.*` or `message.*` on an email that isn't linked to a workflow), that Customer.io ignored a routing key like `recipient` or `from_address` in your `event` or `trigger` data, or that a recipient field in the template failed to render. That last one doesn't change who got the test: it goes only to the addresses in `to`. Omitted when there's nothing to report.\n"
}
},
"example": {
"accepted": true,
"from": "\"No reply\" <noreply@customer.io>",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL",
"subject": "[TEST] Welcome Ada",
"to": [
"pigeon@customer.io",
"penguin@customer.io"
]
}
},
"EmailReviewResponse": {
"type": "object",
"properties": {
"checks": {
"type": "object",
"description": "Per-check status, keyed by check name. See the endpoint description for the full list of checks.",
"additionalProperties": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Present when `status` is `degraded` or `error`. Explains what was missing or what failed."
},
"status": {
"type": "string",
"enum": [
"complete",
"degraded",
"error",
"skipped"
],
"description": "`complete`: findings are authoritative. `degraded`: the check ran on reduced input (for example, some URL validations failed) — its findings aren't authoritative. `error`: the check couldn't run and contributed no findings. `skipped`: the check has no server-side signal for API callers.\n"
}
}
}
},
"findings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"check": {
"type": "string",
"description": "Which check produced this finding."
},
"details": {
"type": "string",
"description": "Explanation and suggested fix. Omitted when there's nothing more to add beyond the title."
},
"id": {
"type": "string",
"description": "Identifier for this finding, unique within the response."
},
"severity": {
"type": "string",
"enum": [
"error",
"warning",
"tip"
],
"description": "Fix all errors to make sure your recipients get your email and you follow compliance requirements. Review warnings and tips to improve the quality of your email."
},
"state": {
"type": "string",
"enum": [
"pass",
"fail"
],
"description": "Whether this finding represents an issue. Passing findings don't affect the score."
},
"summary": {
"type": "string",
"description": "Location context, for example \"In the email body\". Omitted when there's no additional context."
},
"title": {
"type": "string",
"description": "Short human-readable title."
}
}
}
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the reviewed email node."
},
"score": {
"type": "object",
"description": "Readiness score. Omitted when `status` is `render_failed`.",
"properties": {
"counts": {
"type": "object",
"description": "Finding counts by severity across all checks.",
"properties": {
"error": {
"type": "integer",
"description": "The number of failing `error` findings."
},
"tip": {
"type": "integer",
"description": "The number of failing `tip` findings."
},
"warning": {
"type": "integer",
"description": "The number of failing `warning` findings."
}
}
},
"score": {
"type": "integer",
"description": "0–100 readiness estimate. Starts at 100 and is reduced per failing finding. An error drops the score to 60 or below; fix all errors to make sure your recipients get your email and you follow compliance requirements. See **findings** to locate errors.\n"
}
}
},
"status": {
"type": "string",
"enum": [
"complete",
"partial",
"render_failed"
],
"description": "- `complete`: every check ran to completion. \n- `partial`: at least one check errored, ran on reduced input, or was skipped. `failed-components` is always skipped and doesn't [affect this status. If you get a `partial` status, send the request again after a few seconds to try to get a complete set of findings.\n- `render_failed`: the underlying render failed; no checks ran, `score` is omitted, and `findings` is empty. If it's a timeout, send the request again after a few seconds. If it's a content or compilation error, fix the email before sending the request again.\n"
}
},
"example": {
"checks": {
"liquid": {
"status": "complete"
},
"failed-components": {
"status": "skipped"
},
"source": {
"status": "complete"
},
"links": {
"status": "complete"
},
"images": {
"status": "complete"
},
"accessibility": {
"status": "complete"
},
"spam": {
"status": "complete"
},
"unsubscribe": {
"status": "complete"
},
"implied-links": {
"status": "complete"
},
"html-clip": {
"status": "complete"
},
"preheader": {
"status": "complete"
}
},
"findings": [
{
"check": "unsubscribe",
"details": "Add {% unsubscribe %} or use {% unsubscribe_url %} as the href.",
"id": "unsubscribe",
"severity": "warning",
"state": "fail",
"title": "No unsubscribe link"
},
{
"check": "preheader",
"details": "Add a short preheader to improve open rates.",
"id": "preheader",
"severity": "tip",
"state": "fail",
"title": "No preheader text"
}
],
"node_id": "887d804e-9199-4a65-ae26-315e825344bc",
"score": {
"counts": {
"error": 0,
"tip": 1,
"warning": 1
},
"score": 86
},
"status": "complete"
}
},
"EmailReviewScore": {
"type": "object",
"description": "Readiness score. Omitted when `status` is `render_failed`.",
"properties": {
"counts": {
"type": "object",
"description": "Finding counts by severity across all checks.",
"properties": {
"error": {
"type": "integer",
"description": "The number of failing `error` findings."
},
"tip": {
"type": "integer",
"description": "The number of failing `tip` findings."
},
"warning": {
"type": "integer",
"description": "The number of failing `warning` findings."
}
}
},
"score": {
"type": "integer",
"description": "0–100 readiness estimate. Starts at 100 and is reduced per failing finding. An error drops the score to 60 or below; fix all errors to make sure your recipients get your email and you follow compliance requirements. See **findings** to locate errors.\n"
}
}
},
"EmailReviewCheckStatus": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Present when `status` is `degraded` or `error`. Explains what was missing or what failed."
},
"status": {
"type": "string",
"enum": [
"complete",
"degraded",
"error",
"skipped"
],
"description": "`complete`: findings are authoritative. `degraded`: the check ran on reduced input (for example, some URL validations failed) — its findings aren't authoritative. `error`: the check couldn't run and contributed no findings. `skipped`: the check has no server-side signal for API callers.\n"
}
}
},
"EmailReviewFinding": {
"type": "object",
"properties": {
"check": {
"type": "string",
"description": "Which check produced this finding."
},
"details": {
"type": "string",
"description": "Explanation and suggested fix. Omitted when there's nothing more to add beyond the title."
},
"id": {
"type": "string",
"description": "Identifier for this finding, unique within the response."
},
"severity": {
"type": "string",
"enum": [
"error",
"warning",
"tip"
],
"description": "Fix all errors to make sure your recipients get your email and you follow compliance requirements. Review warnings and tips to improve the quality of your email."
},
"state": {
"type": "string",
"enum": [
"pass",
"fail"
],
"description": "Whether this finding represents an issue. Passing findings don't affect the score."
},
"summary": {
"type": "string",
"description": "Location context, for example \"In the email body\". Omitted when there's no additional context."
},
"title": {
"type": "string",
"description": "Short human-readable title."
}
}
},
"VersionSummary": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "The date-time the version was created."
},
"created_on_publish": {
"type": "boolean",
"description": "`false` if you [saved the email](/integrations/api/design-studio/tag/emails/saveVersion/). `true` if Design Studio created this version automatically when you [published the email](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/). You can't delete versions generated by Design Studio.\n"
},
"description": {
"type": "string",
"description": "Explanatory text you provided when creating a version. Omitted if no description."
},
"feedback": {
"type": "boolean",
"description": "`true` is you saved this version by creating a [round of feedback in Design Studio](/messaging/design-studio/collaboration/feedback/).\n"
},
"id": {
"type": "string",
"format": "uuid",
"description": "UUID of the version."
},
"name": {
"type": "string",
"description": "Name given to the version when it was saved."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the email node this version belongs to."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `\"EMAIL\"`."
}
},
"example": {
"created": 1773856017,
"created_on_publish": false,
"feedback": false,
"id": "8f14e45f-ceea-4c67-9814-b8f0e0e1a6f0",
"name": "Before holiday redesign",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL"
}
},
"VersionDependencyNode": {
"type": "object",
"description": "The code of the referenced custom component(s) in the node version.",
"properties": {
"component_name": {
"type": [
"string",
"null"
],
"description": "The component tag name when you saved this version."
},
"content": {
"type": "string",
"description": "HTML content as of the snapshot."
},
"name": {
"type": "string",
"description": "Display name of the component in Design Studio."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the component node."
},
"node_type": {
"type": "string",
"enum": [
"COMPONENT"
],
"description": "Always `COMPONENT`."
}
},
"example": {
"component_name": "footer",
"content": "<script>...</script><template>...</template>",
"name": "Footer",
"node_id": "1abcbb4e-402e-949e-f6732f333",
"node_type": "COMPONENT"
}
},
"VersionNode": {
"type": "object",
"description": "The content and settings stored in the version.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body as of the snapshot. Omitted if the email had none."
},
"content": {
"type": "string",
"description": "HTML content as of the snapshot. For the content of any referenced custom component, see `dependencies`."
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"name": {
"type": "string",
"description": "Display name of the email in Design Studio. If the version is a language variant, the title ends in the language code like \"Onboarding email (fr)\"."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the node."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `EMAIL` for the node."
},
"preheader_text": {
"type": "string",
"description": "Preview text as of the snapshot. Omitted if the email had none."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body as of the snapshot. Omitted if the email had none."
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
}
},
"example": {
"content": "<x-base>...</x-base>",
"envelope": {
"bcc": "",
"fake_bcc": true,
"from": "Customer.io <noreply@example.com>",
"from_id": 1,
"headers": [],
"recipient": "{{customer.email}}",
"reply_to": "",
"reply_to_id": null
},
"name": "Onboarding phase 1",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL",
"preheader_text": "Get started in minutes",
"subject": "Welcome to Design Studio!",
"transformers": {
"prevent_widows": {
"enabled": false
}
}
}
}
},
"responses": {
"BadRequest": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"Unauthorized": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"NotFound": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"Conflict": {
"description": "Conflict - linked resource or other constraint violation",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "a constraint violation prevents this operation",
"status": "409"
}
]
}
}
}
},
"PublishBackfilling": {
"description": "The destination automation is backfilling and can't accept content right now. This clears on its own—wait a moment and publish again.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "campaign is backfilling, please try publishing again in a moment",
"status": "409"
}
]
}
}
}
},
"PublishUnprocessable": {
"description": "The content or its destination can't be published as-is. Possible reasons:\n - The content has Liquid errors. The `meta` object lists them per language.\n - The destination won't accept content because it's archived, stopping, or being deleted.\n - The destination is linked to different Design Studio content than the item you're publishing.\n - The workspace has no language attribute configured, which multi-language publishing needs.\n - The language group is over the limit of 50 variants.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "liquid validation failed",
"meta": {
"es": [
"unexpected end of liquid tag"
]
},
"status": "422"
}
]
}
}
}
},
"InboxPreviewNotChargeable": {
"description": "Your account can't be charged for inbox preview credits right now. Credits are account-level—every workspace on the account draws from the same pools, so this isn't specific to the workspace in your credentials.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "this account cannot be charged for inbox previews",
"status": "403"
}
]
}
}
}
},
"InboxPreviewInsufficientCredits": {
"description": "Not enough inbox preview credits to cover every device in `client_ids`. The message names both figures, so you can size a top-up without a separate call to [Get preview credit balance](/integrations/api/design-studio/tag/email-testing/getInboxPreviewCredits/).",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "insufficient inbox preview credits: this request needs 12, the account has 4 available",
"status": "422"
}
]
}
}
}
},
"InboxPreviewSubmitConflict": {
"description": "A retry crossed an interrupted charge for this batch. This means one of two things:\n - The batch was already charged and settled today.\n - An earlier attempt at the same batch is still being reconciled.\n\nChange the devices or nodes you're previewing, or retry later. Either way, you weren't double-charged.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "this preview batch was already charged and settled today. Change the devices or nodes you are previewing, or try again tomorrow.",
"status": "409"
}
]
}
}
}
},
"TestSendRateLimited": {
"description": "Rate limited. Every request to this endpoint draws from two buckets: a per-workspace bucket (burst of 20, refilling one every 9 seconds), the same limit the dashboard applies to its own test sends, and a per-IP bucket (burst of 30, refilling one every 10 seconds) that catches one IP address spread across many accounts. Hitting either limit returns this response. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited",
"status": "429"
}
]
}
}
}
},
"InboxPreviewRateLimited": {
"description": "Rate limited to 5 requests per second per workspace—a bucket shared with the Design Studio link, publish, render, preview, and review endpoints, and tighter than the 10 per second reads get, because each call starts a server-side render before it reaches the vendor. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited to 5 requests per second",
"status": "429"
}
]
}
}
}
},
"InboxPreviewReadRateLimited": {
"description": "Over the App API's shared limit of 10 requests per second per workspace—the same bucket every call in your workspace that isn't separately rate limited draws from, writes included. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited to 10 requests per second",
"status": "429"
}
]
}
}
}
},
"InboxPreviewNotEnabled": {
"description": "Inbox previews aren't enabled for your account.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "inbox previews are not enabled for this account",
"status": "404"
}
]
}
}
}
},
"InboxPreviewRenderUnavailable": {
"description": "The email or Liquid renderer couldn't be reached. This is transient—retry in a moment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "the email renderer could not be reached; try again in a moment",
"status": "503"
}
]
}
}
}
},
"InboxPreviewCatalogUnavailable": {
"description": "The device catalog is temporarily unavailable. This is transient—retry in a moment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "service unavailable",
"status": "503"
}
]
}
}
}
}
},
"securitySchemes": {
"Bearer-Auth": {
"type": "http",
"scheme": "bearer",
"description": "The Design Studio API uses the same bearer authentication scheme as the App API.\n\nYou can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).\n"
}
}
},
"openapi": "3.1.0",
"info": {
"version": "1.0.0",
"title": "Customer.io Design Studio API",
"description": "# Overview\n\nDesign Studio is where you build and manage message content in Customer.io. These endpoints let you create and manage emails and SMS specifically:\n- Manage custom components, a way of reusing content across emails\n- Create emails and translations, including validating liquid, sending tests, and previewing in a variety of email clients\n- Create SMS messages\n- Link and publish emails and SMS to workflows\n\nYou can also add them to folders to keep them organized in the UI. \n\nTo manage assets like images and PDFs, use the [Assets endpoints](/integrations/api/app/tag/assets/).\n\nThe Design Studio and Assets APIs run on the same host as our [App API](/integrations/api/app/) and uses the same App API Key. \n\nWhen your email is ready to send, you can also use the [App API](/integrations/api/app/tag/send-messages/) to trigger API-triggered broadcasts, one-time sends, and transactional messages. You can't start an automation via API.\n\nDesign Studio has its own [extended HTML syntax](/messaging/design-studio/emails/code-editor/overview/#html) that we recommend using if you want to the option of editing content in the UI. Otherwise, you can use standard HTML syntax, but check out our [HTML and CSS best practices](/integrations/api/design-studio/integrate/#html-and-css-best-practices).\n\n# Build your integration to ignore fields it doesn't recognize\n\nAs we release new features, we add endpoints and we may even add fields to existing endpoints. We don't announce these additions in advance. Fields we add will be backward compatible: existing fields keep their names and types.\n\nBuild your integration to ignore fields it doesn't recognize. If you validate responses against a schema, make sure the schema accepts unknown keys. In JSON Schema, for example, don't set `additionalProperties: false`.\n\n# Use our Postman collection\n\nThe Design Studio requests are part of our App API Postman collection, in the **Design Studio API** folder. They use the same `app_api_url` variable and App API Key as the rest of the collection.\n\nWe update the collection automatically whenever we release changes to our documentation. If you fork it, you might want to turn off the *Watch original collection* option so you don't get a notification for each update.\n\n**NOTE**: Postman requests default to our US APIs. If you're in our European (EU) region, add `-eu` to the `app_api_url` variable.\n\n[<img src=\"https://run.pstmn.io/button.svg\" alt=\"Run In Postman\" style=\"width: 128px; height: 32px;\">](https://god.gw.postman.com/run-collection/23697545-2931c004-e63d-4cdc-bf4b-e685ba6da42d?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D23697545-2931c004-e63d-4cdc-bf4b-e685ba6da42d%26entityType%3Dcollection%26workspaceId%3Db886877f-fc09-475f-84fe-6221a98f4d18#?env%5BCustomer.io%20API%20Environment%5D=W3sia2V5IjoidHJhY2tfYXBpX3VybCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiJ0cmFjay5jdXN0b21lci5pbyIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBwX2FwaV91cmwiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiYXBpLmN1c3RvbWVyLmlvIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzaXRlX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBpX2tleSIsInR5cGUiOiJzZWNyZXQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYmVhcmVyIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYnJvYWRjYXN0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaW1wb3J0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZW1haWxfYWRkcmVzcyIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InN1cHByZXNzaW9uX3R5cGUiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjb2xsZWN0aW9uX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic25pcHBldF9uYW1lIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoid2ViaG9va19pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InNlbmRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImV4cG9ydF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Im1lc3NhZ2VfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzZWdtZW50X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibmV3c2xldHRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNvbnRlbnRfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjYW1wYWlnbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFjdGlvbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImN1c3RvbWVyX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidHJhbnNhY3Rpb25hbF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRyaWdnZXJfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJmb3JtX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaWRlbnRpZmllciIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRldmljZV9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRlbGl2ZXJ5X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9XQ==)\n\n# Server addresses: US and EU\n\nCustomer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.\n\n| Region | Server Address |\n| :-- | :-- |\n| US | https://api.customer.io |\n| EU | https://api-eu.customer.io |\n\n# Authentication\n\nAll requests to the Design Studio API use an [App API Key](#authentication), the same key you use for our App API.\n\nTo authenticate, provide your key as a Bearer token in a HTTP Authorization header. You can create and manage your API keys—including keys with different scopes—in [your account settings page](https://fly.customer.io/settings/api_credentials?keyType=app). Each operation on this page references the authorization header it requires.\n\n# Rate Limits\n\nDesign Studio endpoints share the App API limit of 10 requests per second per workspace. Every call in your workspace that isn't separately rate limited draws from this bucket, writes included. The exceptions are:\n* [Link](/integrations/api/design-studio/tag/email-email-link-and-publish/linkEmail/) and [publish](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/), [render](/integrations/api/design-studio/tag/email-testing/renderEmail/), [preview](/integrations/api/design-studio/tag/email-testing/previewEmail/), [review](/integrations/api/design-studio/tag/email-testing/reviewEmail/), and [inbox preview](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/) requests share a tighter bucket of 5 requests per second per workspace, because each call starts a server-side render.\n* [Test sends](/integrations/api/design-studio/tag/email-testing/testSendEmail/) draw from a per-workspace bucket (burst of 20, refilling one every 9 seconds) that you share with test sends from the dashboard, and a per-IP bucket (burst of 30, refilling one every 10 seconds).\n\nWhen you exceed a limit, the API returns a `429` response with a `Retry-After` header.\n\n**Rate limits are subject to change. We may adjust these thresholds to ensure stable performance for all customers.**\n"
},
"tags": [
{
"name": "Folders",
"description": "Folders organize your Design Studio files. Use these endpoints to list, create, rename, move, and delete folders. Folders hold emails, SMS, and components, but these endpoints return folders only; list the [emails](/integrations/api/design-studio/tag/emails/), [SMS](/integrations/api/design-studio/tag/sms/), or [components](/integrations/api/design-studio/tag/components/) in a folder with their own endpoints.\n"
},
{
"name": "Components",
"description": "Custom components are reusable blocks of content that you build once and reference from any email. Use these endpoints to list, create, update, and delete custom components.\n\nUpdating a component through the API changes the component itself. It doesn't publish the change to the messages that reference the component; you do that from your workspace.\n"
},
{
"name": "Emails",
"description": "Create and manage the emails you build in Design Studio, along with their translations and versions.\n\n- **Emails** hold the content, envelope details, and transformers for the default language.\n- **Translations** are language variants of an email. Each one has its own content and envelope.\n- **Versions** are named checkpoints of an email's content. Design Studio saves one automatically every time you publish, and you can save, inspect, restore, or delete them yourself.\n\nLearn more about the [best practices](/integrations/api/design-studio/integrate/) for sending HTML through these endpoints.\n"
},
{
"name": "Email link and publish",
"description": "A Design Studio email doesn't send anything on its own. You [link](/integrations/api/design-studio/tag/email-email-link-and-publish/linkEmail/) it to a single workflow, like an email action in an automation, a one-time send, a transactional message, or an API-triggered broadcast. Then you [publish](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) to push your updates from Design Studio to that workflow.\n\nPublishing covers the default language and every translation. Multi-language publishes run in the background; poll [publish status](/integrations/api/design-studio/tag/email-email-link-and-publish/getPublishStatus/) to see when they finish, and check for [unpublished changes](/integrations/api/design-studio/tag/email-email-link-and-publish/checkUnpublishedChanges/) to find out whether the linked workflow is behind the draft.\n"
},
{
"name": "Email testing",
"description": "Check an email before you publish or send it.\n\n- [Render](/integrations/api/design-studio/tag/email-testing/renderEmail/) returns the compiled HTML with liquid left intact.\n- [Preview](/integrations/api/design-studio/tag/email-testing/previewEmail/) evaluates liquid against a real profile or sample data.\n- [Review](/integrations/api/design-studio/tag/email-testing/reviewEmail/) reports issues that could stop the email from sending or breach compliance standards.\n- [Test send](/integrations/api/design-studio/tag/email-testing/testSendEmail/) delivers the email to addresses you choose.\n- **Inbox previews** render the email in real email clients. [Submit a job](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/), poll it, then fetch each capture. Inbox previews use credits; check your balance and the available clients with the account-level endpoints in this section.\n"
},
{
"name": "SMS",
"description": "Create and manage the SMS messages you write in Design Studio.\n\nThese endpoints only work if your workspace writes SMS in Design Studio. Workspaces that set up SMS on or after July 30, 2026 do. If your workspace set up Twilio before July 30, 2026, it uses our original Twilio integration instead: you write each SMS in the workflow that sends it, and you can't use these endpoints. To check which one your workspace uses, go to Design Studio and click **Create**. If **SMS** is one of the options, you can use these endpoints.\n\nTo organize your SMS into folders, use the [Folders](/integrations/api/design-studio/tag/folders/) endpoints.\n"
},
{
"name": "SMS link and publish",
"description": "A Design Studio SMS doesn't send anything on its own. After you [create](/integrations/api/design-studio/tag/sms/createSms/) an SMS, you [link](/integrations/api/design-studio/tag/sms-link-and-publish/linkSms/) it to a single workflow, like an SMS action in an automation or a transactional message. Then you [publish](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) to push your updates from Design Studio to that workflow.\n"
}
],
"x-tagGroups": [
{
"name": "Shared",
"tags": [
"Folders",
"Components"
]
},
{
"name": "Email",
"tags": [
"Emails",
"Email link and publish",
"Email testing"
]
},
{
"name": "SMS",
"tags": [
"SMS",
"SMS link and publish"
]
}
],
"servers": [
{
"url": "https://api.customer.io",
"description": "The base URL for the Design Studio API. These endpoints use bearer authorization, and require an [App API Key that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app)."
},
{
"url": "https://api-eu.customer.io",
"description": "The base URL for the Design Studio API (EU region). These endpoints use bearer authorization, and require an [App API Key that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app)."
}
],
"paths": {
"/v1/design_studio/folders": {
"get": {
"tags": [
"Folders"
],
"summary": "List folders",
"operationId": "listFolders",
"security": [
{
"Bearer-Auth": []
}
],
"description": "Returns a paginated list of folders. This does not include files like emails, components, etc.\n",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page number of results you want to display. Use with `limit`.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "limit",
"in": "query",
"description": "The maximum number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 1000
}
},
{
"name": "parent_folder_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Filter by parent folder. Must reference an existing folder. If not set, the response filters by the root level directory.\n\nTo list only items in the root folder, leave `parent_folder_id` unset and only set `direct_descendants_only` to `true`.\n"
},
{
"name": "direct_descendants_only",
"in": "query",
"description": "When `true`, the response includes only the immediate children of the parent folder. When `false`, it includes the parent folder's entire subtree.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "sort_by",
"in": "query",
"schema": {
"type": "string",
"enum": [
"created",
"updated",
"name"
],
"default": "created"
}
},
{
"name": "sort_order",
"in": "query",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "created_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created before this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "created_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created after this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "updated_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated before this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "updated_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated after this time. Must be a unix timestamp.",
"example": 1773856017
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"folders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the folder was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of folder"
},
"name": {
"type": "string",
"description": "The name of the folder."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory."
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the folder."
}
},
"example": {
"created": 1714732800,
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Product Announcements",
"parent_folder_id": null,
"updated": 1714732800
}
}
},
"meta": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"description": "The filters applied in your request.",
"example": {
"parent_folder_id": "123e4567-e89b-12d3-a456-426614174000",
"direct_descendants_only": true,
"sort_by": "created",
"sort_order": "desc",
"created_before": 1714732800,
"created_after": null,
"updated_before": null,
"updated_after": null
}
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "The number of results per page."
},
"page": {
"type": "integer",
"description": "The page number of results you're on."
},
"total": {
"type": "integer",
"description": "The total number of folders."
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "invalid query parameter",
"status": "400"
}
]
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Folders"
],
"summary": "Create a folder",
"description": "Create a new folder at the root level or under a parent folder. To create a child folder, you need the UUID of the parent folder, which you can retrieve with [List folders](/integrations/api/design-studio/tag/folders/listFolders/).\n",
"operationId": "createFolder",
"security": [
{
"Bearer-Auth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the folder. Cannot contain these characters: < > : \" / \\ | ? * .\n",
"minLength": 1,
"maxLength": 170,
"example": "Product Announcements"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"description": "UUID of the parent folder. Omit or pass `null` to create at root.",
"format": "uuid"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Folder created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"folder": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the folder was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of folder"
},
"name": {
"type": "string",
"description": "The name of the folder."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory."
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the folder."
}
},
"example": {
"created": 1714732800,
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Product Announcements",
"parent_folder_id": null,
"updated": 1714732800
}
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"detail": {
"description": "The name is missing or invalid, the parent folder id is an empty string, or there's an unknown JSON field in the request body",
"type": "string"
},
"status": {
"description": "Response code",
"type": "string"
}
}
}
}
},
"example": {
"errors": [
{
"detail": "missing or invalid name",
"status": "400"
}
]
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Response not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "parent folder not found",
"status": "404"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"name\": \"Product Announcements\",\n \"parent_folder_id\": null\n}"
}
]
}
},
"/v1/design_studio/folders/{id}": {
"get": {
"tags": [
"Folders"
],
"summary": "Get a folder",
"description": "Get a folder by its UUID. You can retrieve the UUID of folders through [List folders](/integrations/api/design-studio/tag/folders/listFolders/).\n",
"operationId": "getFolder",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the folder.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"folder": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the folder was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of folder"
},
"name": {
"type": "string",
"description": "The name of the folder."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory."
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the folder."
}
},
"example": {
"created": 1714732800,
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Product Announcements",
"parent_folder_id": null,
"updated": 1714732800
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"put": {
"tags": [
"Folders"
],
"summary": "Update a folder",
"description": "Update part of a folder: the name and/or the folder it belongs to. If you move a folder, all files stay nested in the folder.\n",
"operationId": "updateFolder",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the folder.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the folder. Cannot contain any of these characters: < > : \" / \\ | ? * .\n",
"minLength": 1,
"maxLength": 170
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The UUID of the parent folder.\n\nOmit if you want no change to where the folder or file is located. Include `null` to move it to your root directory. Or add the UUID of another folder to move it there.\n"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Successful response, no content returned"
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"detail": {
"description": "Possible reasons for error: No fields provided, invalid name, parent_folder_id is an empty string or not a valid place to move the folder to, or unknown JSON field in request body\n",
"type": "string"
},
"status": {
"description": "Response code",
"type": "string"
}
}
}
}
},
"example": {
"errors": [
{
"detail": "missing or invalid name",
"status": "400"
}
]
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"name\": \"\",\n \"parent_folder_id\": null\n}"
}
]
},
"delete": {
"tags": [
"Folders"
],
"summary": "Delete a folder",
"description": "Delete a folder **including subfolders and all file (components, templates, and emails)**. You cannot delete a folder with emails used in your workflows (automations, broadcasts, etc).\n\nHowever, you can delete a folder with components that are referenced in emails linked to workflows, so make sure deleting a folder with components won't break your emails.\n",
"operationId": "deleteFolder",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the folder.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Successful response, no content returned"
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "Conflict - linked resource or other constraint violation",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "a constraint violation prevents this operation",
"status": "409"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails": {
"get": {
"tags": [
"Emails"
],
"summary": "List emails",
"description": "Returns a paginated list of emails and a separate array of folders that the emails belong to.\n",
"operationId": "listEmails",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page number of results you want to display. Use with `limit`.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "limit",
"in": "query",
"description": "The maximum number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 1000
}
},
{
"name": "parent_folder_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Filter by parent folder. Must reference an existing folder. If not set, the response filters by the root level directory.\n\nTo list only items in the root folder, leave `parent_folder_id` unset and only set `direct_descendants_only` to `true`.\n"
},
{
"name": "direct_descendants_only",
"in": "query",
"description": "When `true`, the response includes only the immediate children of the parent folder. When `false`, it includes the parent folder's entire subtree.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "sort_by",
"in": "query",
"schema": {
"type": "string",
"enum": [
"created",
"updated",
"name"
],
"default": "created"
}
},
{
"name": "sort_order",
"in": "query",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "created_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created before this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "created_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created after this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "updated_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated before this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "updated_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated after this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "is_template",
"description": "Filter by whether the email is a template",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"any"
],
"default": "any"
}
},
{
"name": "has_translations",
"description": "Filter by whether the email has translations",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"any"
],
"default": "any"
}
},
{
"name": "is_linked",
"description": "Filter by whether the email is linked to a workflow (automation, broadcast, etc).",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"any"
],
"default": "any"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the email was created.",
"example": 1714732800
},
"has_translations": {
"type": "boolean",
"description": "Whether the email has translations"
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of email",
"example": "sdflkj345"
},
"is_linked": {
"type": "boolean",
"description": "Whether the email is linked to a workflow (automation, broadcast, etc)"
},
"is_template": {
"type": "boolean",
"description": "Whether the email is a template"
},
"name": {
"type": "string",
"description": "The name of the email"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the email.",
"example": 1714732800
}
}
}
},
"folders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the folder was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of folder"
},
"name": {
"type": "string",
"description": "The name of the folder."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory."
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the folder."
}
},
"example": {
"created": 1714732800,
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Product Announcements",
"parent_folder_id": null,
"updated": 1714732800
}
}
},
"meta": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"description": "The filters applied in your request.",
"example": {
"parent_folder_id": "123e4567-e89b-12d3-a456-426614174000",
"direct_descendants_only": true,
"sort_by": "created",
"sort_order": "desc",
"created_before": 1714732800,
"created_after": null,
"updated_before": null,
"updated_after": null
}
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "The number of results per page."
},
"page": {
"type": "integer",
"description": "The page number of results you're on."
},
"total": {
"type": "integer",
"description": "The total number of folders."
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "invalid query parameter",
"status": "400"
}
]
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Emails"
],
"summary": "Create an email",
"description": "Create an email. Note, you can create an email without filling out all required fields for sending. You can fill in the envelope, like a to and from address, with this method, but that's not required until you link it to a workflow like an automation.",
"operationId": "createEmail",
"security": [
{
"Bearer-Auth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name of the email."
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"envelope": {
"type": "object",
"description": "The envelope of your email, like from and to addresses.",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID. Must reference an existing identity. You can find this in *Workspace Settings > Email* under your From Addresses.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient email address. Defaults to `{{customer.email}}`` if not set.\n"
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Reply-to identity ID. Must reference an existing identity from *Workspace Settings > Email* under your From Addresses.\n"
}
}
},
"is_template": {
"type": "boolean",
"default": false,
"description": "Whether the email is a reusable template."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder. Omit or pass `null` to create at root."
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Email created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"available_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of [language codes](/journeys/channels/localization/attribute/#supported-languages) that reflect the languages this default email has been translated to.",
"example": [
"en",
"es"
]
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the email was created.",
"example": 1773856017
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the email.",
"example": "sdflkj345"
},
"is_linked": {
"type": "boolean",
"description": "Whether the email is currently linked to a workflow (automation, broadcast, etc).\n"
},
"is_template": {
"type": "boolean",
"description": "Whether the email is a reusable template."
},
"name": {
"type": "string",
"description": "Display name of the email."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder, or `null` if the email is in your root directory.\n"
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
},
"updated": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the email.",
"example": 1773856017
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons:\n - Missing or invalid name\n - Missing content or any required content sub-field\n - Unknown JSON field in content, envelope, or transformers\n - from_id or reply_to_id does not reference an existing identity\n - parent_folder_id is an empty string\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"name\": \"\",\n \"content\": {\n \"amp\": \"\",\n \"html\": \"\",\n \"preheader_text\": \"\",\n \"subject\": \"\",\n \"text\": \"\"\n },\n \"envelope\": {\n \"bcc\": \"\",\n \"fake_bcc\": true,\n \"from_id\": null,\n \"headers\": [\n {\n \"name\": \"\",\n \"value\": \"\"\n }\n ],\n \"recipient\": \"\",\n \"reply_to_id\": null\n },\n \"is_template\": false,\n \"parent_folder_id\": null,\n \"transformers\": {\n \"accessibility\": {\n \"add_dir_to_content\": true,\n \"add_dir_to_html\": true,\n \"add_empty_alt_to_images\": true,\n \"add_lang_to_content\": true,\n \"add_lang_to_html\": true,\n \"add_role_to_tables\": true,\n \"add_title_to_head\": true,\n \"add_vml_alt_text\": true,\n \"enabled\": false,\n \"language\": \"\",\n \"remove_button_role_from_links\": true,\n \"remove_zoom_meta_tag\": true\n },\n \"css_inliner\": {\n \"apply_html_attributes\": {\n \"apply_height_attributes\": true,\n \"apply_table_element_attributes\": true,\n \"apply_width_attributes\": true,\n \"enabled\": true\n },\n \"apply_style_tags\": true,\n \"enabled\": false,\n \"inline_pseudo_elements\": false,\n \"preserve_font_faces\": true,\n \"preserve_important\": false,\n \"preserve_keyframes\": true,\n \"preserve_media_queries\": true,\n \"preserve_pseudos\": true,\n \"remove_style_tags\": true\n },\n \"css_variables\": {\n \"enabled\": false,\n \"preserve\": false\n },\n \"encode_entities\": {\n \"enabled\": false\n },\n \"formatter\": {\n \"minify\": {\n \"line_length_limit\": 500,\n \"remove_css_comments\": true,\n \"remove_html_comments\": \"0\",\n \"remove_indentations\": true,\n \"remove_line_breaks\": false\n },\n \"prettify\": {\n \"indent_character\": \"spaces\",\n \"indent_size\": 2,\n \"wrap_attributes\": false\n },\n \"type\": \"none\"\n },\n \"prevent_widows\": {\n \"enabled\": false\n },\n \"remove_unused_css\": {\n \"backend_markers\": [\n {\n \"heads\": \"\",\n \"tails\": \"\"\n },\n {\n \"heads\": \"{%\",\n \"tails\": \"%}\"\n }\n ],\n \"enabled\": false,\n \"uglify\": false,\n \"whitelist\": [\n \"\"\n ]\n },\n \"url_parameters\": {\n \"enabled\": false,\n \"parameters\": []\n }\n }\n}"
}
]
}
},
"/v1/design_studio/emails/{id}": {
"get": {
"tags": [
"Emails"
],
"summary": "Get an email",
"description": "Returns a single email including content, envelope details, and transformers. This endpoint returns only default emails; see [Email translations](/integrations/api/design-studio/tag/emails/createEmailTranslation/) to access language variants.\n",
"operationId": "getEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "object",
"properties": {
"available_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of [language codes](/journeys/channels/localization/attribute/#supported-languages) that reflect the languages this default email has been translated to.",
"example": [
"en",
"es"
]
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the email was created.",
"example": 1773856017
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the email.",
"example": "sdflkj345"
},
"is_linked": {
"type": "boolean",
"description": "Whether the email is currently linked to a workflow (automation, broadcast, etc).\n"
},
"is_template": {
"type": "boolean",
"description": "Whether the email is a reusable template."
},
"name": {
"type": "string",
"description": "Display name of the email."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder, or `null` if the email is in your root directory.\n"
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
},
"updated": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the email.",
"example": 1773856017
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"put": {
"tags": [
"Emails"
],
"summary": "Update an email",
"description": "Update part of an email: an email's name, template status, folder, content, envelope, or transformers. Note, this does not publish your email; if the email is linked to a workflow like an automation, you still need to click publish to make the changes live.\n",
"operationId": "updateEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"description": "You must provide a body with at least one of the following properties. Omitting a field leaves it unchanged.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"envelope": {
"type": "object",
"description": "The envelope of your email, like from and to addresses.",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID. Must reference an existing identity. You can find this in *Workspace Settings > Email* under your From Addresses.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient email address. Defaults to `{{customer.email}}`` if not set.\n"
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Reply-to identity ID. Must reference an existing identity from *Workspace Settings > Email* under your From Addresses.\n"
}
}
},
"is_template": {
"type": "boolean",
"description": "Whether the email is a reusable template."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name of the email."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The UUID of the parent folder.\n\nOmit if you want no change to where the folder or file is located. Include `null` to move it to your root directory. Or add the UUID of another folder to move it there.\n"
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
}
}
}
}
}
},
"responses": {
"204": {
"description": "Email updated, no content returned"
},
"400": {
"description": "Bad request. Possible reasons:\n - No fields provided\n - Invalid name\n - Unknown JSON field in content, envelope, or transformers\n - from_id or reply_to_id does not reference an existing identity\n - parent_folder_id is an empty string\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"content\": {\n \"amp\": \"\",\n \"html\": \"\",\n \"preheader_text\": \"\",\n \"subject\": \"\",\n \"text\": \"\"\n },\n \"envelope\": {\n \"bcc\": \"\",\n \"fake_bcc\": true,\n \"from_id\": null,\n \"headers\": [\n {\n \"name\": \"\",\n \"value\": \"\"\n }\n ],\n \"recipient\": \"\",\n \"reply_to_id\": null\n },\n \"is_template\": true,\n \"name\": \"\",\n \"parent_folder_id\": null,\n \"transformers\": {\n \"accessibility\": {\n \"add_dir_to_content\": true,\n \"add_dir_to_html\": true,\n \"add_empty_alt_to_images\": true,\n \"add_lang_to_content\": true,\n \"add_lang_to_html\": true,\n \"add_role_to_tables\": true,\n \"add_title_to_head\": true,\n \"add_vml_alt_text\": true,\n \"enabled\": false,\n \"language\": \"\",\n \"remove_button_role_from_links\": true,\n \"remove_zoom_meta_tag\": true\n },\n \"css_inliner\": {\n \"apply_html_attributes\": {\n \"apply_height_attributes\": true,\n \"apply_table_element_attributes\": true,\n \"apply_width_attributes\": true,\n \"enabled\": true\n },\n \"apply_style_tags\": true,\n \"enabled\": false,\n \"inline_pseudo_elements\": false,\n \"preserve_font_faces\": true,\n \"preserve_important\": false,\n \"preserve_keyframes\": true,\n \"preserve_media_queries\": true,\n \"preserve_pseudos\": true,\n \"remove_style_tags\": true\n },\n \"css_variables\": {\n \"enabled\": false,\n \"preserve\": false\n },\n \"encode_entities\": {\n \"enabled\": false\n },\n \"formatter\": {\n \"minify\": {\n \"line_length_limit\": 500,\n \"remove_css_comments\": true,\n \"remove_html_comments\": \"0\",\n \"remove_indentations\": true,\n \"remove_line_breaks\": false\n },\n \"prettify\": {\n \"indent_character\": \"spaces\",\n \"indent_size\": 2,\n \"wrap_attributes\": false\n },\n \"type\": \"none\"\n },\n \"prevent_widows\": {\n \"enabled\": false\n },\n \"remove_unused_css\": {\n \"backend_markers\": [\n {\n \"heads\": \"\",\n \"tails\": \"\"\n },\n {\n \"heads\": \"{%\",\n \"tails\": \"%}\"\n }\n ],\n \"enabled\": false,\n \"uglify\": false,\n \"whitelist\": [\n \"\"\n ]\n },\n \"url_parameters\": {\n \"enabled\": false,\n \"parameters\": []\n }\n }\n}"
}
]
},
"delete": {
"tags": [
"Emails"
],
"summary": "Delete an email",
"description": "Delete an email. You cannot delete an email that is linked to a workflow (automation, broadcast, etc). This deletes the email and all translations.\n",
"operationId": "deleteEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Email deleted"
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "Email is linked to a journey and cannot be deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "cannot delete email because it is linked",
"status": "409"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/languages": {
"get": {
"tags": [
"Emails"
],
"summary": "List email translations",
"description": "Returns all translations for an email. Each translation contains the email's content, envelope, and transformers for a specific language.\n",
"operationId": "listEmailTranslations",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email_translations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"available_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of [language codes](/journeys/channels/localization/attribute/#supported-languages) that reflect the languages this default email has been translated to.",
"example": [
"en",
"es"
]
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"created": {
"type": "integer",
"description": "Unix timestamp of when the translation was created.",
"example": 1773856017
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"is_linked": {
"type": "boolean",
"description": "Whether the translation is linked to a workflow (automation, broadcast, etc)"
},
"is_template": {
"type": "boolean",
"description": "Whether the translation is a template"
},
"language": {
"type": "string",
"description": "The [language code](/journeys/channels/localization/attribute/#supported-languages) of the translation",
"example": "fr"
},
"language_group_id": {
"type": "string",
"format": "uuid",
"description": "ID of the parent email that groups all translations. Same as the id in the path parameter."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder, or `null` if the email is in your root directory."
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
},
"updated": {
"type": "integer",
"description": "Unix timestamp of the last update to the translation.",
"example": 1773856017
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Emails"
],
"summary": "Create an email translation",
"description": "Creates a new translation for an email. If content, envelope, and/or transformers are omitted, the values are copied from the default (parent) email.\n",
"operationId": "createEmailTranslation",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"description": "How content is inherited from the default, parent email:\n - If both `content` and `envelope` are omitted: envelope (including subject and preheader) is copied verbatim from the parent email\n - If `content` is provided but `envelope` is omitted: the envelope is reconstructed from the parent’s envelope settings, using the new subject and preheader\n - If `envelope` is provided but `content` is omitted: the provided envelope is used with the parent’s subject and preheader\n - HTML, AMP, and text body fields are always copied from parent if `content` is omitted\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"language"
],
"properties": {
"language": {
"type": "string",
"description": "A [language code](/journeys/channels/localization/attribute/#supported-languages) that corresponds to the language of the translation",
"example": "es"
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"envelope": {
"type": "object",
"description": "The envelope of your email, like from and to addresses.",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID. Must reference an existing identity. You can find this in *Workspace Settings > Email* under your From Addresses.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient email address. Defaults to `{{customer.email}}`` if not set.\n"
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Reply-to identity ID. Must reference an existing identity from *Workspace Settings > Email* under your From Addresses.\n"
}
}
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Translation created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email_translation": {
"type": "object",
"properties": {
"available_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of [language codes](/journeys/channels/localization/attribute/#supported-languages) that reflect the languages this default email has been translated to.",
"example": [
"en",
"es"
]
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"created": {
"type": "integer",
"description": "Unix timestamp of when the translation was created.",
"example": 1773856017
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"is_linked": {
"type": "boolean",
"description": "Whether the translation is linked to a workflow (automation, broadcast, etc)"
},
"is_template": {
"type": "boolean",
"description": "Whether the translation is a template"
},
"language": {
"type": "string",
"description": "The [language code](/journeys/channels/localization/attribute/#supported-languages) of the translation",
"example": "fr"
},
"language_group_id": {
"type": "string",
"format": "uuid",
"description": "ID of the parent email that groups all translations. Same as the id in the path parameter."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder, or `null` if the email is in your root directory."
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
},
"updated": {
"type": "integer",
"description": "Unix timestamp of the last update to the translation.",
"example": 1773856017
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons:\n - Missing language\n - Invalid language code\n - Missing required content sub-field when content is provided\n - Unknown JSON field in content, envelope, or transformers\n - from_id or reply_to_id does not reference an existing identity\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "Conflict - linked resource or other constraint violation",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "a constraint violation prevents this operation",
"status": "409"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"language\": \"es\",\n \"content\": {\n \"amp\": \"\",\n \"html\": \"\",\n \"preheader_text\": \"\",\n \"subject\": \"\",\n \"text\": \"\"\n },\n \"envelope\": {\n \"bcc\": \"\",\n \"fake_bcc\": true,\n \"from_id\": null,\n \"headers\": [\n {\n \"name\": \"\",\n \"value\": \"\"\n }\n ],\n \"recipient\": \"\",\n \"reply_to_id\": null\n },\n \"transformers\": {\n \"accessibility\": {\n \"add_dir_to_content\": true,\n \"add_dir_to_html\": true,\n \"add_empty_alt_to_images\": true,\n \"add_lang_to_content\": true,\n \"add_lang_to_html\": true,\n \"add_role_to_tables\": true,\n \"add_title_to_head\": true,\n \"add_vml_alt_text\": true,\n \"enabled\": false,\n \"language\": \"\",\n \"remove_button_role_from_links\": true,\n \"remove_zoom_meta_tag\": true\n },\n \"css_inliner\": {\n \"apply_html_attributes\": {\n \"apply_height_attributes\": true,\n \"apply_table_element_attributes\": true,\n \"apply_width_attributes\": true,\n \"enabled\": true\n },\n \"apply_style_tags\": true,\n \"enabled\": false,\n \"inline_pseudo_elements\": false,\n \"preserve_font_faces\": true,\n \"preserve_important\": false,\n \"preserve_keyframes\": true,\n \"preserve_media_queries\": true,\n \"preserve_pseudos\": true,\n \"remove_style_tags\": true\n },\n \"css_variables\": {\n \"enabled\": false,\n \"preserve\": false\n },\n \"encode_entities\": {\n \"enabled\": false\n },\n \"formatter\": {\n \"minify\": {\n \"line_length_limit\": 500,\n \"remove_css_comments\": true,\n \"remove_html_comments\": \"0\",\n \"remove_indentations\": true,\n \"remove_line_breaks\": false\n },\n \"prettify\": {\n \"indent_character\": \"spaces\",\n \"indent_size\": 2,\n \"wrap_attributes\": false\n },\n \"type\": \"none\"\n },\n \"prevent_widows\": {\n \"enabled\": false\n },\n \"remove_unused_css\": {\n \"backend_markers\": [\n {\n \"heads\": \"\",\n \"tails\": \"\"\n },\n {\n \"heads\": \"{%\",\n \"tails\": \"%}\"\n }\n ],\n \"enabled\": false,\n \"uglify\": false,\n \"whitelist\": [\n \"\"\n ]\n },\n \"url_parameters\": {\n \"enabled\": false,\n \"parameters\": []\n }\n }\n}"
}
]
}
},
"/v1/design_studio/emails/{id}/languages/{language}": {
"get": {
"tags": [
"Emails"
],
"summary": "Get an email translation",
"description": "Returns a single email translation by language code, including content, envelope, and transformers.\n",
"operationId": "getEmailTranslation",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "language",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "A [language code](/journeys/channels/localization/attribute/#supported-languages) that indicates the language of your translated email"
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email_translation": {
"type": "object",
"properties": {
"available_languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of [language codes](/journeys/channels/localization/attribute/#supported-languages) that reflect the languages this default email has been translated to.",
"example": [
"en",
"es"
]
},
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"created": {
"type": "integer",
"description": "Unix timestamp of when the translation was created.",
"example": 1773856017
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"is_linked": {
"type": "boolean",
"description": "Whether the translation is linked to a workflow (automation, broadcast, etc)"
},
"is_template": {
"type": "boolean",
"description": "Whether the translation is a template"
},
"language": {
"type": "string",
"description": "The [language code](/journeys/channels/localization/attribute/#supported-languages) of the translation",
"example": "fr"
},
"language_group_id": {
"type": "string",
"format": "uuid",
"description": "ID of the parent email that groups all translations. Same as the id in the path parameter."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder, or `null` if the email is in your root directory."
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
},
"updated": {
"type": "integer",
"description": "Unix timestamp of the last update to the translation.",
"example": 1773856017
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"put": {
"tags": [
"Emails"
],
"summary": "Update an email translation",
"description": "Update part of an email translation: the content, envelope, or transformers for a specific email translation. Note, this does not publish your email; if the email is linked to a workflow like an automation, you still need to click publish to make the changes live.\n",
"operationId": "updateEmailTranslation",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "language",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "A [language code](/journeys/channels/localization/attribute/#supported-languages) that indicates the language of your translated email"
}
],
"requestBody": {
"required": true,
"description": "You must provide a body with at least one of the following properties. Omitting a field leaves it unchanged.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "object",
"description": "The content of your email.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body."
},
"html": {
"type": "string",
"description": "HTML body."
},
"preheader_text": {
"type": "string",
"description": "Preview text."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body."
}
}
},
"envelope": {
"type": "object",
"description": "The envelope of your email, like from and to addresses.",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID. Must reference an existing identity. You can find this in *Workspace Settings > Email* under your From Addresses.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient email address. Defaults to `{{customer.email}}`` if not set.\n"
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Reply-to identity ID. Must reference an existing identity from *Workspace Settings > Email* under your From Addresses.\n"
}
}
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
}
}
}
}
}
},
"responses": {
"204": {
"description": "Translation updated"
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"content\": {\n \"amp\": \"\",\n \"html\": \"\",\n \"preheader_text\": \"\",\n \"subject\": \"\",\n \"text\": \"\"\n },\n \"envelope\": {\n \"bcc\": \"\",\n \"fake_bcc\": true,\n \"from_id\": null,\n \"headers\": [\n {\n \"name\": \"\",\n \"value\": \"\"\n }\n ],\n \"recipient\": \"\",\n \"reply_to_id\": null\n },\n \"transformers\": {\n \"accessibility\": {\n \"add_dir_to_content\": true,\n \"add_dir_to_html\": true,\n \"add_empty_alt_to_images\": true,\n \"add_lang_to_content\": true,\n \"add_lang_to_html\": true,\n \"add_role_to_tables\": true,\n \"add_title_to_head\": true,\n \"add_vml_alt_text\": true,\n \"enabled\": false,\n \"language\": \"\",\n \"remove_button_role_from_links\": true,\n \"remove_zoom_meta_tag\": true\n },\n \"css_inliner\": {\n \"apply_html_attributes\": {\n \"apply_height_attributes\": true,\n \"apply_table_element_attributes\": true,\n \"apply_width_attributes\": true,\n \"enabled\": true\n },\n \"apply_style_tags\": true,\n \"enabled\": false,\n \"inline_pseudo_elements\": false,\n \"preserve_font_faces\": true,\n \"preserve_important\": false,\n \"preserve_keyframes\": true,\n \"preserve_media_queries\": true,\n \"preserve_pseudos\": true,\n \"remove_style_tags\": true\n },\n \"css_variables\": {\n \"enabled\": false,\n \"preserve\": false\n },\n \"encode_entities\": {\n \"enabled\": false\n },\n \"formatter\": {\n \"minify\": {\n \"line_length_limit\": 500,\n \"remove_css_comments\": true,\n \"remove_html_comments\": \"0\",\n \"remove_indentations\": true,\n \"remove_line_breaks\": false\n },\n \"prettify\": {\n \"indent_character\": \"spaces\",\n \"indent_size\": 2,\n \"wrap_attributes\": false\n },\n \"type\": \"none\"\n },\n \"prevent_widows\": {\n \"enabled\": false\n },\n \"remove_unused_css\": {\n \"backend_markers\": [\n {\n \"heads\": \"\",\n \"tails\": \"\"\n },\n {\n \"heads\": \"{%\",\n \"tails\": \"%}\"\n }\n ],\n \"enabled\": false,\n \"uglify\": false,\n \"whitelist\": [\n \"\"\n ]\n },\n \"url_parameters\": {\n \"enabled\": false,\n \"parameters\": []\n }\n }\n}"
}
]
},
"delete": {
"tags": [
"Emails"
],
"summary": "Delete an email translation",
"description": "Delete a specific language translation from an email. This fails if the email is linked to a workflow (automation, broadcast, etc).\n",
"operationId": "deleteEmailTranslation",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "language",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "A [language code](/journeys/channels/localization/attribute/#supported-languages) that indicates the language of your translated email"
}
],
"responses": {
"204": {
"description": "Translation deleted"
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "Conflict - linked resource or other constraint violation",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "a constraint violation prevents this operation",
"status": "409"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/link": {
"post": {
"tags": [
"Email link and publish"
],
"summary": "Link an email to a workflow",
"description": "Link a Design Studio email to a workflow: a transactional message, a one-time send, an automation, or an API-triggered broadcast. After you link an email, [publish it](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) to push the content live.\n\nYou can only link an email to one workflow or action at a time. If the workflow or action is already linked to a *different* Design Studio email, the request fails with a `409` unless you pass `\"force\": true`, which replaces (and unlinks) the other email.\n",
"operationId": "linkEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"target"
],
"properties": {
"target": {
"type": "object",
"description": "The workflow to link the content to.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "The kind of workflow to link. Provide the matching ID field for the type you choose. Use `campaign_action` for an automation or API-triggered broadcast.\n",
"enum": [
"transactional_message",
"newsletter",
"campaign_action"
]
},
"action_id": {
"type": "integer",
"description": "The ID of the action in the automation or API-triggered broadcast to link your content to. Required when `type` is `campaign_action`."
},
"newsletter_id": {
"type": "integer",
"description": "The ID of the one-time send to link your content to. Required when `type` is `newsletter`."
},
"transactional_message_id": {
"type": "integer",
"description": "The ID of the transactional message to link your content to. Required when `type` is `transactional_message`."
}
},
"example": {
"type": "campaign_action",
"action_id": 42
}
},
"force": {
"type": "boolean",
"description": "Replace an existing link if the workflow or action is already linked to *different* Design Studio content.\n",
"default": false
}
},
"example": {
"target": {
"type": "campaign_action",
"action_id": 42
},
"force": false
}
}
}
}
},
"responses": {
"200": {
"description": "Email linked",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the linked message."
},
"target": {
"type": "object",
"description": "The workflow linked to the message. The response returns `campaign_action` for an automation or an API-triggered broadcast.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "The type of workflow linked.\n",
"enum": [
"transactional_message",
"newsletter",
"campaign_action"
]
},
"action_id": {
"type": "integer",
"description": "The ID of the action in the automation or API-triggered broadcast that was linked."
},
"newsletter_id": {
"type": "integer",
"description": "The ID of the one-time send linked."
},
"transactional_message_id": {
"type": "integer",
"description": "The ID of the transactional message linked."
}
},
"example": {
"type": "campaign_action",
"action_id": 42
}
},
"template_id": {
"type": "integer",
"description": "The ID of the workflow template the content is now linked to."
}
},
"example": {
"node_id": "123e4567-e89b-12d3-a456-426614174000",
"target": {
"type": "campaign_action",
"action_id": 42
},
"template_id": 987654
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons include invalid or missing IDs, attempting to update a translation rather than the default template, or trying to link an email already tied to a workflow.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "email is already linked to another destination; unlink it first",
"status": "400"
}
]
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "The destination is already linked to a different Design Studio email. Pass `\"force\": true` to replace that link.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "destination is already linked to a different Design Studio email; pass `\"force\": true` to replace that link.",
"status": "409"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"target\": {\n \"type\": \"campaign_action\",\n \"action_id\": 42\n },\n \"force\": false\n}"
}
]
}
},
"/v1/design_studio/emails/{id}/publish": {
"post": {
"tags": [
"Email link and publish"
],
"summary": "Publish an email",
"description": "Publish a linked Design Studio email. This pushes its current content to the workflow it's linked to. You must link an email to a workflow before you can publish it.\n\nPublishing pushes updates to all language variants: the default language and all of the translations. For a single-language email, the publish runs inline and returns `\"status\": \"done\"` with the resulting template version mappings. For a multi-language email, the publish may take longer; if it doesn't finish within the request window, the response returns `\"status\": \"pending\"` along with a `publish_id` you can poll with [Get publish status](/integrations/api/design-studio/tag/email-email-link-and-publish/getPublishStatus/).\n",
"operationId": "publishEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Publish completed (`done`) or accepted and still running (`pending`).\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"mappings": {
"type": "array",
"description": "The template versions created by the publish. Present when `status` is `done`.",
"items": {
"type": "object",
"description": "A single node-to-template-version mapping produced by the publish process.",
"properties": {
"language": {
"type": "string",
"description": "The language code of the published node. Empty for the default-language email."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the published email node (default or translation)."
},
"template_id": {
"type": "integer",
"description": "The ID of the workflow template that received the content."
},
"version_id": {
"type": "string",
"description": "The identifier of the template version created by the publish."
}
}
}
},
"publish_id": {
"type": "string",
"description": "An opaque ID to poll for completion with [Get publish status](/integrations/api/design-studio/tag/email-email-link-and-publish/getPublishStatus/). Present when `status` is `pending`."
},
"status": {
"type": "string",
"description": "Returns `done` when the publish process finished within the request window. Returns `pending` when publish is still running for a multi-language email (poll with `publish_id`).\n",
"enum": [
"done",
"pending"
]
}
},
"example": {
"mappings": [
{
"language": "",
"node_id": "123e4567-e89b-12d3-a456-426614174000",
"template_id": 987654,
"version_id": "v_01H8XK"
}
],
"status": "done"
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons include invalid IDs, the email is not linked to workflow, or a translation uses an unsupported language code.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "The destination automation is backfilling and can't accept content right now. This clears on its own—wait a moment and publish again.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "campaign is backfilling, please try publishing again in a moment",
"status": "409"
}
]
}
}
}
},
"422": {
"description": "The content or its destination can't be published as-is. Possible reasons:\n - The content has Liquid errors. The `meta` object lists them per language.\n - The destination won't accept content because it's archived, stopping, or being deleted.\n - The destination is linked to different Design Studio content than the item you're publishing.\n - The workspace has no language attribute configured, which multi-language publishing needs.\n - The language group is over the limit of 50 variants.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "liquid validation failed",
"meta": {
"es": [
"unexpected end of liquid tag"
]
},
"status": "422"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/publish_status": {
"get": {
"tags": [
"Email link and publish"
],
"summary": "Get publish status",
"description": "Check the status of a multi-language publish that returned `\"status\": \"pending\"`. Pass the `publish_id` from the [Publish an email](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) response. When the publish is still running, the response returns `\"status\": \"pending\"`; when it finishes, it returns `\"status\": \"done\"` with the template version mappings.\n\nIf the publish fails, this endpoint returns an error rather than a status. You get the same error a single-language publish returns inline—a `422` for liquid errors, a `409` when the destination automation is backfilling, and so on.\n",
"operationId": "getPublishStatus",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "publish_id",
"in": "query",
"required": true,
"description": "The publish ID returned when a multi-language publish is pending.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Current publish status.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"mappings": {
"type": "array",
"description": "The template versions created by the publish. Present when `status` is `done`.",
"items": {
"type": "object",
"description": "A single node-to-template-version mapping produced by the publish process.",
"properties": {
"language": {
"type": "string",
"description": "The language code of the published node. Empty for the default-language email."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the published email node (default or translation)."
},
"template_id": {
"type": "integer",
"description": "The ID of the workflow template that received the content."
},
"version_id": {
"type": "string",
"description": "The identifier of the template version created by the publish."
}
}
}
},
"status": {
"type": "string",
"description": "`pending` while the publish is still running; `done` when it has finished.\n",
"enum": [
"pending",
"done"
]
}
},
"example": {
"mappings": [
{
"language": "",
"node_id": "123e4567-e89b-12d3-a456-426614174000",
"template_id": 987654,
"version_id": "v_01H8XK"
}
],
"status": "done"
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons:\n - `publish_id` is missing or invalid\n - The publish failed while rendering the content, usually because of invalid markup\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reason includes the automation, template, or email targeted by the publish job no longer exists.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "publish job not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "The destination automation is backfilling and can't accept content right now. This clears on its own—wait a moment and publish again.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "campaign is backfilling, please try publishing again in a moment",
"status": "409"
}
]
}
}
}
},
"422": {
"description": "The content or its destination can't be published as-is. Possible reasons:\n - The content has Liquid errors. The `meta` object lists them per language.\n - The destination won't accept content because it's archived, stopping, or being deleted.\n - The destination is linked to different Design Studio content than the item you're publishing.\n - The workspace has no language attribute configured, which multi-language publishing needs.\n - The language group is over the limit of 50 variants.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "liquid validation failed",
"meta": {
"es": [
"unexpected end of liquid tag"
]
},
"status": "422"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/unpublished_changes": {
"get": {
"tags": [
"Email link and publish"
],
"summary": "Check for unpublished changes",
"description": "Check whether a linked email, or any of its translations, has content changes that haven't been published yet. Use this to decide whether you need to publish before changes go live.\n\nReturns `false` for emails that aren't linked to a workflow or that have no pending changes.\n",
"operationId": "checkUnpublishedChanges",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The id of the email. If your email has multiple languages, you must provide the ID of the **default** language template. This links the workflow to all of the language variants for the template.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Returns whether the email has unpublished changes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"has_unpublished_changes": {
"type": "boolean",
"description": "Indicates whether the email or any of its translations has content changes that haven't been published."
}
},
"example": {
"has_unpublished_changes": true
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons:\n - Missing or invalid email (node) ID\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/render": {
"get": {
"tags": [
"Email testing"
],
"summary": "Render an email",
"description": "Returns email-ready HTML. Use this endpoint to inspect your compiled markup.\n\nLiquid tags are left intact—`{{customer.first_name}}` stays in the output as written. To evaluate liquid against real profile data instead, use [Preview an email](/integrations/api/design-studio/tag/email-testing/previewEmail/).\n\nThe render, preview, review, link, and publish endpoints share a rate limit of 5 requests per second per workspace.\n",
"operationId": "renderEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML variant. Omitted unless you added an AMP version when you [created the email](/integrations/api/design-studio/tag/emails/createEmail/)."
},
"html": {
"type": "string",
"description": "Full HTML with liquid tags left intact."
},
"language": {
"type": "string",
"description": "Language code if the node is a translation (for example, `\"es\"`). Omitted for default-language nodes."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the rendered email node."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `\"EMAIL\"`."
},
"text": {
"type": "string",
"description": "Plain text version of the email. Omitted unless you added a plain text version when you [created the email](/integrations/api/design-studio/tag/emails/createEmail/)."
}
},
"example": {
"html": "<!doctype html>\n<html lang=\"und\">...\n<p>{{customer.first_name}}, welcome!</p>\n...\n</html>",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL",
"text": "<html><head></head><body style=\"margin:0\"><div style=\"font-size:16px;line-height:1.5;font-family:Arial,Helvetica,sans-serif;white-space:pre-wrap;padding:10px;\">{{customer.first_name}}, welcome!</div></body></html>"
}
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reasons:\n - The `design_studio_api_manage` feature isn't enabled for this workspace\n - The email node doesn't exist\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/preview": {
"post": {
"tags": [
"Email testing"
],
"summary": "Preview an email",
"description": "Returns an email with liquid fully evaluated against data you provide. The response includes the final HTML as a recipient would see it, along with liquid errors.\n\nOmit the body or send `{}` to render your fallback values: a variable with a `default` filter renders its fallback, and each variable without one reports an error in the response's `errors` object.\n\nThe render, preview, review, link, and publish endpoints share a rate limit of 5 requests per second per workspace.\n",
"operationId": "previewEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": false,
"description": "All fields are optional.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"campaign": {
"type": "object",
"description": "Campaign metadata for `{{campaign.*}}`."
},
"customer": {
"type": "object",
"description": "Customer profile attributes for `{{customer.*}}` variables."
},
"event": {
"type": "object",
"description": "Event attributes for `{{event.*}}`."
},
"journey": {
"type": "object",
"description": "Journey metadata for `{{journey.*}}`."
},
"lax": {
"type": "boolean",
"default": false,
"description": "Set to `true` if you want undefined variables to resolve to an empty string instead of reporting an error; this can help you focus on more important errors when you don't provide sample data or fallback values. Liquid *syntax* errors (like broken tags and invalid filters) are always reported as errors.\n"
},
"message": {
"type": "object",
"description": "Message metadata for `{{message.*}}`."
},
"objects": {
"type": "object",
"description": "Related objects for `{{objects.*}}`."
},
"trigger": {
"type": "object",
"description": "Trigger data for `{{trigger.*}}`."
}
},
"example": {
"customer": {
"first_name": "Jane",
"email": "jane@example.com",
"plan": "enterprise"
},
"event": {
"name": "order_completed",
"total": 149.99
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML variant with liquid evaluated. Omitted if the email doesn't have an AMP version."
},
"errors": {
"type": "object",
"description": "Per-field Liquid error arrays. All 15 fields are always present; an empty array means no errors for that field.",
"properties": {
"bcc": {
"type": "array",
"items": {
"type": "string"
},
"description": "BCC field Liquid errors."
},
"body": {
"type": "array",
"items": {
"type": "string"
},
"description": "HTML body Liquid errors."
},
"body_amp": {
"type": "array",
"items": {
"type": "string"
},
"description": "AMP body Liquid errors."
},
"body_plain": {
"type": "array",
"items": {
"type": "string"
},
"description": "Plain-text body Liquid errors."
},
"cc": {
"type": "array",
"items": {
"type": "string"
},
"description": "CC field Liquid errors."
},
"event": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event data Liquid errors."
},
"from": {
"type": "array",
"items": {
"type": "string"
},
"description": "From address Liquid errors."
},
"layout": {
"type": "array",
"items": {
"type": "string"
},
"description": "Layout template errors."
},
"message": {
"type": "array",
"items": {
"type": "string"
},
"description": "Message-level errors."
},
"preheader_text": {
"type": "array",
"items": {
"type": "string"
},
"description": "Preheader Liquid errors."
},
"reply_to": {
"type": "array",
"items": {
"type": "string"
},
"description": "Reply-to address Liquid errors."
},
"snippets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Snippet rendering errors."
},
"subject": {
"type": "array",
"items": {
"type": "string"
},
"description": "Subject line Liquid errors."
},
"to": {
"type": "array",
"items": {
"type": "string"
},
"description": "Recipient field Liquid errors, for example `\"undefined variable: customer.email\"`.\n"
},
"trigger": {
"type": "array",
"items": {
"type": "string"
},
"description": "Trigger data Liquid errors."
}
}
},
"from": {
"type": "string",
"description": "Resolved from address, for example `\"Name <email>\"`. Omitted when the email doesn't include a from address."
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "array",
"items": {
"type": "string"
},
"description": "Errors in the header name."
},
"value": {
"type": "array",
"items": {
"type": "string"
},
"description": "Errors in the header value."
}
}
},
"description": "One entry per custom header that has Liquid errors. Omitted when there are none."
},
"html": {
"type": "string",
"description": "Final HTML with Liquid evaluated, the preheader injected, and dangerous tags removed."
},
"language": {
"type": "string",
"description": "Language code if the node is a translation. Omitted for default-language nodes."
},
"links": {
"type": "array",
"items": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Problems with this link, like a relative URL or liquid tags that were URL-encoded. Empty when the link is fine."
},
"text": {
"type": "string",
"description": "The link's visible text."
},
"tracked": {
"type": "boolean",
"description": "Whether Customer.io rewrites this link for click tracking when you send the email."
},
"url": {
"type": "string",
"description": "The link URL after liquid evaluation."
}
}
},
"description": "Every link in the evaluated HTML body, with any per-link problems."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the previewed email node."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `\"EMAIL\"`."
},
"plaintext_body": {
"type": "string",
"description": "The plain-text part a recipient would get—your plain text version with HTML tags stripped, or text generated from the final HTML if the email doesn't have one. Omitted when empty."
},
"preheader_text": {
"type": "string",
"description": "Evaluated preheader text. Omitted when the email doesn't include preheaders."
},
"subject": {
"type": "string",
"description": "Evaluated subject line."
},
"text": {
"type": "string",
"description": "Plain-text body with liquid evaluated. Omitted if the email doesn't have a plain text version."
}
},
"example": {
"errors": {
"bcc": [],
"body": [],
"body_amp": [],
"body_plain": [],
"cc": [],
"event": [],
"from": [],
"layout": [],
"message": [],
"preheader_text": [],
"reply_to": [],
"snippets": [],
"subject": [],
"to": [],
"trigger": []
},
"from": "\"No reply\" <noreply@example.com>",
"html": "<!DOCTYPE html>...<p>Purchase info</p>...",
"links": [
{
"errors": [],
"text": "View your order",
"tracked": true,
"url": "https://example.com/orders"
}
],
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL",
"plaintext_body": "Thanks for your recent purchase!",
"subject": "Order Confirmation",
"text": "<html><head></head><body style=\"margin:0\"><div style=\"font-size:16px;line-height:1.5;font-family:Arial,Helvetica,sans-serif;white-space:pre-wrap;padding:10px;\">Thanks for your recent purchase!</div></body></html>"
}
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reasons:\n - The `design_studio_api_manage` feature isn't enabled for this workspace\n - The email node doesn't exist\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"customer\": {\n \"first_name\": \"Jane\",\n \"email\": \"jane@example.com\",\n \"plan\": \"enterprise\"\n },\n \"event\": {\n \"name\": \"order_completed\",\n \"total\": 149.99\n }\n}"
}
]
}
},
"/v1/design_studio/emails/{id}/test_send": {
"post": {
"tags": [
"Email testing"
],
"summary": "Send a test email",
"description": "Sends a test email to a real inbox through your sending domain using the content saved to Design Studio. The test includes the tracking pixel and link parameters a real send would add, so you can see your email as it would appear in an actual email client. To get the rendered HTML back in the API response instead, use [Preview an email](/integrations/api/design-studio/tag/email-testing/previewEmail/).\n\n* **If you already linked the email to a workflow**, then keep in mind that what's *saved* to Design Studio may differ from what's *published* to the linked workflow. Make sure you publish your changes when you're ready to push them to your linked workflow.\n\n* **If your email has translations**, you have to send this request separately for each language variant. Pass the ID of the specific translation you want to test, which you can retrieve from [List email translations](/integrations/api/design-studio/tag/emails/listEmailTranslations/).\n\n* **If the email contains liquid variables**, you can provide sample data in the request body to check how the liquid renders. Without sample data, the send still succeeds, but each variable renders as an empty string and the response includes a warning. A variable with a fallback filter like `default` renders its fallback instead. A liquid syntax error, like a missing close tag, always fails the request.\n\nYour account has a set number of test emails you can send per day. This endpoint counts towards that quota. Learn more in [Plan features](/accounts/billing/plan-features/#general-features).\n",
"operationId": "testSendEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"to"
],
"properties": {
"to": {
"type": "array",
"items": {
"type": "string"
},
"description": "The email addresses you want to send the test to. You can send to up to 25 addresses per request; up to three addresses on a trial account; or a single address (the account owner's address or your workspace's delivery address) if your account isn't verified yet.\n"
},
"customer": {
"type": [
"object",
"null"
],
"description": "Sample profile attributes for `customer.*` liquid variables, as a flat object of values. Encode a nested value as a JSON string. You can pass this alongside `customer_id`: Customer.io uses the profile's attributes, and a value here overrides the profile's value for the same key.\n",
"additionalProperties": true
},
"customer_id": {
"type": [
"string",
"null"
],
"description": "The person whose profile attributes fill in `customer.*` liquid variables. Pass the person's `cio_id` or the `id` that identifies them in your workspace. If nobody matches, the request fails. When you omit this field and don't pass `customer` values, the email renders with empty `customer.*` values and the response includes a warning.\n"
},
"event": {
"type": [
"object",
"null"
],
"description": "Sample event data for `event.*` liquid variables. The `event` key references trigger data for event-triggered automations.\n",
"additionalProperties": true
},
"lax": {
"type": "boolean",
"default": false,
"description": "Set to `true` to render a liquid variable your sample data doesn't cover as an empty string rather than failing the request. Only applies when you pass `customer_id` or `customer`; without sample data, the email renders this way anyway and the response includes a warning.\n"
},
"prepend_test": {
"type": "boolean",
"default": false,
"description": "Set to `true` to add `[TEST]` to the start of the subject line."
},
"tracked": {
"type": "boolean",
"description": "Set to `true` to add a tracking pixel or `false` to leave it out. If you don't pass this field, Customer.io uses the tracking setting of the workflow message the email is linked to, and adds the pixel when the email isn't linked to a workflow message. Customer.io never adds the pixel for unverified accounts.\n"
},
"trigger": {
"type": [
"object",
"null"
],
"description": "Sample trigger data for `trigger.*` liquid variables. The `trigger` key references trigger data for these specific workflows: API-triggered broadcasts or transactional messages.\n",
"additionalProperties": true
}
}
},
"example": {
"to": [
"pigeon@customer.io",
"penguin@customer.io"
],
"customer": {
"first_name": "Ada",
"vip": "gold",
"cio_subscription_preferences": "{\"topics\":{\"topic_2\":true}}"
},
"customer_id": "5",
"prepend_test": true
}
}
}
},
"responses": {
"200": {
"description": "Test accepted for delivery",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"accepted": {
"type": "boolean",
"description": "Always `true` in a 200 response. Anything that stops the send returns a 4xx instead. Acceptance isn't proof of delivery."
},
"from": {
"type": "string",
"description": "The rendered `From` header the test was sent with.\n"
},
"language": {
"type": "string",
"description": "The language code if the message is a language variant. Omitted for the default-language node."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The email node that was tested."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "The response represents an email."
},
"subject": {
"type": "string",
"description": "The rendered subject line, including the `[TEST]` prefix if you set `prepend_test`."
},
"to": {
"type": "array",
"items": {
"type": "string"
},
"description": "The recipients the test was sent to."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "The ways this test differs from a real send. Customer.io delivered the email anyway, so read these before you trust what landed in the inbox. You might see that no profile data was available, that context a test send can't supply rendered as empty strings (like `campaign.*` or `message.*` on an email that isn't linked to a workflow), that Customer.io ignored a routing key like `recipient` or `from_address` in your `event` or `trigger` data, or that a recipient field in the template failed to render. That last one doesn't change who got the test: it goes only to the addresses in `to`. Omitted when there's nothing to report.\n"
}
},
"example": {
"accepted": true,
"from": "\"No reply\" <noreply@customer.io>",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL",
"subject": "[TEST] Welcome Ada",
"to": [
"pigeon@customer.io",
"penguin@customer.io"
]
}
}
}
}
},
"400": {
"description": "The ID isn't a valid email node, your account isn't verified yet and `to` holds an address it can't send to, or you've reached your [daily test-send limit](/accounts/billing/plan-features/#general-features).",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The email node doesn't exist.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "email not found",
"status": "404"
}
]
}
}
}
},
"422": {
"description": "A request field is invalid or the email's liquid didn't render. Each error's `source.pointer` names what failed, as `/data/attributes/<name>`. That name isn't always something you sent: `node_id` points at the email itself, and a liquid error can name `url_params`, `layout`, or `snippets`.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "to is required: a test send made with an API key has no user to default the recipient to",
"source": {
"pointer": "/data/attributes/to"
},
"status": "422"
}
]
}
}
}
},
"429": {
"description": "Rate limited. Every request to this endpoint draws from two buckets: a per-workspace bucket (burst of 20, refilling one every 9 seconds), the same limit the dashboard applies to its own test sends, and a per-IP bucket (burst of 30, refilling one every 10 seconds) that catches one IP address spread across many accounts. Hitting either limit returns this response. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited",
"status": "429"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"to\": [\n \"pigeon@customer.io\",\n \"penguin@customer.io\"\n ],\n \"customer\": {\n \"first_name\": \"Ada\",\n \"vip\": \"gold\",\n \"cio_subscription_preferences\": \"{\\\"topics\\\":{\\\"topic_2\\\":true}}\"\n },\n \"customer_id\": \"5\",\n \"prepend_test\": true\n}"
}
]
}
},
"/v1/design_studio/emails/{id}/review": {
"get": {
"tags": [
"Email testing"
],
"summary": "Review an email",
"description": "Checks an email's saved content for errors and suggests how to improve accessibility, styling, and more. This runs the same process as the [*Review* panel in Design Studio](/messaging/design-studio/emails/qa-in-design-studio/) and returns a readiness score, a status per check, and how to fix issues.\n\nThis endpoint reviews **a single translation** based on the `:id` you pass. Call this endpoint for each language variant to review each translation.\n\n**Checks**\n - `liquid` — Liquid syntax: broken tags, invalid filters, unclosed blocks. Does not report missing variables; use the [preview endpoint](/integrations/api/design-studio/tag/email-testing/previewEmail/) with sample data to validate variable resolution.\n - `failed-components` — Custom components that fail to compile. Always `skipped` on the API; it's a browser-runtime-only signal.\n - `source` — Raw markup the editor stores, before liquid rendering. Checks for reserved internal HTML attributes, multiple root elements, and design-token clashes.\n - `links` — Broken URLs, validated over HTTP (capped at 100 links per review).\n - `images` — Broken image URLs and missing alt text (capped at 100 images per review).\n - `accessibility` — WCAG accessibility issues.\n - `spam` — SpamAssassin score.\n - `unsubscribe` — Presence of an unsubscribe link.\n - `implied-links` — Bare URLs or email addresses that should be wrapped in `<a>` tags.\n - `html-clip` — Gmail's 102 KB clipping threshold.\n - `preheader` — Preheader text presence and quality.\n\nThe render, preview, review, link, and publish endpoints share a rate limit of 5 requests per second per workspace.\n",
"operationId": "reviewEmail",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email node. This can be the default-language node or a specific translation node.\n",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"checks": {
"type": "object",
"description": "Per-check status, keyed by check name. See the endpoint description for the full list of checks.",
"additionalProperties": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Present when `status` is `degraded` or `error`. Explains what was missing or what failed."
},
"status": {
"type": "string",
"enum": [
"complete",
"degraded",
"error",
"skipped"
],
"description": "`complete`: findings are authoritative. `degraded`: the check ran on reduced input (for example, some URL validations failed) — its findings aren't authoritative. `error`: the check couldn't run and contributed no findings. `skipped`: the check has no server-side signal for API callers.\n"
}
}
}
},
"findings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"check": {
"type": "string",
"description": "Which check produced this finding."
},
"details": {
"type": "string",
"description": "Explanation and suggested fix. Omitted when there's nothing more to add beyond the title."
},
"id": {
"type": "string",
"description": "Identifier for this finding, unique within the response."
},
"severity": {
"type": "string",
"enum": [
"error",
"warning",
"tip"
],
"description": "Fix all errors to make sure your recipients get your email and you follow compliance requirements. Review warnings and tips to improve the quality of your email."
},
"state": {
"type": "string",
"enum": [
"pass",
"fail"
],
"description": "Whether this finding represents an issue. Passing findings don't affect the score."
},
"summary": {
"type": "string",
"description": "Location context, for example \"In the email body\". Omitted when there's no additional context."
},
"title": {
"type": "string",
"description": "Short human-readable title."
}
}
}
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the reviewed email node."
},
"score": {
"type": "object",
"description": "Readiness score. Omitted when `status` is `render_failed`.",
"properties": {
"counts": {
"type": "object",
"description": "Finding counts by severity across all checks.",
"properties": {
"error": {
"type": "integer",
"description": "The number of failing `error` findings."
},
"tip": {
"type": "integer",
"description": "The number of failing `tip` findings."
},
"warning": {
"type": "integer",
"description": "The number of failing `warning` findings."
}
}
},
"score": {
"type": "integer",
"description": "0–100 readiness estimate. Starts at 100 and is reduced per failing finding. An error drops the score to 60 or below; fix all errors to make sure your recipients get your email and you follow compliance requirements. See **findings** to locate errors.\n"
}
}
},
"status": {
"type": "string",
"enum": [
"complete",
"partial",
"render_failed"
],
"description": "- `complete`: every check ran to completion. \n- `partial`: at least one check errored, ran on reduced input, or was skipped. `failed-components` is always skipped and doesn't [affect this status. If you get a `partial` status, send the request again after a few seconds to try to get a complete set of findings.\n- `render_failed`: the underlying render failed; no checks ran, `score` is omitted, and `findings` is empty. If it's a timeout, send the request again after a few seconds. If it's a content or compilation error, fix the email before sending the request again.\n"
}
},
"example": {
"checks": {
"liquid": {
"status": "complete"
},
"failed-components": {
"status": "skipped"
},
"source": {
"status": "complete"
},
"links": {
"status": "complete"
},
"images": {
"status": "complete"
},
"accessibility": {
"status": "complete"
},
"spam": {
"status": "complete"
},
"unsubscribe": {
"status": "complete"
},
"implied-links": {
"status": "complete"
},
"html-clip": {
"status": "complete"
},
"preheader": {
"status": "complete"
}
},
"findings": [
{
"check": "unsubscribe",
"details": "Add {% unsubscribe %} or use {% unsubscribe_url %} as the href.",
"id": "unsubscribe",
"severity": "warning",
"state": "fail",
"title": "No unsubscribe link"
},
{
"check": "preheader",
"details": "Add a short preheader to improve open rates.",
"id": "preheader",
"severity": "tip",
"state": "fail",
"title": "No preheader text"
}
],
"node_id": "887d804e-9199-4a65-ae26-315e825344bc",
"score": {
"counts": {
"error": 0,
"tip": 1,
"warning": 1
},
"score": 86
},
"status": "complete"
}
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reasons:\n - The `design_studio_api_manage` feature isn't enabled for this workspace\n - The email node doesn't exist\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/versions": {
"get": {
"tags": [
"Emails"
],
"summary": "List email versions",
"description": "Returns an email's saved versions, newest first. A version is a named checkpoint of the email's content and envelope. \n- Design Studio creates a version automatically every time you [publish](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) the email.\n- You can save a version manually with [Save an email version](/integrations/api/design-studio/tag/emails/saveVersion/).\n\nPass `start_date` to filter for versions created after a certain time. Or pass `start_date` and `end_date` together to filter for versions created in a certain time range.\n\nYou can retrieve your email's UUID through [List emails](/integrations/api/design-studio/tag/emails/listEmails/). If your email has language variants, *List emails* only returns the UUID for the default language. Use this default ID to retrieve variant IDs through [List email translations](/integrations/api/design-studio/tag/emails/listEmailTranslations/).\n",
"operationId": "listVersions",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "start_date",
"in": "query",
"description": "Return versions created at or after this time. Must be a unix timestamp.",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"example": 1773856017
},
{
"name": "end_date",
"in": "query",
"description": "Return versions created at or before this time. Must be a unix timestamp. Requires `start_date`.",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"example": 1773856017
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"versions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "The date-time the version was created."
},
"created_on_publish": {
"type": "boolean",
"description": "`false` if you [saved the email](/integrations/api/design-studio/tag/emails/saveVersion/). `true` if Design Studio created this version automatically when you [published the email](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/). You can't delete versions generated by Design Studio.\n"
},
"description": {
"type": "string",
"description": "Explanatory text you provided when creating a version. Omitted if no description."
},
"feedback": {
"type": "boolean",
"description": "`true` is you saved this version by creating a [round of feedback in Design Studio](/messaging/design-studio/collaboration/feedback/).\n"
},
"id": {
"type": "string",
"format": "uuid",
"description": "UUID of the version."
},
"name": {
"type": "string",
"description": "Name given to the version when it was saved."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the email node this version belongs to."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `\"EMAIL\"`."
}
},
"example": {
"created": 1773856017,
"created_on_publish": false,
"feedback": false,
"id": "8f14e45f-ceea-4c67-9814-b8f0e0e1a6f0",
"name": "Before holiday redesign",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons include `:id` is not a valid UUID, the node is not an `EMAIL` type, or you passed `end_date` without `start_date`.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reasons include the email node doesn't exist.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
}
},
"post": {
"tags": [
"Emails"
],
"summary": "Save an email version",
"description": "Saves a version of the email's current content, envelope, and any component dependencies it references.\n\nIf you need to revert to a previous version, use [Restore an email version](/integrations/api/design-studio/tag/emails/restoreVersion/).\n\nIf the email is identical to the most recent version, this returns that version with `\"created\": false` instead of saving a duplicate. If the code of a referenced custom component changes, you can save a new version of the email with the latest component changes; however, the code diff in Design Studio will show no change because the component code isn't compiled in that view.\n",
"operationId": "saveVersion",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name for the version, shown in the [version history list](/integrations/api/design-studio/tag/emails/listVersions/).",
"minLength": 1,
"maxLength": 100,
"example": "Before holiday redesign"
},
"description": {
"type": "string",
"description": "Note about the version."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Returns the new version saved, or the latest version if nothing changed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"created": {
"type": "boolean",
"description": "`false` when the email and its dependencies matched the most recent version exactly, so no new version was saved. `true` when this call created a new version.\n"
},
"version": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "The date-time the version was created."
},
"created_on_publish": {
"type": "boolean",
"description": "`false` if you [saved the email](/integrations/api/design-studio/tag/emails/saveVersion/). `true` if Design Studio created this version automatically when you [published the email](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/). You can't delete versions generated by Design Studio.\n"
},
"description": {
"type": "string",
"description": "Explanatory text you provided when creating a version. Omitted if no description."
},
"feedback": {
"type": "boolean",
"description": "`true` is you saved this version by creating a [round of feedback in Design Studio](/messaging/design-studio/collaboration/feedback/).\n"
},
"id": {
"type": "string",
"format": "uuid",
"description": "UUID of the version."
},
"name": {
"type": "string",
"description": "Name given to the version when it was saved."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the email node this version belongs to."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `\"EMAIL\"`."
}
},
"example": {
"created": 1773856017,
"created_on_publish": false,
"feedback": false,
"id": "8f14e45f-ceea-4c67-9814-b8f0e0e1a6f0",
"name": "Before holiday redesign",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL"
}
}
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons include `:id` is not a valid UUID or `name` is missing.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reasons include the email node doesn't exist.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"name\": \"Before holiday redesign\",\n \"description\": \"\"\n}"
}
]
}
},
"/v1/design_studio/emails/{id}/versions/{version_id}": {
"get": {
"tags": [
"Emails"
],
"summary": "Get an email version",
"description": "Returns a snapshot of the version's content including the code for any custom components referenced in the email (see `dependencies` for more).\n",
"operationId": "getVersion",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version_id",
"in": "path",
"required": true,
"description": "The UUID of the version.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"dependencies": {
"type": "array",
"items": {
"type": "object",
"description": "The code of the referenced custom component(s) in the node version.",
"properties": {
"component_name": {
"type": [
"string",
"null"
],
"description": "The component tag name when you saved this version."
},
"content": {
"type": "string",
"description": "HTML content as of the snapshot."
},
"name": {
"type": "string",
"description": "Display name of the component in Design Studio."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the component node."
},
"node_type": {
"type": "string",
"enum": [
"COMPONENT"
],
"description": "Always `COMPONENT`."
}
},
"example": {
"component_name": "footer",
"content": "<script>...</script><template>...</template>",
"name": "Footer",
"node_id": "1abcbb4e-402e-949e-f6732f333",
"node_type": "COMPONENT"
}
}
},
"node": {
"type": "object",
"description": "The content and settings stored in the version.",
"properties": {
"amp": {
"type": "string",
"description": "AMP HTML body as of the snapshot. Omitted if the email had none."
},
"content": {
"type": "string",
"description": "HTML content as of the snapshot. For the content of any referenced custom component, see `dependencies`."
},
"envelope": {
"type": "object",
"properties": {
"bcc": {
"type": "string",
"description": "BCC email address."
},
"fake_bcc": {
"type": "boolean",
"description": "Whether to use fake BCC. Defaults to true if not provided."
},
"from": {
"type": "string",
"description": "The sender address associated with the from_id."
},
"from_id": {
"type": [
"integer",
"null"
],
"description": "Sender identity ID.\n"
},
"headers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Custom headers. Each item: { \"name\": \"string\", \"value\": \"string\" }.\n"
},
"recipient": {
"type": "string",
"description": "Recipient expression. Defaults to {{customer.email}} if not set."
},
"reply_to": {
"type": "string",
"description": "The reply-to address associated with the reply_to_id."
},
"reply_to_id": {
"type": [
"integer",
"null"
],
"description": "Reply-to identity ID. This matches one of the ids in *Workspace Settings > Email*.\n"
}
}
},
"name": {
"type": "string",
"description": "Display name of the email in Design Studio. If the version is a language variant, the title ends in the language code like \"Onboarding email (fr)\"."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the node."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `EMAIL` for the node."
},
"preheader_text": {
"type": "string",
"description": "Preview text as of the snapshot. Omitted if the email had none."
},
"subject": {
"type": "string",
"description": "Email subject line."
},
"text": {
"type": "string",
"description": "Plain text body as of the snapshot. Omitted if the email had none."
},
"transformers": {
"type": "object",
"description": "Automate repetitive actions like removing white space and inlining CSS with [transformers](/journeys/design-studio/emails/code-editor/overview/#transformers).",
"properties": {
"accessibility": {
"type": "object",
"description": "Applies a set of accessibility improvements to the email HTML. When no `language` is set, this falls back to the `lang` attribute on the `<html>` tag, or `\"und\"` (undetermined). The `dir` attribute is automatically derived from the language using RTL detection.\n",
"properties": {
"add_dir_to_content": {
"type": "boolean",
"description": "Add `dir` attribute to direct children of `<body>`.\n",
"default": true
},
"add_dir_to_html": {
"type": "boolean",
"description": "Add `dir` attribute (`ltr`, `rtl`, or `auto`) to the `<html>` element if not already present.\n",
"default": true
},
"add_empty_alt_to_images": {
"type": "boolean",
"description": "Add `alt=\"\"` to `<img>` elements missing an `alt` attribute, preventing screen readers from reading the file name.\n",
"default": true
},
"add_lang_to_content": {
"type": "boolean",
"description": "Add `lang` attribute to direct children of `<body>`.\n",
"default": true
},
"add_lang_to_html": {
"type": "boolean",
"description": "Add `lang` attribute to the `<html>` element if not already present.\n",
"default": true
},
"add_role_to_tables": {
"type": "boolean",
"description": "Add `role=\"presentation\"` to all `<table>` elements without an existing `role`, so screen readers skip table semantics for layout tables.\n",
"default": true
},
"add_title_to_head": {
"type": "boolean",
"description": "Add a `<title>` tag to `<head>` using the email subject line (creates or replaces if empty).\n",
"default": true
},
"add_vml_alt_text": {
"type": "boolean",
"description": "Add `alt` attribute to VML elements (used by Outlook’s Word rendering engine), derived from the element’s text content.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable accessibility fixes.\n",
"default": false
},
"language": {
"type": "string",
"description": "Language code (for example, `\"en\"`, `\"fr\"`, or `\"ar\"`) used for `lang` and `dir` attributes.\n",
"default": ""
},
"remove_button_role_from_links": {
"type": "boolean",
"description": "Remove `role=\"button\"` from `<a>` tags to restore proper link semantics for screen readers.\n",
"default": true
},
"remove_zoom_meta_tag": {
"type": "boolean",
"description": "Remove viewport `<meta>` tags that restrict zoom (`user-scalable=0`, `user-scalable=no`, `maximum-scale=1`, or `maximum-scale=2`).\n",
"default": true
}
}
},
"css_inliner": {
"type": "object",
"description": "Moves CSS from `<style>` tags into inline `style` attributes on each element. Essential for email clients with limited `<style>` support (for example, older Gmail and some Outlook versions). Uses the `juice` library. Elements in `<style>` tags marked with `data-ignore-inlining` are skipped.\n",
"properties": {
"apply_html_attributes": {
"type": "object",
"description": "Controls adding redundant HTML attributes alongside inlined CSS to different HTML elements.\n",
"properties": {
"apply_height_attributes": {
"type": "boolean",
"description": "Add redundant HTML `height` attributes alongside inlined CSS `height` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS height.\n",
"default": true
},
"apply_table_element_attributes": {
"type": "boolean",
"description": "Add redundant HTML attributes on table elements (`<table>`, `<th>`, `<tr>`, `<td>`, `<caption>`, `<colgroup>`, `<col>`, `<thead>`, `<tbody>`, `<tfoot>`): `background-color` → `bgcolor`, `background-image` → `background`, `text-align` → `align`, `vertical-align` → `valign`.\n",
"default": true
},
"apply_width_attributes": {
"type": "boolean",
"description": "Add redundant HTML `width` attributes alongside inlined CSS `width` on `<table>`, `<td>`, `<th>`, and `<img>` elements. Only applies to `px` values (and `%` on table elements). Needed for email clients that ignore CSS width (for example, older Outlook).\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable adding redundant HTML attributes.\n",
"default": true
}
}
},
"apply_style_tags": {
"type": "boolean",
"description": "Inline styles from `<style>` tags.\n",
"default": true
},
"enabled": {
"type": "boolean",
"description": "Enable CSS inlining.\n",
"default": false
},
"inline_pseudo_elements": {
"type": "boolean",
"description": "Attempt to inline pseudo-element (`::before`, `::after`) styles.\n",
"default": false
},
"preserve_font_faces": {
"type": "boolean",
"description": "Keep `@font-face` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_important": {
"type": "boolean",
"description": "Preserve `!important` declarations in inlined styles.\n",
"default": false
},
"preserve_keyframes": {
"type": "boolean",
"description": "Keep `@keyframes` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_media_queries": {
"type": "boolean",
"description": "Keep `@media` rules in `<style>` (cannot be inlined).\n",
"default": true
},
"preserve_pseudos": {
"type": "boolean",
"description": "Keep pseudo-selector rules (for example, `:hover`) in `<style>` (cannot be inlined).\n",
"default": true
},
"remove_style_tags": {
"type": "boolean",
"description": "Remove `<style>` tags after inlining their rules.\n",
"default": true
}
}
},
"css_variables": {
"type": "object",
"description": "Resolves CSS custom properties (`var(--name)`) into their computed values. Required for email clients that do not support CSS custom properties (most email clients). Variables declared in one `<style>` tag are available in subsequent `<style>` tags.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable CSS variable resolution.\n",
"default": false
},
"preserve": {
"type": "boolean",
"description": "Keep original custom property declarations (`--name: value`) alongside the resolved values.\n",
"default": false
}
}
},
"encode_entities": {
"type": "object",
"description": "Encodes special characters (for example, `©`, `™`, and `—`) as their HTML entity equivalents. Improves rendering consistency across email clients with varying character encoding support. Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags and avoids double-encoding existing entities.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable HTML entity encoding.\n",
"default": false
}
}
},
"formatter": {
"type": "object",
"description": "Controls the output formatting of the final HTML. Only one mode (`prettify` or `minify`) can be active at a time. Set to `\"none\"` to skip formatting entirely.\n",
"properties": {
"minify": {
"type": "object",
"description": "Options used when `type` is `\"minify\"`. Reduces file size by stripping whitespace and comments.\n",
"properties": {
"line_length_limit": {
"type": "integer",
"description": "Maximum characters per line before inserting a line break.\n",
"default": 500
},
"remove_css_comments": {
"type": "boolean",
"description": "Remove CSS comments (`/* ... */`) from `<style>` blocks.\n",
"default": true
},
"remove_html_comments": {
"type": "string",
"description": "HTML comment removal level. `\"0\"` keeps all comments, `\"1\"` removes non-conditional comments (preserves MSO conditionals like `<!--[if mso]>`), and `\"2\"` removes all comments including conditional.\n",
"enum": [
"0",
"1",
"2"
],
"default": "0"
},
"remove_indentations": {
"type": "boolean",
"description": "Remove leading whitespace indentation.\n",
"default": true
},
"remove_line_breaks": {
"type": "boolean",
"description": "Remove all line breaks from the output.\n",
"default": false
}
}
},
"prettify": {
"type": "object",
"description": "Options used when `type` is `\"prettify\"`. Produces human-readable, indented HTML output.\n",
"properties": {
"indent_character": {
"type": "string",
"description": "Character used for indentation.\n",
"enum": [
"spaces",
"tabs"
],
"default": "spaces"
},
"indent_size": {
"type": "integer",
"description": "Number of indent characters per level.\n",
"default": 2
},
"wrap_attributes": {
"type": "boolean",
"description": "Wrap HTML attributes onto separate lines (`force-expand-multiline` mode).\n",
"default": false
}
}
},
"type": {
"type": "string",
"description": "Formatting mode to apply.\n",
"enum": [
"none",
"prettify",
"minify"
],
"default": "none"
}
}
},
"prevent_widows": {
"type": "object",
"description": "Replaces the last space in text blocks with a non-breaking space (` `) to prevent a single word from wrapping onto its own line (a “widow”). Only processes text nodes in the `<body>` and skips `<script>`, `<style>`, `<noscript>`, `<svg>`, and `<head>` elements. Preserves Liquid template tags (`{{ }} ` and `{% %}`).\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable widow word prevention.\n",
"default": false
}
}
},
"remove_unused_css": {
"type": "object",
"description": "Scans the HTML and removes any CSS selectors from `<style>` tags that are not referenced in the document. Reduces file size and helps avoid Gmail’s 102 KB clipping limit. HTML and CSS comments are always preserved by this step (comment removal is handled separately by the formatter object).\n",
"properties": {
"backend_markers": {
"type": "array",
"description": "Template syntax delimiters (e.g., Liquid, Handlebars) that the CSS parser should skip over to avoid treating template expressions as invalid CSS.\n",
"default": [
{
"heads": "",
"tails": ""
},
{
"heads": "{%",
"tails": "%}"
}
],
"items": {
"type": "object",
"properties": {
"heads": {
"type": "string",
"description": "Opening delimiter.\n"
},
"tails": {
"type": "string",
"description": "Closing delimiter.\n"
}
}
}
},
"enabled": {
"type": "boolean",
"description": "Enable unused CSS removal.\n",
"default": false
},
"uglify": {
"type": "boolean",
"description": "Shorten (uglify) CSS class names to reduce file size.\n",
"default": false
},
"whitelist": {
"type": "array",
"description": "CSS selectors to always keep, even if they are not found in the HTML.\n - .ReadMsgBody\n - .ExternalClass\n - .aBn\n - .a6S\n - .im\n - .yshortcuts\n - \"#outlook\"\n - .MsoHyperlink\n - .MsoHyperlinkFollowed\n",
"items": {
"type": "string",
"description": "A CSS selector to always keep.\n"
}
}
}
},
"url_parameters": {
"type": "object",
"description": "Appends query string parameters to all absolute URLs in `<a>` and VML elements. Useful for adding UTM tracking or other analytics parameters. Skips `mailto:`, `tel:`, and `sms:` links. Elements marked with `data-ignore-params` are excluded.\n",
"properties": {
"enabled": {
"type": "boolean",
"description": "Enable URL parameter injection.\n",
"default": false
},
"parameters": {
"type": "array",
"description": "List of parameters to append to URLs.\n",
"default": [],
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Parameter name.\n"
},
"url_encode": {
"type": "boolean",
"description": "URL-encode the value before appending it to the URL.\n"
},
"value": {
"type": "string",
"description": "Parameter value. May contain template variables.\n"
}
}
}
}
}
}
}
}
},
"example": {
"content": "<x-base>...</x-base>",
"envelope": {
"bcc": "",
"fake_bcc": true,
"from": "Customer.io <noreply@example.com>",
"from_id": 1,
"headers": [],
"recipient": "{{customer.email}}",
"reply_to": "",
"reply_to_id": null
},
"name": "Onboarding phase 1",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL",
"preheader_text": "Get started in minutes",
"subject": "Welcome to Design Studio!",
"transformers": {
"prevent_widows": {
"enabled": false
}
}
}
},
"version": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "The date-time the version was created."
},
"created_on_publish": {
"type": "boolean",
"description": "`false` if you [saved the email](/integrations/api/design-studio/tag/emails/saveVersion/). `true` if Design Studio created this version automatically when you [published the email](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/). You can't delete versions generated by Design Studio.\n"
},
"description": {
"type": "string",
"description": "Explanatory text you provided when creating a version. Omitted if no description."
},
"feedback": {
"type": "boolean",
"description": "`true` is you saved this version by creating a [round of feedback in Design Studio](/messaging/design-studio/collaboration/feedback/).\n"
},
"id": {
"type": "string",
"format": "uuid",
"description": "UUID of the version."
},
"name": {
"type": "string",
"description": "Name given to the version when it was saved."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the email node this version belongs to."
},
"node_type": {
"type": "string",
"enum": [
"EMAIL"
],
"description": "Always `\"EMAIL\"`."
}
},
"example": {
"created": 1773856017,
"created_on_publish": false,
"feedback": false,
"id": "8f14e45f-ceea-4c67-9814-b8f0e0e1a6f0",
"name": "Before holiday redesign",
"node_id": "1a0cbb4e-09d3-402e-949e-f6732f021650",
"node_type": "EMAIL"
}
}
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons include `:id` is not a valid UUID, the node is not an email, or `version_id` is not a valid UUID.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reasons include the email node or version doesn't exist.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"Emails"
],
"summary": "Delete an email version",
"description": "Deletes a version. You can't delete a version that Design Studio created automatically during a publish.\n",
"operationId": "deleteVersion",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version_id",
"in": "path",
"required": true,
"description": "The UUID of the version.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Version deleted"
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reasons include the email node or version doesn't exist or the version belongs to a different node.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"409": {
"description": "The version was created automatically during a publish and can't be deleted.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "cannot delete a version created on publish",
"status": 409
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/versions/{version_id}/restore": {
"post": {
"tags": [
"Emails"
],
"summary": "Restore an email version",
"description": "Returns the email to a saved version. This restores only the email itself; if the code for a referenced custom component changed since this version was saved, the latest component code renders in Design Studio, not the original.\n\nThis only edits the draft in Design Studio. If you already linked the email to a workflow, you need to [publish it](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) to push the restored content live.\n",
"operationId": "restoreVersion",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "version_id",
"in": "path",
"required": true,
"description": "The UUID of the version.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Version restored",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the restored email node."
},
"restored_node_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "The nodes whose content was rolled back. Always just the email node itself—component dependencies aren't restored."
},
"version_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the version that was restored."
}
},
"example": {
"node_id": "123e4567-e89b-12d3-a456-426614174000",
"restored_node_ids": [
"123e4567-e89b-12d3-a456-426614174000"
],
"version_id": "fc70fa5f-5fed-49c1-be48-6508aa9875c1"
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons include `:id` or `version_id` is not a valid UUID.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Possible reasons include the email node or version doesn't exist or the version belongs to a different node.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
}
}
},
"/v1/design_studio/sms": {
"get": {
"tags": [
"SMS"
],
"summary": "List SMS",
"operationId": "listSms",
"description": "Returns a paginated list of your SMS messages and a separate array of the folders they belong to. Each item in the list is a summary; to see an SMS's content, recipient, and sender, [get the SMS](/integrations/api/design-studio/tag/sms/getSms/).\n",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The page number of results you want to display. Use with `limit`.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "limit",
"in": "query",
"description": "The maximum number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 1000
}
},
{
"name": "parent_folder_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Filter by parent folder. Must reference an existing folder. If not set, the response filters by the root level directory.\n\nTo list only items in the root folder, leave `parent_folder_id` unset and only set `direct_descendants_only` to `true`.\n"
},
{
"name": "direct_descendants_only",
"in": "query",
"description": "When `true`, the response includes only the immediate children of the parent folder. When `false`, it includes the parent folder's entire subtree.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "sort_by",
"in": "query",
"schema": {
"type": "string",
"enum": [
"created",
"updated",
"name"
],
"default": "created"
}
},
{
"name": "sort_order",
"in": "query",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "created_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created before this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "created_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created after this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "updated_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated before this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "updated_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated after this time. Must be a unix timestamp.",
"example": 1773856017
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"folders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the folder was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of folder"
},
"name": {
"type": "string",
"description": "The name of the folder."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory."
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the folder."
}
},
"example": {
"created": 1714732800,
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Product Announcements",
"parent_folder_id": null,
"updated": 1714732800
}
}
},
"meta": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"description": "The filters applied in your request.",
"example": {
"parent_folder_id": "123e4567-e89b-12d3-a456-426614174000",
"direct_descendants_only": true,
"sort_by": "created",
"sort_order": "desc",
"created_before": 1714732800,
"created_after": null,
"updated_before": null,
"updated_after": null
}
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "The number of results per page."
},
"page": {
"type": "integer",
"description": "The page number of results you're on."
},
"total": {
"type": "integer",
"description": "The total number of folders."
}
}
}
}
},
"sms": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "int64",
"description": "When you created the SMS, as a Unix timestamp in seconds.",
"example": 1790000000
},
"id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the SMS."
},
"is_linked": {
"type": "boolean",
"description": "Whether you've linked the SMS to a workflow, like a transactional message, a one-time send, or an automation action."
},
"name": {
"type": "string",
"description": "The friendly name your team sees for the SMS in Design Studio.",
"example": "Order shipped"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the folder that contains the SMS, or `null` if the SMS is at the root level."
},
"updated": {
"type": "integer",
"format": "int64",
"description": "When the SMS last changed, as a Unix timestamp in seconds.",
"example": 1790000000
}
}
}
}
}
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"post": {
"tags": [
"SMS"
],
"summary": "Create an SMS",
"operationId": "createSms",
"description": "This endpoint creates an SMS message in Design Studio. After you create an SMS, [link it](/integrations/api/design-studio/tag/sms-link-and-publish/linkSms/) to a workflow. If you make updates after linking the message, make sure you [publish changes](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) to send the latest content to your audience.\n\nNot all accounts are set up to create SMS through Design Studio. [Learn more about your options](/integrations/api/design-studio/tag/sms/).\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"content"
],
"properties": {
"content": {
"type": "string",
"minLength": 1,
"description": "The message, written as SMS markup. Put your message text in an `<x-sms-body>` element inside an `<x-sms>` element; the text can include liquid. To send an image as an MMS, add an `<x-sms-media>` element inside `<x-sms>` with `type=\"image\"` and an `href` set to the image URL or to liquid that resolves to one. Each message can have one image. See [SMS building blocks](/messaging/channels/sms/send-messages/#sms-building-blocks) for line breaks, special characters, and the HTML you can't use.",
"example": "<x-sms><x-sms-body>Hi {{customer.first_name}}, your order has shipped.</x-sms-body><x-sms-media type=\"image\" href=\"https://example.com/order.png\"/></x-sms>"
},
"name": {
"type": "string",
"description": "A friendly name for the SMS. Your team sees this name in Design Studio, so pick one that helps them find the message.",
"minLength": 1,
"maxLength": 191,
"pattern": "^[^/\\x00-\\x1F\\x7F]+$",
"example": "Order shipped"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the folder to create the SMS in. Omit or pass `null` to create the SMS at the root level. You can [list folders](/integrations/api/design-studio/tag/folders/listFolders/) to find the UUID of the folder you want."
},
"recipient": {
"type": "string",
"description": "Liquid that resolves to the phone number of the person you're messaging, like `{{customer.phone}}`. Customer.io evaluates it against that person's profile when it sends the message. If you leave it empty, Customer.io uses `{{customer.phone}}`. Don't set a static phone number here; if you do, every send of this message goes to that one number instead of to each person.",
"example": "{{customer.phone}}"
},
"sender_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The ID of the sender identity to send the SMS from. You can [list sender identities](/integrations/api/app/tag/sender-identities/listSenders/) to find the ID you want. You can create an SMS without a sender, but you need to set one before you can publish it.",
"example": 2
}
}
}
}
}
},
"responses": {
"200": {
"description": "SMS created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sms": {
"type": "object",
"required": [
"id",
"name",
"is_linked",
"parent_folder_id",
"content",
"recipient",
"sender_id",
"created",
"updated"
],
"properties": {
"content": {
"type": "string",
"description": "The message, written as SMS markup.",
"example": "<x-sms><x-sms-body>Hi {{customer.first_name}}, your order has shipped.</x-sms-body></x-sms>"
},
"created": {
"type": "integer",
"format": "int64",
"description": "When you created the SMS, as a Unix timestamp in seconds.",
"example": 1790000000
},
"id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the SMS."
},
"is_linked": {
"type": "boolean",
"description": "Whether you've linked the SMS to a workflow, like a transactional message, a one-time send, or an automation action."
},
"name": {
"type": "string",
"description": "The friendly name your team sees for the SMS in Design Studio.",
"example": "Order shipped"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the folder that contains the SMS, or `null` if the SMS is at the root level."
},
"recipient": {
"type": "string",
"description": "Liquid that resolves to the phone number of the person you're messaging. An empty string means Customer.io sends to `{{customer.phone}}`.",
"example": "{{customer.phone}}"
},
"sender_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The ID of the sender identity the SMS sends from, or `null` if you haven't set a sender.",
"example": 2
},
"updated": {
"type": "integer",
"format": "int64",
"description": "When the SMS last changed, as a Unix timestamp in seconds.",
"example": 1790000000
}
}
}
}
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"422": {
"description": "The `content` isn't valid SMS markup, or the liquid in `content` or `recipient` isn't valid. Markup fails when it doesn't parse, when `<x-sms-body>` is empty, or when text sits inside an unsupported tag like `<b>`. Each error's `source.pointer` names the field that failed, as `/data/attributes/content` or `/data/attributes/recipient`. Customer.io checks liquid syntax only, so a variable your profiles don't have yet renders as empty rather than failing.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"content\": \"<x-sms><x-sms-body>Hi {{customer.first_name}}, your order has shipped.</x-sms-body><x-sms-media type=\\\"image\\\" href=\\\"https://example.com/order.png\\\"/></x-sms>\",\n \"name\": \"Order shipped\",\n \"parent_folder_id\": null,\n \"recipient\": \"{{customer.phone}}\",\n \"sender_id\": 2\n}"
}
]
}
},
"/v1/design_studio/sms/{id}": {
"get": {
"tags": [
"SMS"
],
"summary": "Get an SMS",
"operationId": "getSms",
"description": "Returns a single SMS, including its content, recipient, and sender.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the SMS.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sms": {
"type": "object",
"required": [
"id",
"name",
"is_linked",
"parent_folder_id",
"content",
"recipient",
"sender_id",
"created",
"updated"
],
"properties": {
"content": {
"type": "string",
"description": "The message, written as SMS markup.",
"example": "<x-sms><x-sms-body>Hi {{customer.first_name}}, your order has shipped.</x-sms-body></x-sms>"
},
"created": {
"type": "integer",
"format": "int64",
"description": "When you created the SMS, as a Unix timestamp in seconds.",
"example": 1790000000
},
"id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the SMS."
},
"is_linked": {
"type": "boolean",
"description": "Whether you've linked the SMS to a workflow, like a transactional message, a one-time send, or an automation action."
},
"name": {
"type": "string",
"description": "The friendly name your team sees for the SMS in Design Studio.",
"example": "Order shipped"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the folder that contains the SMS, or `null` if the SMS is at the root level."
},
"recipient": {
"type": "string",
"description": "Liquid that resolves to the phone number of the person you're messaging. An empty string means Customer.io sends to `{{customer.phone}}`.",
"example": "{{customer.phone}}"
},
"sender_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The ID of the sender identity the SMS sends from, or `null` if you haven't set a sender.",
"example": 2
},
"updated": {
"type": "integer",
"format": "int64",
"description": "When the SMS last changed, as a Unix timestamp in seconds.",
"example": 1790000000
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"put": {
"tags": [
"SMS"
],
"summary": "Update an SMS",
"operationId": "updateSms",
"description": "Update an SMS's name, folder, content, recipient, or sender. You only need to send the fields you want to change; Customer.io keeps the current value of any field you leave out.\n\nIf the SMS is linked to a workflow, you need to [publish your changes](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) so your audience receives the latest content.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the SMS.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"description": "Send at least one of these properties.",
"content": {
"application/json": {
"schema": {
"type": "object",
"minProperties": 1,
"properties": {
"content": {
"type": "string",
"description": "The new message, written as SMS markup. See the `content` field on [Create an SMS](/integrations/api/design-studio/tag/sms/createSms/) for the format. If you pass an empty string, Customer.io clears the content, and you'll need to add content again before you can publish the SMS.",
"example": "<x-sms><x-sms-body>Hi {{customer.first_name}}, your order is out for delivery.</x-sms-body></x-sms>"
},
"name": {
"type": "string",
"description": "A new friendly name for the SMS.",
"minLength": 1,
"maxLength": 191,
"pattern": "^[^/\\x00-\\x1F\\x7F]+$",
"example": "Order shipped"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the folder you want to move the SMS into. Pass `null` to move the SMS to the root level."
},
"recipient": {
"type": "string",
"description": "New liquid that resolves to the phone number of the person you're messaging, like `{{customer.phone}}`. If you pass an empty string, Customer.io clears the recipient and sends to `{{customer.phone}}`.",
"example": "{{customer.phone}}"
},
"sender_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The ID of the sender identity to send the SMS from. Pass `null` to clear the sender; you'll need to set one again before you can publish the SMS.",
"example": 2
}
}
}
}
}
},
"responses": {
"204": {
"description": "SMS updated, no content returned"
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"422": {
"description": "The `content` has invalid SMS markup, or the liquid in `content` or `recipient` is invalid. Customer.io only checks the fields you send. Each error's `source.pointer` names the field that failed, as `/data/attributes/content` or `/data/attributes/recipient`.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"content\": \"<x-sms><x-sms-body>Hi {{customer.first_name}}, your order is out for delivery.</x-sms-body></x-sms>\",\n \"name\": \"Order shipped\",\n \"parent_folder_id\": null,\n \"recipient\": \"{{customer.phone}}\",\n \"sender_id\": 2\n}"
}
]
},
"delete": {
"tags": [
"SMS"
],
"summary": "Delete an SMS",
"operationId": "deleteSms",
"description": "Delete an SMS. You can't delete an SMS that's linked to a workflow, like a transactional message, a one-time send, or an automation action.\n",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the SMS.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "SMS deleted"
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "The SMS is linked to a workflow, so Customer.io doesn't delete it.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "cannot delete sms because it is linked",
"status": "409"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/sms/{id}/link": {
"post": {
"tags": [
"SMS link and publish"
],
"summary": "Link an SMS to a workflow",
"description": "Link an existing SMS to a workflow—a transactional message, a one-time send, an automation action, or an API-triggered broadcast—to send it to your audience.\n\nIf your workflow is already live, people start receiving this SMS as soon as you link it. If you make changes to the message after linking it, you need to [publish the SMS](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) to send the latest content to your audience.\n\nYou can only link an SMS to one workflow at a time. If you try to link an SMS to a workflow or action that's already linked to a *different* message, the request fails with a `409` unless you pass `\"force\": true`. The `force` parameter replaces (and unlinks) the other message.\n",
"operationId": "linkSms",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the SMS.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"target"
],
"properties": {
"target": {
"type": "object",
"description": "The workflow to link the content to.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "The kind of workflow to link. Provide the matching ID field for the type you choose. Use `campaign_action` for an automation or API-triggered broadcast.\n",
"enum": [
"transactional_message",
"newsletter",
"campaign_action"
]
},
"action_id": {
"type": "integer",
"description": "The ID of the action in the automation or API-triggered broadcast to link your content to. Required when `type` is `campaign_action`."
},
"newsletter_id": {
"type": "integer",
"description": "The ID of the one-time send to link your content to. Required when `type` is `newsletter`."
},
"transactional_message_id": {
"type": "integer",
"description": "The ID of the transactional message to link your content to. Required when `type` is `transactional_message`."
}
},
"example": {
"type": "campaign_action",
"action_id": 42
}
},
"force": {
"type": "boolean",
"description": "Replace an existing link if the workflow or action is already linked to *different* Design Studio content.\n",
"default": false
}
},
"example": {
"target": {
"type": "campaign_action",
"action_id": 42
},
"force": false
}
}
}
}
},
"responses": {
"200": {
"description": "SMS linked",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"format": "uuid",
"description": "The UUID of the linked message."
},
"target": {
"type": "object",
"description": "The workflow linked to the message. The response returns `campaign_action` for an automation or an API-triggered broadcast.",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"description": "The type of workflow linked.\n",
"enum": [
"transactional_message",
"newsletter",
"campaign_action"
]
},
"action_id": {
"type": "integer",
"description": "The ID of the action in the automation or API-triggered broadcast that was linked."
},
"newsletter_id": {
"type": "integer",
"description": "The ID of the one-time send linked."
},
"transactional_message_id": {
"type": "integer",
"description": "The ID of the transactional message linked."
}
},
"example": {
"type": "campaign_action",
"action_id": 42
}
},
"template_id": {
"type": "integer",
"description": "The ID of the workflow template the content is now linked to."
}
},
"example": {
"node_id": "123e4567-e89b-12d3-a456-426614174000",
"target": {
"type": "campaign_action",
"action_id": 42
},
"template_id": 987654
}
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "The destination is already linked to a different message. Pass `\"force\": true` to replace that link.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "destination is already linked to a different Design Studio sms; pass \"force\": true to replace that link",
"status": "409"
}
]
}
}
}
},
"422": {
"description": "The liquid in the SMS's content or recipient isn't valid, so Customer.io doesn't link it. Each error's `source.pointer` names the field that failed, as `/data/attributes/content` or `/data/attributes/recipient`. Fix the SMS, then link it again.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"target\": {\n \"type\": \"campaign_action\",\n \"action_id\": 42\n },\n \"force\": false\n}"
}
]
}
},
"/v1/design_studio/sms/{id}/publish": {
"post": {
"tags": [
"SMS link and publish"
],
"summary": "Publish an SMS",
"description": "If you made changes to a [linked SMS message](/integrations/api/design-studio/tag/sms-link-and-publish/linkSms/), you need to publish the SMS when you're ready so your workflows send the latest content. \n",
"operationId": "publishSms",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the SMS.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "SMS published",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "The result of the publish process.",
"properties": {
"template_ids": {
"type": "array",
"description": "The IDs of the workflow templates that received the content.",
"items": {
"type": "integer"
}
},
"version_id": {
"type": "string",
"description": "The identifier of the template version created by the publish process."
}
},
"example": {
"template_ids": [
987654
],
"version_id": "v_01H8XK"
}
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"422": {
"description": "The liquid in the SMS's content or recipient isn't valid, so Customer.io doesn't publish it. Each error's `source.pointer` names the field that failed, as `/data/attributes/content` or `/data/attributes/recipient`. Fix the SMS, then publish it again.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
}
}
}
},
"/v1/design_studio/components": {
"get": {
"tags": [
"Components"
],
"summary": "List components",
"description": "Returns a paginated list of components and any folders in the result set.",
"operationId": "listComponents",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "tag",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by component tag name. This is the name of the tag inserted into your emails."
},
{
"name": "page",
"in": "query",
"description": "The page number of results you want to display. Use with `limit`.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "limit",
"in": "query",
"description": "The maximum number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 1000
}
},
{
"name": "parent_folder_id",
"in": "query",
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Filter by parent folder. Must reference an existing folder. If not set, the response filters by the root level directory.\n\nTo list only items in the root folder, leave `parent_folder_id` unset and only set `direct_descendants_only` to `true`.\n"
},
{
"name": "direct_descendants_only",
"in": "query",
"description": "When `true`, the response includes only the immediate children of the parent folder. When `false`, it includes the parent folder's entire subtree.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "sort_by",
"in": "query",
"schema": {
"type": "string",
"enum": [
"created",
"updated",
"name"
],
"default": "created"
}
},
{
"name": "sort_order",
"in": "query",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "created_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created before this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "created_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records created after this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "updated_before",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated before this time. Must be a unix timestamp.",
"example": 1773856017
},
{
"name": "updated_after",
"in": "query",
"schema": {
"type": "integer",
"format": "Unix timestamp"
},
"description": "Return records updated after this time. Must be a unix timestamp.",
"example": 1773856017
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the component was created.",
"example": 1773856017
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of the component",
"example": "e89b-12d3"
},
"name": {
"type": "string",
"description": "Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.",
"example": "Custom footer"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "ID of the parent folder, or `null` if the component is in your root directory.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"tag": {
"type": "string",
"description": "The component tag name, used to reference your component in an email.",
"example": "custom-footer"
},
"updated": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the component.",
"example": 1773856019
}
}
}
},
"folders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of when the folder was created."
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of folder"
},
"name": {
"type": "string",
"description": "The name of the folder."
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory."
},
"updated": {
"type": "integer",
"format": "Unix timestamp",
"description": "Timestamp of last update to the folder."
}
},
"example": {
"created": 1714732800,
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Product Announcements",
"parent_folder_id": null,
"updated": 1714732800
}
}
},
"meta": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"description": "The filters applied in your request.",
"example": {
"parent_folder_id": "123e4567-e89b-12d3-a456-426614174000",
"direct_descendants_only": true,
"sort_by": "created",
"sort_order": "desc",
"created_before": 1714732800,
"created_after": null,
"updated_before": null,
"updated_after": null
}
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "The number of results per page."
},
"page": {
"type": "integer",
"description": "The page number of results you're on."
},
"total": {
"type": "integer",
"description": "The total number of folders."
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"post": {
"tags": [
"Components"
],
"summary": "Create a component",
"description": "Creates a custom component.",
"operationId": "createComponent",
"security": [
{
"Bearer-Auth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"tag",
"content"
],
"properties": {
"content": {
"type": "string",
"description": "HTML content"
},
"name": {
"type": "string",
"description": "Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.",
"minLength": 1,
"maxLength": 255,
"example": "Custom footer"
},
"tag": {
"type": "string",
"description": "The component tag name, used to reference your component in an email. [Learn what characters you can use](/journeys/design-studio/reusable/components/code-custom-component/#component-tag-name-validation).",
"example": "custom-footer"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "UUID of the parent folder. Omit or pass `null` to create in the root directory."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Component created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"component": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "HTML content"
},
"created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the component was created.",
"example": 1773856017
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of the component",
"example": "e89b-12d3"
},
"name": {
"type": "string",
"description": "Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.",
"example": "Custom footer"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "ID of the parent folder, or `null` if the component is in your root directory.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"tag": {
"type": "string",
"description": "The component tag name, used to reference your component in an email.",
"example": "custom-footer"
},
"updated": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the component."
}
}
}
}
}
}
}
},
"400": {
"description": "Bad request. Possible reasons:\n - Missing or invalid name\n - Missing or invalid tag\n - parent_folder_id is an empty string\n - Unknown JSON field in request body\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "Conflict - linked resource or other constraint violation",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "a constraint violation prevents this operation",
"status": "409"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"content\": \"\",\n \"name\": \"Custom footer\",\n \"tag\": \"custom-footer\",\n \"parent_folder_id\": null\n}"
}
]
}
},
"/v1/design_studio/components/{id}": {
"get": {
"tags": [
"Components"
],
"summary": "Get a component",
"description": "Returns a single component with its full content.",
"operationId": "getComponent",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the component.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"component": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "HTML content"
},
"created": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the component was created.",
"example": 1773856017
},
"id": {
"type": "string",
"format": "uuid",
"description": "ID of the component",
"example": "e89b-12d3"
},
"name": {
"type": "string",
"description": "Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.",
"example": "Custom footer"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "ID of the parent folder, or `null` if the component is in your root directory.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"tag": {
"type": "string",
"description": "The component tag name, used to reference your component in an email.",
"example": "custom-footer"
},
"updated": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the component."
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
},
"put": {
"tags": [
"Components"
],
"summary": "Update a component",
"description": "Update part of a component: its name, tag, folder, or content.\n",
"operationId": "updateComponent",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the component.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"description": "You must provide a body with at least one of the following properties. Omitting a field leaves it unchanged.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "HTML content"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.",
"example": "custom-footer"
},
"parent_folder_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "The UUID of the parent folder.\n\nOmit if you want no change to where the folder or file is located. Include `null` to move it to your root directory. Or add the UUID of another folder to move it there.\n"
},
"tag": {
"type": "string",
"description": "The component tag name, used to reference your component in an email. Learn what [characters](/journeys/design-studio/reusable/components/code-custom-component/#component-tag-name-validation) you can use."
}
}
}
}
}
},
"responses": {
"204": {
"description": "Component updated"
},
"400": {
"description": "Bad request. Possible reasons:\n - No fields provided\n - Invalid name\n - Invalid tag\n - parent_folder_id is an empty string\n - Unknown JSON field in request body\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "Conflict - linked resource or other constraint violation",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "a constraint violation prevents this operation",
"status": "409"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"content\": \"\",\n \"name\": \"custom-footer\",\n \"parent_folder_id\": null,\n \"tag\": \"\"\n}"
}
]
},
"delete": {
"tags": [
"Components"
],
"summary": "Delete a component",
"description": "Delete a component. Note, this deletes any component. If you delete a component in use, the emails that reference it could fail to send.",
"operationId": "deleteComponent",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the component.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Component deleted"
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/inbox_previews/clients": {
"get": {
"tags": [
"Email testing"
],
"summary": "List inbox preview options",
"description": "Returns the catalog of email clients and devices available for [inbox previews](/messaging/design-studio/emails/qa-in-design-studio/#inbox-preview). \n\nUse the `id` values returned by this endpoint as `client_ids` when you [send for an inbox preview](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/).\n",
"operationId": "listInboxPreviewClients",
"security": [
{
"Bearer-Auth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"clients": {
"type": "array",
"items": {
"type": "object",
"description": "An email client available for inbox previews.",
"properties": {
"browser": {
"type": "string",
"description": "Browser used to render the client. Populates when `category` is `Web`.",
"example": ""
},
"category": {
"type": "string",
"enum": [
"Mobile",
"Application",
"Web"
],
"description": "Where the client renders. `Mobile` is a phone's native mail app, for example the Gmail App on Android devices. `Application` is a desktop native mail app, for example Apple Mail on macOS. `Web` is webmail viewed in a desktop browser, for example Gmail.com in Firefox, and includes a `browser` value.\n",
"example": "Mobile"
},
"client": {
"type": "string",
"description": "Name of the email client and device.",
"example": "Gmail App Pixel 6"
},
"id": {
"type": "string",
"description": "Identifier to pass in `client_ids` when you send for an inbox preview.",
"example": "android12_gmailapp_pixel6_dm"
},
"os": {
"type": "string",
"description": "Operating system the client runs on. Look for `(Dark Mode)` if you want to locate preview options for dark mode.\n",
"example": "Android 12 (Dark Mode)"
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Inbox previews aren't enabled for your account.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "inbox previews are not enabled for this account",
"status": "404"
}
]
}
}
}
},
"429": {
"description": "Over the App API's shared limit of 10 requests per second per workspace—the same bucket every call in your workspace that isn't separately rate limited draws from, writes included. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited to 10 requests per second",
"status": "429"
}
]
}
}
}
},
"503": {
"description": "The device catalog is temporarily unavailable. This is transient—retry in a moment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "service unavailable",
"status": "503"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/inbox_previews/credits": {
"get": {
"tags": [
"Email testing"
],
"summary": "Get preview credit balance",
"description": "Returns your account's credit balance for inbox previews. Your credit balance determines how many previews you can generate in your account.\n\nLearn more about [how inbox previews use credits](/accounts/billing/inbox-previews/).\n",
"operationId": "getInboxPreviewCredits",
"security": [
{
"Bearer-Auth": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"credits": {
"type": "array",
"items": {
"type": "object",
"description": "Credits available for generating inbox previews.",
"properties": {
"credits_original": {
"type": "integer",
"description": "Credits originally granted for a tier."
},
"credits_remaining": {
"type": "integer",
"description": "Credits left to spend from this tier."
},
"expires_at": {
"type": [
"integer",
"null"
],
"format": "Unix timestamp",
"description": "When this pool's credits expire, if ever. Expiry is set per pool, not per tier—a purchased pool typically doesn't expire, but a free pool support granted can carry an expiration date. The monthly allowance's `expires_at` also reads `null` when Customer.io can't resolve your current billing period; that's a transient read issue, not a sign the allowance never expires."
},
"tier": {
"type": "string",
"enum": [
"free",
"paid"
],
"description": "The credit tier this pool belongs to. The [`free` tier](/accounts/billing/inbox-previews/) covers two kinds of pools, the monthly allowance of 25 credits every account gets and any free pools Customer.io support has granted. Because of that, `free` can appear more than once in the response. The `paid` tier covers credits purchased for the account."
}
},
"example": [
{
"tier": "free",
"credits_original": 25,
"credits_remaining": 0,
"expires_at": 1715769600
},
{
"tier": "paid",
"credits_original": 100,
"credits_remaining": 90,
"expires_at": null
}
]
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Inbox previews aren't enabled for your account.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "inbox previews are not enabled for this account",
"status": "404"
}
]
}
}
}
},
"429": {
"description": "Over the App API's shared limit of 10 requests per second per workspace—the same bucket every call in your workspace that isn't separately rate limited draws from, writes included. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited to 10 requests per second",
"status": "429"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/inbox_previews": {
"post": {
"tags": [
"Email testing"
],
"summary": "Send for inbox previews",
"description": "Initiate one or more inbox previews for an email. This uses inbox preview credits; check your balance with [Get preview credit balance](/integrations/api/design-studio/tag/email-testing/getInboxPreviewCredits/). [**Learn how billing for inbox previews work before you call this endpoint.**](/accounts/billing/inbox-previews/)\n\nUse [List emails](/integrations/api/design-studio/tag/emails/listEmails/) to get your email's ID. If the email has translations, call [List email translations](/integrations/api/design-studio/tag/emails/listEmailTranslations/) to get the ID of the language variant you want a preview of.\n\nYou can retrieve client IDs from [List inbox preview options](/integrations/api/design-studio/tag/email-testing/listInboxPreviewClients/).\n\nThis call does not return the preview file. It returns a `run_id`; poll [Get an inbox preview job](/integrations/api/design-studio/tag/email-testing/getInboxPreviewJob/) with it, then fetch each tile's capture URL from that response.\n\nSubmitting the same email, content, and devices again on the same UTC day returns the existing run instead of starting a new one, with `replayed` set to `true` and no second charge. The same happens the next day if that run is still processing, or if a concurrent identical request gets there first. Resubmitting a stuck run is safe and free—it hands you the same run back rather than starting a second one.\n",
"operationId": "submitInboxPreview",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"client_ids"
],
"properties": {
"client_ids": {
"type": "array",
"description": "The identifiers of the preview options you want. You can retrieve client IDs from [List inbox preview options](/integrations/api/design-studio/tag/email-testing/listInboxPreviewClients/).\n",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 150
},
"lax_mode": {
"type": "boolean",
"description": "Set to `true` to render liquid variables missing from `sample_data` as blank instead of failing the job.",
"default": false
},
"name": {
"type": "string",
"description": "A label for the batch of previews, shown in [preview history](/integrations/api/design-studio/tag/email-testing/listInboxPreviewJobs/).",
"maxLength": 191
},
"sample_data": {
"type": "object",
"description": "Liquid variables to render with, as a JSON object—any shape is accepted, from flat variables like `{\"first_name\": \"Janine\"}` to nested ones like `{\"customer\": {\"first_name\": \"Janine\"}}`. Defaults to none, which fails the render on any variable the content needs beyond the ones a preview already sets for you. Set `lax_mode` to render missing variables as blank instead. Limited to 128 KB.\n",
"additionalProperties": true
}
},
"example": {
"client_ids": [
"android12_gmailapp_pixel6_dm",
"android12_gmailapp_pixel6_dm_dark"
],
"name": "Welcome email previews",
"sample_data": {
"customer": {
"first_name": "Janine"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Preview job submitted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"replayed": {
"type": "boolean",
"description": "`true` when this call returned an existing run instead of starting a new one, and you weren't charged a second time for it. This happens for an identical request (same email, content, and devices) submitted again on the same UTC day, an identical request from the day before that's still processing, or a concurrent identical request that got there first. The run may belong to another client in your workspace, including the Journeys UI—`created_at` is that run's, and a `name` you send is applied to it.\n"
},
"run_id": {
"type": "integer",
"description": "ID of the preview job. Check when it's complete with [Get an inbox preview job](/integrations/api/design-studio/tag/email-testing/getInboxPreviewJob/)."
}
}
},
"example": {
"replayed": false,
"run_id": 10
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"403": {
"description": "Your account can't be charged for inbox preview credits right now. Credits are account-level—every workspace on the account draws from the same pools, so this isn't specific to the workspace in your credentials.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "this account cannot be charged for inbox previews",
"status": "403"
}
]
}
}
}
},
"404": {
"description": "The requested resource was not found.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "resource not found",
"status": "404"
}
]
}
}
}
},
"409": {
"description": "A retry crossed an interrupted charge for this batch. This means one of two things:\n - The batch was already charged and settled today.\n - An earlier attempt at the same batch is still being reconciled.\n\nChange the devices or nodes you're previewing, or retry later. Either way, you weren't double-charged.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "this preview batch was already charged and settled today. Change the devices or nodes you are previewing, or try again tomorrow.",
"status": "409"
}
]
}
}
}
},
"422": {
"description": "Not enough inbox preview credits to cover every device in `client_ids`. The message names both figures, so you can size a top-up without a separate call to [Get preview credit balance](/integrations/api/design-studio/tag/email-testing/getInboxPreviewCredits/).",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "insufficient inbox preview credits: this request needs 12, the account has 4 available",
"status": "422"
}
]
}
}
}
},
"429": {
"description": "Rate limited to 5 requests per second per workspace—a bucket shared with the Design Studio link, publish, render, preview, and review endpoints, and tighter than the 10 per second reads get, because each call starts a server-side render before it reaches the vendor. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited to 5 requests per second",
"status": "429"
}
]
}
}
}
},
"503": {
"description": "The email or Liquid renderer couldn't be reached. This is transient—retry in a moment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "the email renderer could not be reached; try again in a moment",
"status": "503"
}
]
}
}
}
}
},
"x-codeSamples": [
{
"lang": "json",
"label": "JSON",
"source": "{\n \"client_ids\": [\n \"android12_gmailapp_pixel6_dm\",\n \"android12_gmailapp_pixel6_dm_dark\"\n ],\n \"name\": \"Welcome email previews\",\n \"sample_data\": {\n \"customer\": {\n \"first_name\": \"Janine\"\n }\n }\n}"
}
]
}
},
"/v1/design_studio/emails/{id}/inbox_previews/{run_id}": {
"get": {
"tags": [
"Email testing"
],
"summary": "Get an inbox preview job",
"description": "Returns the status of a preview job submitted with [Send for inbox previews](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/), including each preview's settings.\n",
"operationId": "getInboxPreviewJob",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "run_id",
"in": "path",
"required": true,
"description": "The ID of the inbox preview job, returned by [Send for inbox previews](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/).",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "The status and results of an Inbox Previews job.",
"properties": {
"client_ids": {
"type": "array",
"description": "The device identifiers requested for this job.",
"items": {
"type": "string"
}
},
"created_at": {
"type": "integer",
"format": "Unix timestamp",
"description": "When you submitted the preview job."
},
"is_processed": {
"type": "boolean",
"description": "`true` once every device has settled, for the email in the path—a multi-language run reports each of its emails separately, so this doesn't reflect the whole run when it covers more than one. Poll this field, and see the endpoint description for how often, and for when to give up.\n"
},
"name": {
"type": "string",
"description": "The batch label provided when you sent an email for previews. Empty if none was given."
},
"previews": {
"type": "array",
"description": "One object per requested preview.",
"items": {
"type": "object",
"description": "The data for a single preview.",
"properties": {
"browser": {
"type": "string",
"description": "Browser used to render the client, when applicable. Populates when `category` is `Web`."
},
"cached": {
"type": "boolean",
"description": "Set when the item wasn't newly generated in this preview job because it had already been generated. Omitted when `false`."
},
"category": {
"type": "string",
"enum": [
"Mobile",
"Application",
"Web"
],
"description": "Client category. `Mobile` is a phone's native mail app, for example the Gmail App on Android devices. `Application` is a desktop native mail app, for example Apple Mail on macOS. `Web` is webmail viewed in a desktop browser, for example Gmail.com in Firefox, and includes a `browser` value."
},
"client_id": {
"type": "string",
"description": "The preview identifier, matching a value from `client_ids` in the submit request."
},
"display_name": {
"type": "string",
"description": "Human-readable name of the client and device used to render the preview."
},
"error": {
"type": "object",
"description": "Details for a tile whose rendering failed.",
"properties": {
"message": {
"type": "string",
"description": "A human-readable explanation, safe to show to a user."
},
"type": {
"type": "string",
"enum": [
"bounced",
"vendor_timeout",
"client_rejected",
"vendor_request",
"abandoned",
"expired",
"other"
],
"description": "Why this device has no screenshot:\n - `bounced`: the vendor rendered the device and reported a bounce.\n - `vendor_timeout`: submitted to the vendor, but didn't finish in time.\n - `client_rejected`: the vendor refused the device id.\n - `vendor_request`: the submission to the vendor itself failed.\n - `abandoned`: submitted, but the outcome is unknown.\n - `expired`: the screenshot rendered successfully but has since aged out of its retention window and is no longer available. Unlike the other types, this isn't a render failure.\n - `other`: any other cause.\n\nA tile with any of these types (except `expired`) was refunded its credit.\n"
}
}
},
"full_thumbnail": {
"type": "string",
"description": "Capture URL for a reduced, full-length version of the default screenshot. Omitted unless the render completed."
},
"os": {
"type": "string",
"description": "Operating system the client runs on."
},
"screenshots": {
"type": "object",
"description": "Capture URLs keyed by image name—the full-size screenshot under `default`, plus a key per extra image the device renders. This is the only place the full-size URL appears; `thumbnail` and `full_thumbnail` are reduced variants. Omitted unless the render completed.",
"additionalProperties": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"Pending",
"Processing",
"Complete",
"Bounced"
],
"description": "The vendor's own status for this device's render. Only `Complete` and `Bounced` are terminal."
},
"thumbnail": {
"type": "string",
"description": "Capture URL for a reduced-size version of the default screenshot. Useful for grid/list views where you don't want to load full-size screenshots. Omitted unless the render completed."
}
}
}
},
"run_id": {
"type": "integer",
"description": "ID of the preview job."
},
"total_previews_bounced": {
"type": "integer",
"description": "Previews that produced no screenshot, whether the vendor bounced them or they failed on Customer.io's side. Their credits are refunded when the run settles."
},
"total_previews_cached": {
"type": "integer",
"description": "Previews served from an earlier run's screenshot. Not charged, and not counted in `total_previews_succeeded`."
},
"total_previews_ready": {
"type": "integer",
"description": "How many previews show a screenshot you can fetch, counted from the tiles themselves. This is the progress count to compare against `total_previews_requested`—`total_previews_succeeded` alone reads `0` on a fully cached run. It isn't the completion signal; `is_processed` is. Because a tile can be served by an earlier screenshot of the same content while this run's own render is still in flight, this can reach `total_previews_requested` before the run finishes.\n"
},
"total_previews_requested": {
"type": "integer",
"description": "Previews requested in the job, for the email in the path. On a settled run, this is normally `total_previews_cached` + `total_previews_succeeded` + `total_previews_bounced`."
},
"total_previews_succeeded": {
"type": "integer",
"description": "Previews this run generated itself, excluding cached ones. A fully cached run reports `0` here even though every tile is `Complete`—compare `total_previews_ready` against `total_previews_requested` instead to track progress."
},
"updated_at": {
"type": "integer",
"format": "Unix timestamp",
"description": "When the job's status was last updated."
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The job doesn't exist, or inbox previews aren't enabled for your workspace.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"429": {
"description": "Over the App API's shared limit of 10 requests per second per workspace—the same bucket every call in your workspace that isn't separately rate limited draws from, writes included. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited to 10 requests per second",
"status": "429"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/emails/{id}/inbox_previews/{run_id}/captures/{client_id}": {
"get": {
"tags": [
"Email testing"
],
"summary": "Get a preview screenshot",
"description": "Returns the image bytes for a single preview job, proxied from the vendor. The response's content type matches whatever the vendor sent for that capture, which isn't always PNG, and the `Content-Disposition` filename's extension matches it. You can also use the URL paths in the response of [Get an inbox preview job](/integrations/api/design-studio/tag/email-testing/getInboxPreviewJob/) to complete this request.\n",
"operationId": "getInboxPreviewCapture",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The UUID of the email. If your email has translations, this is the ID of a specific language variant.\n",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "run_id",
"in": "path",
"required": true,
"description": "The ID of the inbox preview job, returned by [Send for inbox previews](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/).",
"schema": {
"type": "integer"
}
},
{
"name": "client_id",
"in": "path",
"required": true,
"description": "The device identifier for the capture, matching a value from `client_ids` in the response of [Send for inbox previews](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/).",
"schema": {
"type": "string"
}
},
{
"name": "variant",
"in": "query",
"description": "The image to return.",
"schema": {
"type": "string",
"enum": [
"screenshot",
"thumbnail",
"full_thumbnail"
],
"default": "screenshot"
}
},
{
"name": "key",
"in": "query",
"description": "Only applies when `variant` is `screenshot`. Match this to a key in that tile's `screenshots` object from [Get an inbox preview job](/integrations/api/design-studio/tag/email-testing/getInboxPreviewJob/)—most devices only have `default`, but some carry extra vendor-defined captures, like an image-blocking render.\n",
"schema": {
"type": "string",
"default": "default"
}
}
],
"responses": {
"200": {
"description": "Image bytes for the requested capture, in whatever format the vendor sent it.",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/jpeg": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/gif": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/webp": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/svg+xml": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/avif": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/bmp": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/tiff": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/x-icon": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "Invalid `variant` value.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "The capture doesn't exist, is still rendering, bounced, or has expired, or inbox previews aren't enabled for your workspace.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"429": {
"description": "Over the App API's shared limit of 10 requests per second per workspace—the same bucket every call in your workspace that isn't separately rate limited draws from, writes included. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited to 10 requests per second",
"status": "429"
}
]
}
}
}
}
}
}
},
"/v1/design_studio/inbox_previews/jobs": {
"get": {
"tags": [
"Email testing"
],
"summary": "List inbox preview history",
"description": "Returns a paginated history of inbox preview jobs across your workspace, or for a single email when you pass `node_id`. Only lists runs recent enough for their screenshots to still be viewable—an older run won't appear here even though it still exists.\n",
"operationId": "listInboxPreviewJobs",
"security": [
{
"Bearer-Auth": []
}
],
"parameters": [
{
"name": "node_id",
"in": "query",
"description": "Filter to preview jobs submitted for a specific email.",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "limit",
"in": "query",
"description": "Number of jobs to return per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
},
{
"name": "cursor",
"in": "query",
"description": "A pagination cursor returned in the previous page's `meta.pagination.next_cursor`. Omit to return the first page.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "The `limit` used for this page."
},
"next_cursor": {
"type": "string",
"description": "Pass this as `cursor` to fetch the next page. Omitted when there are no more results."
}
}
}
}
},
"preview_jobs": {
"type": "array",
"items": {
"type": "object",
"description": "A summary entry in the inbox previews job history.",
"properties": {
"created_at": {
"type": "integer",
"format": "Unix timestamp",
"description": "When the job was submitted."
},
"is_processed": {
"type": "boolean",
"description": "`true` once every device of every counted node has settled. Under a `node_id` filter, \"counted\" means the matched nodes only.\n"
},
"name": {
"type": "string",
"description": "The batch label provided when the job was submitted."
},
"node_count": {
"type": "integer",
"description": "How many email nodes the run covers—more than one for a multi-language run. Under a `node_id` filter, how many of them matched."
},
"node_id": {
"type": "string",
"format": "uuid",
"description": "The email node the run covers, or the first of them when it covers several. Under a `node_id` filter, this is the matched node."
},
"run_id": {
"type": "integer",
"description": "ID of the preview job."
},
"total_previews_bounced": {
"type": "integer",
"description": "Previews that produced no screenshot, whether the vendor bounced them or they failed on Customer.io's side, as stored when each node settled. Their credits are refunded."
},
"total_previews_cached": {
"type": "integer",
"description": "Previews served from an earlier run's screenshot. Not charged, and not counted in `total_previews_succeeded`."
},
"total_previews_ready": {
"type": "integer",
"description": "`total_previews_cached` + `total_previews_succeeded`, from the counters stored on the run. The cached half is final as soon as the run exists; the succeeded half counts only nodes that have settled, so a run still generating reads low until `is_processed` is `true`. This list can't see a tile served by an earlier screenshot of the same content, so it can read lower than [Get an inbox preview job](/integrations/api/design-studio/tag/email-testing/getInboxPreviewJob/) reports for the same run—poll the run for the authoritative count.\n"
},
"total_previews_requested": {
"type": "integer",
"description": "Previews requested across the counted nodes. On a settled run, this is normally `total_previews_cached` + `total_previews_succeeded` + `total_previews_bounced`."
},
"total_previews_succeeded": {
"type": "integer",
"description": "Previews this run generated itself, as stored when each node settled. Excludes cached ones, and counts only nodes that have settled—so a run still generating reads `0` here even once some devices are done."
},
"updated_at": {
"type": "integer",
"format": "Unix timestamp",
"description": "When the job's status was last updated."
}
}
}
}
}
},
"example": {
"meta": {
"pagination": {
"limit": 50
}
},
"preview_jobs": [
{
"created_at": 1773856017,
"is_processed": true,
"name": "Welcome email previews",
"node_count": 1,
"node_id": "018fbb92-6d1e-7c33-9c2c-df6a2b5aa931",
"run_id": 2,
"total_previews_bounced": 0,
"total_previews_cached": 4,
"total_previews_ready": 12,
"total_previews_requested": 12,
"total_previews_succeeded": 8,
"updated_at": 1773856032
},
{
"created_at": 1773855001,
"is_processed": false,
"name": "Order confirmation previews",
"node_count": 1,
"node_id": "018fbb90-1a2f-7e21-8f3d-56b1c0a2e410",
"run_id": 1,
"total_previews_bounced": 0,
"total_previews_cached": 2,
"total_previews_ready": 2,
"total_previews_requested": 10,
"total_previews_succeeded": 0,
"updated_at": 1773855950
}
]
}
}
}
},
"400": {
"description": "The request is invalid due to malformed parameters, missing required fields, or constraint violations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"401": {
"description": "Authentication failed due to a missing or invalid API key.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "unauthorized",
"status": "401"
}
]
}
}
}
},
"404": {
"description": "Inbox previews aren't enabled for your workspace.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
}
}
}
},
"429": {
"description": "Over the App API's shared limit of 10 requests per second per workspace—the same bucket every call in your workspace that isn't separately rate limited draws from, writes included. The response carries a `Retry-After` header.\n",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "An error response containing one or more error details.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors that occurred while processing the request.",
"items": {
"type": "object",
"properties": {
"detail": {
"type": "string",
"description": "A human-readable description of the error."
},
"meta": {
"type": "object",
"description": "Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language."
},
"source": {
"type": "object",
"description": "The request field that caused the error. Validation errors (`422`) include it.",
"properties": {
"pointer": {
"type": "string",
"description": "The path to the field that failed, like `/data/attributes/content`."
}
}
},
"status": {
"type": "string",
"description": "The HTTP status code for this error, as a string."
}
}
}
}
}
},
"example": {
"errors": [
{
"detail": "rate limited to 10 requests per second",
"status": "429"
}
]
}
}
}
}
}
}
}
}
}