Unlayer Cloud API (2)

Download OpenAPI specification:Download

Introduction

Welcome to the Unlayer REST API documentation. Our API enables you to programmatically access and manipulate email templates, designs, and other Unlayer resources.

Authentication

The Unlayer API uses Basic Authentication. All requests require you to authenticate using a Unlayer Project API Key as the username with an empty string as the password:

curl -u YOUR_API_KEY: -X GET https://api.unlayer.com/v2/templates

All API calls must use HTTPS. Any calls made using HTTP will return an appropriate error code.

Get your API Key

Follow these steps to get your API key:

Log in to the Developer Console
Create a Project
Find your API key in Project > Settings

Authorization: Basic BASE64-ENCODED-API-KEY

Basic Authentication

If you need to, you may construct and send basic auth headers yourself. To do this you need to perform the following steps:

Get the API Key
Build a string in the form of APIKey:Password where Password will always be empty. For example, if your API Key is XAyAztva4, you will just add a : at the end. XAyAztva4:
Base64 encode the string
Supply an Authorization header with content Basic followed by the encoded string. For example, the string XAyAztva4: encodes to WEF5QXp0dmE0Og== in base64. Here's how the request would look:

  curl -D- \
    -X GET \
    -H "Authorization: Basic WEF5QXp0dmE0Og==" \
    "https://api.unlayer.com/v2/templates"

Errors

All API requests will receive a standard HTTP response code.

Response Ranges

2xx -- Successful Request
4xx -- Failed Request (Client error)
5xx -- Failed Request (Server error)

Versioning

This API is versioned. The current version is 2.0.

/templates

Manage email templates

/templates

GET https://api.unlayer.com/v2/templates

Get a list of available templates

Authorizations:

basicAuth

query Parameters

page	integer >= 1 Default: 1 Current page
perPage	integer >= 1 Default: 20 Number of templates to fetch per page
includeDesign	integer Default: 1 Enum: 0 1 Should the result include design json or not. This is not recommended as it could result in long response. To disable, pass 0.

Responses

Response samples

200

Content type

application/json

{"success": true,
"data": [{"id": "string",
"name": "string",
"design": { },
"displayMode": "string",
"updatedAt": "string",
"createdAt": "string"
}
]
}

/templates/:id

GET https://api.unlayer.com/v2/templates/{id}

Get a specific template by ID

path Parameters

id

required

string

ID of the template to retrieve

Responses

Response samples

200

Content type

application/json

{"success": true,
"data": {"id": "string",
"name": "string",
"design": { },
"displayMode": "string",
"updatedAt": "string",
"createdAt": "string"
}
}

/templates/validate

Check a design JSON against the Unlayer schema — in CI, in import pipelines, or before saving. A schema problem caught here is a clear error message instead of a broken render. Older designs are upgraded to the current schema first, and custom tool blocks can be deep-checked by passing your tool declarations.

See Design Schema → Design object for the design shape this endpoint expects.

This endpoint lives on the v3 base URL: https://api.unlayer.com/v3. Authenticate with a Bearer token (API key with the unlayer_sk_ prefix).

/templates/schema

GET https://api.unlayer.com/v3/templates/schema

Download the canonical design schema as a standard JSON Schema document — the exact schema /templates/validate checks against. Plug it into any JSON Schema validator, IDE, or codegen tooling.

Serves the Full schema by default; pass simple=true for the compact Simple schema. No authentication required.

query Parameters

simple	boolean Default: false When `true`, returns the Simple schema instead of the Full schema.
displayMode	string Default: "email" Enum: "email" "web" "document" "popup" Display mode whose rules the schema describes. Defaults to `email`.

Responses

Response samples

200

Content type

application/json

{ }

/templates/validate

POST https://api.unlayer.com/v3/templates/validate

Check a design JSON against the Unlayer schema. Every checked design gets HTTP 200 — read data.valid, not the status code; only malformed requests (missing design, unknown displayMode) return 400 with error: VALIDATION_ERROR. Invalid designs come back with data.errors: the dotted path, message, and code of every issue. Built-in content blocks are validated against their exact per-type schemas, not just the content envelope.

Designs saved by an older editor version are upgraded to the current schema before checking, the same way the editor and the convert endpoints treat stored designs. Pass migrate: false to check strict conformance with the current schema version instead.

