Email Templates API Overview

The Email Templates API is used for interacting with email templates stored in Klaviyo. This API is organized around REST. The API endpoints were designed to be predictable and resource-oriented and use HTTP response codes to indicate API errors. JSON is returned in all responses from the API, including errors.

Libraries

We are working on adding the Email Templates API to our existing libraries. If you want to be notified those libraries have been updated, you can watch the following repositories:

Python (https://github.com/klaviyo/python-klaviyo)
Ruby (https://github.com/klaviyo/ruby-klaviyo)
PHP (https://github.com/klaviyo/php-klaviyo)

API Endpoint

https://a.klaviyo.com

Summary of Resource URL Patterns

  • /api/v1/email-templates
  • /api/v1/email-template/{TEMPLATE_ID}/clone
  • /api/v1/email-template/{TEMPLATE_ID}/render
  • /api/v1/email-template/{TEMPLATE_ID}/send

Authentication

You authenticate to the Email Templates API by providing one of your private API keys as part of each request. You can manage your private API keys from your account. We allow you to have multiple API keys at once in case you need more than one.

Authentication happens via the api_key parameter in each request. It can be sent as part of the GET or POST parameters.

Klaviyo's API is served over HTTPS and all requests must be authenticated.

Your Private API key

To view your API key, you need to log in.

Errors

Our API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error from information provided as part of the request (e.g. the requested object doesn't exist, an invalid setting, etc.), and codes in the 5xx range indicate an error on Klaviyo's end.

The response of all API errors contain a message parameter which has developer-facing information about why the request failed.

HTTP Status Code Summary

  • 200 OK - The request completed successfully.
  • 400 Bad request - Request is missing or has a bad parameter.
  • 400 Not Authorized - Request is missing or has an invalid API key.
  • 404 Not Found - The requested resource doesn't exist.
  • 500 Server errors - Something is wrong on Klaviyo's end.

Versioning

When we make backwards incompatible changes to the API, we release new API versions, which are reflected in the API endpoints. The current version, v1, is the first version. In the future, if we switch to v2, we will provide documentation on the changes as well as new documentation detailing how to use the new API.

Email Templates

Email template objects allow you to render and send dynamic emails based on templates you've created with the email template builder. You can also retrieve a list of email templates in your account.

List all templates

Returns a list of all the email templates you've created. The templates are returned in sorted order by name.

Arguments

There are no arguments for this method.

Response

A dictionary with a data property that contains an array of all the email templates. Each entry is a separate email template object. If no email templates exist, the resulting array will be empty. This request should never return an error.

GET https://a.klaviyo.com/api/v1/email-templates curl https://a.klaviyo.com/api/v1/email-templates \ -d api_key=API_KEY { "object": "$list", "start" : 0, "end": 3, "page" : 0, "page_size": 3, "total": 3, "data": [ { "object": "email-template", "id": "dqQnNW", "name": "Weekly Summary" }, {...}, {...} ] }

Creating a template

Creates a new email template.

Arguments
name
string
The name of the email template.
html
string
The HTML content for this template.
Response

The newly created Email Template object with summary information.

POST https://a.klaviyo.com/api/v1/email-templates curl https://a.klaviyo.com/api/v1/email-templates \ -X POST \ -d api_key=API_KEY \ -d name='My New Template' \ -d html='<html><body><p>This is an email for {{ email }}.</p></body></html>' { "object": "email-template", "id" : "dqQnNW", "name": "My New Template", "html" : "<html><body><p>This is an email for {{ email }}.</p></body></html>", "created": "2013-06-17 14:00:00", "updated": "2013-06-17 14:00:00" }

Updating an email template

Updates the name and/or HTML content of a template.

Arguments
name
optional, string
The name of the email template.
html
optional, string
The HTML content for this template.
Response

The updated Email Template object with summary information.

PUT https://a.klaviyo.com/api/v1/email-template/{{ TEMPLATE_ID }} curl https://a.klaviyo.com/api/v1/email-template/{{ TEMPLATE_ID }} \ -X PUT \ -d api_key=API_KEY \ -d name='My New Template' \ -d html='<html><body><p>This is an email for {{ email }}.</p></body></html>' { "object": "email-template", "id" : "dqQnNW", "name": "My New Template", "html" : "<html><body><p>This is an email for {{ email }}.</p></body></html>", "created": "2013-06-17 14:00:00", "updated": "2013-06-17 14:00:00" }

Deleting template

Deletes a given template.

Note: This is a destructive operation and cannot be undone. Be careful when deleting objects.

Arguments

There are no arguments for this method.

Response

The deleted Email Template object with summary information.

DELETE https://a.klaviyo.com/api/v1/email-template/{{ TEMPLATE_ID }} curl https://a.klaviyo.com/api/v1/email-template/{{ TEMPLATE_ID }} \ -X DELETE \ -d api_key=API_KEY { "object": "email-template", "name": "My New Template", "html" : "<html><body><p>This is an email for {{ email }}.</p></body></html>", "created": "2013-06-17 14:00:00", "updated": "2013-06-17 14:00:00" }

Clone template

Creates a copy of a given template with a new name.

Arguments
name
string
The name of the new email template.
Response

The newly created Email Template object with summary information.

POST https://a.klaviyo.com/api/v1/email-template/{{ TEMPLATE_ID }}/clone curl https://a.klaviyo.com/api/v1/email-template/{{ TEMPLATE_ID }}/clone \ -X POST \ -d api_key=API_KEY \ -d name='My Cloned Template' { "object": "email-template", "id" : "erRoOX", "name": "My Cloned Template", "html" : "<html><body><p>This is an email for {{ email }}.</p></body></html>", "created": "2013-06-17 14:00:00", "updated": "2013-06-17 14:00:00" }

Render template

Renders the specified template with the provided data and return HTML and text versions of the email.

Arguments
context
optional, JSON encoded hash
This is the context your email template will be rendered with. Email templates are rendered with contexts in a similar manner to how Django templates are rendered. This means that nested template variables can be referenced via dot notation and template variables without corresponding context values are treated as falsy and output nothing.
Response

The Email Template object with an additional data property that contains both the HTML and text versions of the rendered template.

POST https://a.klaviyo.com/api/v1/email-template/{{ TEMPLATE_ID }}/render curl https://a.klaviyo.com/api/v1/email-template/dqQnNW/render \ -X POST \ -d api_key=API_KEY \ -d context='{ "name" : "George Washington", "notifcation_count" : 10 }' { "object": "email-template", "id" : "dqQnNW", "name": "Weekly Summary", "data": { "html" : "<html>HTML version...", "text": "Text version ..." } }

Render template and send email

Renders the specified template with the provided data and then send the contents in an email via the service specified.

Arguments
service
string
The key of the email service you've configured to send email. This must be one of aws, klaviyo, mailgun, mandrill, postmark or sendgrid. Unless you are using klaviyo to send emails, you must connect your email service before you can send email. You can connect an email service on the manage integrations page.
from_email
string
The email address your email will be sent from and will be used in the reply-to header. Keep in mind some email services have restrictions on which email addresses you can send from.
from_name
string
The name or label associated with the email address you're sending from.
subject
string
to
mixed, string or JSON encoded array of objects with "email" and "name" keys
context
optional, JSON encoded hash
This is the context your email template will be rendered with. Email templates are rendered with contexts in a similar manner to how Django templates are rendered. This means that nested template variables can be referenced via dot notation and template variables without corresponding context values are treated as falsy and output nothing.
Response

The Email Template object with an additional data property that contains the status of the message. If successful, the status will be queued.

POST https://a.klaviyo.com/api/v1/email-template/{{ TEMPLATE_ID }}/send curl https://a.klaviyo.com/api/v1/email-template/dqQnNW/send \ -X POST \ -d api_key=API_KEY \ -d service=mandrill \ -d from_email=george.washington@example.com \ -d from_name='George Washington' \ -d subject='Your Weekly Summary' \ -d to='[{ "email" : "recipient@example.com", "name" : "Recipient Name" }]' \ -d context='{ "name" : "Recipient", "notifcation_count" : 8 }' { "object": "email-template", "id" : "dqQnNW", "name": "Weekly Summary", "data": { "status" : "queued" } }