Before you begin
Check out our general API overview to make sure you’re ready to get started with specific endpoints.
Use the Templates API to seamlessly create, update, and manage email templates programmatically. Whether using hybrid templates compatible with Klaviyo’s drag-and-drop editor or fully custom HTML templates, the Templates API offers flexibility for tailored email experiences.
When calling the Templates API, make sure your authentication key has the appropriate scopes (
templates:read
,templates:write
).
Use cases
The Templates API supports the following use cases:
- Get, create, and manage templates.
- Create custom templates that are compatible with Klaviyo’s drag-and-drop editor (i.e., hybrid templates).
- Render a template with the given template ID and context.
- Clone a template.
Looking to assign a template to a campaign message or fetch template data for a specific campaign message? Check out our Messages endpoints within the Campaigns API.
Data model
A template has the following:
-
id
The template ID.
-
attributes
-
name
(required)The name of the template.
-
editor_type
(required)The type of editor. This is restricted to
CODE
andUSER_DRAGGABLE
(used for hybrid templates).
-
html
The HTML contents of the template.
-
text
The plaintext version of the template.
-
amp
The AMP version of the template. Requires an enabled AMP email to access in-app.
-
created
The timestamp of when the template was last created.
-
updated
The timestamp of when the metric was last updated.
-
Create a template
When creating a template with the Create Template endpoint, your request payload must include at least a template name and an editor type. The example below utilizes dynamic variables including first_name
, last_name
, discount_code
, and order_total
to tailor the content for each recipient. These variables enable seamless personalization when rendering the template.
{
"data": {
"type": "template",
"attributes": {
"name": "Personalized Discount Email",
"editor_type": "CODE",
"html": "<html>\n <head>\n <meta content=\"width=device-width, initial-scale=1.0\" name=\"viewport\" />\n <title>Special Discount for You</title>\n <style>\n body {\n background-color: #f6f6f6;\n font-family: sans-serif;\n margin: 20px;\n }\n .main {\n background: #ffffff;\n border-radius: 3px;\n width: 100%;\n }\n .container {\n margin: 0 auto !important;\n width: 600px;\n }\n .wrapper {\n box-sizing: border-box;\n padding: 15px;\n }\n table {\n width: 100%;\n }\n </style>\n </head>\n <body>\n <div class=\"container\">\n <table class=\"main\">\n <tr>\n <td class=\"wrapper\">\n <p>Hello {{ first_name }} {{ last_name }},</p>\n <p>Thank you for your order of ${{ order_total }}!</p>\n <p>As a thank you, here’s a special discount code just for you: <strong>{{ discount_code }}</strong></p>\n <p>Use it at checkout to enjoy your discount.</p>\n </td>\n </tr>\n <tr>\n <td class=\"wrapper\">{% unsubscribe %}</td>\n </tr>\n </table>\n </div>\n </body>\n</html>"
}
}
}
{
"data": {
"type": "template",
"id": "TuG2Zd",
"attributes": {
"name": "Personalized Discount Email",
"editor_type": "CODE",
"html": "<html>\n<head>\n<meta content=\"width=device-width, initial-scale=1.0\" name=\"viewport\"/>\n<title>Special Discount for You</title>\n<style>body {\n background-color: #f6f6f6;\n font-family: sans-serif;\n margin: 20px\n }\n.main {\n background: #fff;\n border-radius: 3px;\n width: 100%\n }\n.container {\n margin: 0 auto !important;\n width: 600px\n }\n.wrapper {\n box-sizing: border-box;\n padding: 15px\n }\ntable {\n width: 100%\n }</style></head>\n<body>\n<div class=\"container\">\n<table class=\"main\">\n<tr>\n<td class=\"wrapper\">\n<p>Hello {{ first_name }} {{ last_name }},</p>\n<p>Thank you for your order of ${{ order_total }}!</p>\n<p>As a thank you, here’s a special discount code just for you: <strong>{{ discount_code }}</strong></p>\n<p>Use it at checkout to enjoy your discount.</p>\n</td>\n</tr>\n<tr>\n<td class=\"wrapper\">{% unsubscribe %}</td>\n</tr>\n</table>\n</div>\n</body>\n</html>",
"text": null,
"amp": null,
"created": "2025-02-05T19:12:51.599729+00:00",
"updated": "2025-02-05T19:12:51.599758+00:00"
},
"links": {
"self": "https://a.klaviyo.com/api/templates/TuG2Zd/"
}
},
"links": {
"self": "https://a.klaviyo.com/api/templates"
}
}
Render a template
Render a template with a given template ID and context attribute (a JSON object with the context the email template is rendered with). A call to Render Template returns the AMP, HTML, and plain text versions of the email template.
Here’s the request and response for rendering the template we created above:
{
"data": {
"type": "template",
"id": "TuG2Zd",
"attributes": {
"context": {
"first_name": "John",
"last_name": "Doe",
"discount_code": "WELCOME10",
"order_total": 49.99
}
}
}
}
{
"data": {
"type": "template",
"id": "TuG2Zd",
"attributes": {
"name": "Personalized Discount Email",
"editor_type": "CODE",
"html": "<html>\n<head>\n<meta content=\"width=device-width, initial-scale=1.0\" name=\"viewport\"/>\n<title>Special Discount for You</title>\n<style>body {\n background-color: #f6f6f6;\n font-family: sans-serif;\n margin: 20px\n }\n.main {\n background: #fff;\n border-radius: 3px;\n width: 100%\n }\n.container {\n margin: 0 auto !important;\n width: 600px\n }\n.wrapper {\n box-sizing: border-box;\n padding: 15px\n }\ntable {\n width: 100%\n }</style></head>\n<body>\n<div class=\"container\">\n<table class=\"main\">\n<tr>\n<td class=\"wrapper\">\n<p>Hello John Doe,</p>\n<p>Thank you for your order of $49.99!</p>\n<p>As a thank you, here’s a special discount code just for you: <strong>WELCOME10</strong></p>\n<p>Use it at checkout to enjoy your discount.</p>\n</td>\n</tr>\n<tr>\n<td class=\"wrapper\"><a class=\"unsubscribe-link\" href=\"[unsubscribe_tag]\">Unsubscribe</a></td>\n</tr>\n</table>\n</div>\n</body>\n</html>",
"text": null,
"amp": null,
"created": "2025-02-05T19:12:52+00:00",
"updated": "2025-02-05T19:12:52+00:00"
},
"links": {
"self": "https://a.klaviyo.com/api/templates/TuG2Zd/"
}
},
"links": {
"self": "https://a.klaviyo.com/api/template-render"
}
}
Clone a template
To clone the template we created and rendered above, your request payload for Clone Template should look like the following:
{
"data": {
"type": "template",
"id": "TuG2Zd",
"attributes": {
"name": "Clone of Personalized Discount Email"
}
}
}
{
"data": {
"type": "template",
"id": "XRPRey",
"attributes": {
"name": "Clone of Personalized Discount Email",
"editor_type": "CODE",
"html": "<html>\n<head>\n<meta content=\"width=device-width, initial-scale=1.0\" name=\"viewport\"/>\n<title>Special Discount for You</title>\n<style>body {\n background-color: #f6f6f6;\n font-family: sans-serif;\n margin: 20px\n }\n.main {\n background: #fff;\n border-radius: 3px;\n width: 100%\n }\n.container {\n margin: 0 auto !important;\n width: 600px\n }\n.wrapper {\n box-sizing: border-box;\n padding: 15px\n }\ntable {\n width: 100%\n }</style></head>\n<body>\n<div class=\"container\">\n<table class=\"main\">\n<tr>\n<td class=\"wrapper\">\n<p>Hello {{ first_name }} {{ last_name }},</p>\n<p>Thank you for your order of ${{ order_total }}!</p>\n<p>As a thank you, here’s a special discount code just for you: <strong>{{ discount_code }}</strong></p>\n<p>Use it at checkout to enjoy your discount.</p>\n</td>\n</tr>\n<tr>\n<td class=\"wrapper\">{% unsubscribe %}</td>\n</tr>\n</table>\n</div>\n</body>\n</html>",
"text": null,
"amp": null,
"created": "2025-02-05T19:35:59.752156+00:00",
"updated": "2025-02-05T19:35:59.832098+00:00"
},
"links": {
"self": "https://a.klaviyo.com/api/templates/XRPRey/"
}
},
"links": {
"self": "https://a.klaviyo.com/api/template-clone"
}
}
Cloning and creating templates will fail if your account contains 1,000 or more templates, as the Templates API has a limit of 1,000 templates.
Manage templates
Update and delete templates with the Update Template and Delete Template endpoints, respectively.
Fetch templates
When making Get Template or Get Templates request, the response should resemble the following example:
curl --request GET \
--url https://a.klaviyo.com/api/templates/U7bDHv \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/vnd.api+json' \
--header 'revision: 2025-01-15'
{
"data": {
"type": "template",
"id": "U7bDHv",
"attributes": {
"name": "Clone of Monthly Newsletter Template",
"editor_type": "CODE",
"html": "<html><head></head><body>Template HTML content</body></html>",
"text": null,
"amp": null,
"created": "2025-02-04T20:39:18+00:00",
"updated": "2025-02-04T20:39:18+00:00"
},
"links": {
"self": "https://a.klaviyo.com/api/templates/U7bDHv/"
}
},
"links": {
"self": "https://a.klaviyo.com/api/templates/U7bDHv"
}
}
Querying templates
Querying templates with the Templates API can help you achieve many use cases, such as sorting templates by the date they were created. Check out the supported query parameters below and test them with our latest Postman collection. Note that support for given operators and fields is endpoint-specific. Review the API reference documentation for more information on allowed fields and query operators.
Parameter | Description | Query example |
---|---|---|
filter | Retrieve a subset of templates, e.g., templates that have been created within a given time frame. Learn about the filter query parameter. | GET /api/templates?filter=greater-than(created,"2023-06-05T12:30:00+00:00") |
sort | Sort templates, e.g., by date created in ascending order (oldest to newest). Learn about the sort query parameter. | GET /api/templates?sort=created |
fields | Request for only specified template data, e.g., name. Learn more about sparse fieldsets. | GET /api/templates?fields[template]=name |