Using custom tools? Pass their declarations in customTools and each matching block's values is checked against the tool's declared options, with wrong types reported at their exact path. Blocks of undeclared tools are only checked for the { type, values } envelope.

Known limitation: body.headers and body.footers are not yet part of the body schema — their content blocks are deep-checked, but header/footer structure itself is not validated.

Authorizations:

bearerAuth

Request Body schema: application/json
required

required	object The design JSON to validate.
schema	string Default: "full" Enum: "full" "simple" Which form of the schema to validate against.
displayMode	string Default: "email" Enum: "email" "web" "document" "popup" Display mode for the design. Some validation rules differ per mode. Defaults to `email` — designs saved from a different display mode should pass it explicitly.
migrate	boolean Default: true Upgrade designs with an older `schemaVersion` to the current schema before validating — designs without a `schemaVersion` predate versioning and are fully migrated the same way. Full form only. Set to `false` for strict current-version checking. Designs with a newer `schemaVersion` than the API knows are validated as-if-current; fractional or negative versions are rejected with an `invalid_schema_version` issue.
	Array of objects <= 100 items Custom tool declarations, in the same shape passed to `unlayer.registerTool` (up to 100 tools, 100 option groups each). Enables deep validation of matching custom blocks' `values`.

Responses

Request samples

Payload

Content type

application/json

{"displayMode": "email",
"design": {"counters": {"u_row": 1,
"u_column": 1,
"u_content_button": 1
},
"body": {"id": "body-1",
"rows": [{"id": "row-1",
"cells": [1
],
"columns": [{"id": "col-1",
"contents": [{"id": "btn-1",
"type": "button",
"values": {"text": "Shop now"
}
}
],
"values": { }
}
],
"values": { }
}
],
"values": { }
},
"schemaVersion": 25
}
}

Response samples

200
400

Content type

application/json

Example

The design conforms

{"success": true,
"data": {"valid": true
}
}

/template-folders

Manage template folders

/template-folders/:id/templates

GET https://api.unlayer.com/v2/template-folders/{id}/templates

Get a list of templates in a specific folder

path Parameters

id

required

string

ID of the folder to retrieve templates from

query Parameters

page	integer >= 1 Default: 1 Current page
perPage	integer >= 1 Default: 20 Number of templates to fetch per page
includeDesign	integer Default: 1 Enum: 0 1 Should the result include design json or not. This is not recommended as it could result in long response. To disable, pass 0.

Responses

Response samples

200

Content type

application/json

{"success": true,
"data": [{"id": "string",
"name": "string",
"design": { },
"displayMode": "string",
"updatedAt": "string",
"createdAt": "string"
}
]
}

/templates/convert

Convert a design JSON between Unlayer's two schema forms:

Full — the rich representation the editor manipulates in memory. Every option, every computed default, every internal property. Verbose but lossless.
Simple — the compact representation Unlayer stores and ships over the wire. Strips defaults and editor-only metadata, keeping the parts an external consumer needs.

Round-trip safely by passing includeConversion: true on the way out — the embedded _conversion metadata restores original values without data loss.

See Design Schema → Design object for the shape these endpoints accept and return.

These endpoints live on the v3 base URL: https://api.unlayer.com/v3. Authenticate with a Bearer token (API key with the unlayer_sk_ prefix).

/templates/convert/full-to-simple

POST https://api.unlayer.com/v3/templates/convert/full-to-simple

Convert a design from the Full schema to the Simple schema. Use this when you have an in-editor design and need to send it somewhere that expects the Simple shape — your own backend storage, a webhook payload, the /templates/validate endpoint when validating against the simple form, and so on.

Authorizations:

bearerAuth

Request Body schema: application/json
required

required	object The Full-schema design JSON.
displayMode	string Default: "email" Enum: "email" "web" "document" "popup" Display mode of the design. Defaults to `email`, matching `/templates/validate`. Mode-specific repairs apply during conversion (email caps `contentWidth` at 900px, for example), so pass the design's actual mode — a web design converted under the email default can be altered.
includeDefaultValues	boolean Default: false When `true`, keeps explicit default values in the output instead of stripping them.
includeConversion	boolean Default: false When `true`, embeds a `_conversion` metadata block in the response. Round-trip with `/templates/convert/simple-to-full` to recover original values without data loss.

Responses

Request samples

Payload

Content type

application/json

{"displayMode": "email",
"includeConversion": true,
"design": {"counters": {"u_row": 1,
"u_column": 1,
"u_content_button": 1
},
"body": {"id": "body-1",
"rows": [{"id": "row-1",
"cells": [1
],
"columns": [{"id": "col-1",
"contents": [{"id": "btn-1",
"type": "button",
"values": {"text": "Shop now",
"href": {"name": "web",
"values": {"href": "https://example.com",
"target": "_blank"
}
}
}
}
],
"values": { }
}
],
"values": { }
}
],
"values": { }
},
"schemaVersion": 25
}
}

Response samples

200
400

Content type

application/json

{"success": true,
"data": {"design": {"body": {"id": "body-1",
"rows": [{"id": "row-1",
"cells": [1
],
"columns": [{"id": "col-1",
"contents": [{"id": "btn-1",
"type": "button",
"values": {"text": "Shop now",
"href": "https://example.com"
}
}
],
"values": { }
}
],
"values": { }
}
],
"values": { }
},
"schemaVersion": 25,
"_conversion": {"data": "JTdCJTIycmVtb3ZlZEZyb21GdWxsRGF0YSUyMiUzQSU1QiU1RC4uLg==",
"version": 1
}
}
}
}

/templates/convert/simple-to-full

POST https://api.unlayer.com/v3/templates/convert/simple-to-full

Convert a design from the Simple schema to the Full schema. If the input was produced by /templates/convert/full-to-simple with includeConversion: true, the embedded _conversion metadata is used to restore original values without data loss.

Authorizations:

bearerAuth

Request Body schema: application/json
required

required	object The Simple-schema design JSON. May include a `_conversion` block produced by `/templates/convert/full-to-simple` — the metadata is validated before use: `version` is required and must be 1 whenever `data` is non-empty, the blob must decode to the conversion-metadata structure, and the restored Full design is checked before it is returned. Anything else fails with `invalid_conversion_data`.
displayMode	string Default: "email" Enum: "email" "web" "document" "popup" Display mode of the design. Defaults to `email`, matching `/templates/validate`. Mode-specific repairs apply during conversion (email caps `contentWidth` at 900px, for example), so pass the design's actual mode — a web design converted under the email default can be altered.
includeDefaultValues	boolean Default: false When `true`, includes explicit default values in the output.

Responses

Request samples

Payload

Content type

application/json

{"displayMode": "email",
"design": {"body": {"id": "body-1",
"rows": [{"id": "row-1",
"cells": [1
],
"columns": [{"id": "col-1",
"contents": [{"id": "btn-1",
"type": "button",
"values": {"text": "Shop now",
"href": "https://example.com"
}
}
],
"values": { }
}
],
"values": { }
}
],
"values": { }
},
"schemaVersion": 25,
"_conversion": {"data": "JTdCJTIycmVtb3ZlZEZyb21GdWxsRGF0YSUyMiUzQSU1QiU1RC4uLg==",
"version": 1
}
}
}

Response samples

200
400

Content type

application/json

{"success": true,
"data": {"design": {"counters": {"u_row": 1,
"u_column": 1,
"u_content_button": 1
},
"body": {"id": "body-1",
"rows": [{"id": "row-1",
"cells": [1
],
"columns": [{"id": "col-1",
"contents": [{"id": "btn-1",
"type": "button",
"values": {"text": "Shop now",
"href": {"name": "web",
"values": {"href": "https://example.com",
"target": "_blank"
}
}
}
}
],
"values": { }
}
],
"values": { }
}
],
"values": { }
},
"schemaVersion": 25
}
}
}

/export

You can use Unlayer's Cloud API to generate HTML, Image, PDF or ZIP file of your templates or designs.

The Cloud API helps you take care these common use-cases:

Retrieving the HTML: This is useful if you do not store the HTML, or need to retrieve the latest HTML for a design.
Generating a Image: This is useful to show thumbnails or previews of designs to users.
Generating a PDF: You can use this to export a design in PDF format.
Generating a ZIP: This will export a design as a ZIP file that will include their html and images.

/export/html

POST https://api.unlayer.com/v2/export/html

Export a design to HTML format with various options

Authorizations:

basicAuth

Request Body schema: application/json
required

design required	object The design JSON to export
displayMode required	string Enum: "email" "web" "popup" The display mode of the design
mergeTags	object Values to replace merge tags in the design
customJS	Array of strings URLs to your custom JS to support custom tools
editorVersion	string Optional editor version to use when exporting the design. If omitted, the API uses the X-Unlayer-Editor-Version header when present. Versions earlier than 1.438.0 use 1.438.0.

Responses

Request samples

Payload

Content type

application/json

{"design": { },
"displayMode": "email",
"mergeTags": { },
"customJS": ["string"
],
"editorVersion": "string"
}

Response samples

200

Content type

application/json

{"success": true,
"data": {"html": "string",
"chunks": {"body": "string",
"css": "string",
"js": "string",
"fonts": ["string"
]
}
}
}

/export/image

POST https://api.unlayer.com/v2/export/image

Export a design to image format (PNG)

Authorizations:

basicAuth

Request Body schema: application/json
required

design required	object The design JSON to export
displayMode required	string Enum: "email" "web" "popup" The display mode of the design
mergeTags	object Values to replace merge tags in the design
customJS	Array of strings URLs to your custom JS to support custom tools
editorVersion	string Optional editor version to use when exporting the design. If omitted, the API uses the X-Unlayer-Editor-Version header when present. Versions earlier than 1.438.0 use 1.438.0.
fullPage	boolean Default: true Generate image of the full page.

Responses

Request samples

Payload

Content type

application/json

{"design": { },
"displayMode": "email",
"mergeTags": { },
"customJS": ["string"
],
"editorVersion": "string",
"fullPage": true
}

Response samples

200

Content type

application/json

{"success": true,
"data": {"url": "string"
}
}

/export/pdf

POST https://api.unlayer.com/v2/export/pdf

Export a design to PDF format

Authorizations:

basicAuth

Request Body schema: application/json
required

design required	object The design JSON to export
displayMode required	string Enum: "email" "web" "popup" The display mode of the design
mergeTags	object Values to replace merge tags in the design
customJS	Array of strings URLs to your custom JS to support custom tools
editorVersion	string Optional editor version to use when exporting the design. If omitted, the API uses the X-Unlayer-Editor-Version header when present. Versions earlier than 1.438.0 use 1.438.0.

Responses

Request samples

Payload

Content type

application/json

{"design": { },
"displayMode": "email",
"mergeTags": { },
"customJS": ["string"
],
"editorVersion": "string"
}

Response samples

200

Content type

application/json

{"success": true,
"data": {"url": "string"
}
}

/export/zip

POST https://api.unlayer.com/v2/export/zip

Export a design as a ZIP archive containing all assets

Authorizations:

basicAuth

Request Body schema: application/json
required

design required	object The design JSON to export
displayMode required	string Enum: "email" "web" "popup" The display mode of the design
mergeTags	object Values to replace merge tags in the design
customJS	Array of strings URLs to your custom JS to support custom tools
editorVersion	string Optional editor version to use when exporting the design. If omitted, the API uses the X-Unlayer-Editor-Version header when present. Versions earlier than 1.438.0 use 1.438.0.

Responses

Request samples

Payload

Content type

application/json

{"design": { },
"displayMode": "email",
"mergeTags": { },
"customJS": ["string"
],
"editorVersion": "string"
}

Response samples

200

Content type

application/json

{"success": true,
"data": {"url": "string"
}
}

Unlayer Cloud API (2)

Introduction

Authentication

Get your API Key

Basic Authentication

Errors

Response Ranges

Versioning

/templates

/templates

Authorizations:

query Parameters

Responses

Response samples

/templates/:id

path Parameters

Responses

Response samples

/templates/validate

/templates/schema

query Parameters

Responses

Response samples

/templates/validate

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

/template-folders

/template-folders/:id/templates

path Parameters

query Parameters

Responses

Response samples

/templates/convert

/templates/convert/full-to-simple

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

/templates/convert/simple-to-full

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

/export

/export/html

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

/export/image

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

/export/pdf

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

/export/zip

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required