Documentation | Klaviyo

Templates API Overview

The 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 when 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

GET /api/v1/email-templates
POST /api/v1/email-templates
PUT /api/v1/email-template/{TEMPLATE_ID}
DELETE /api/v1/email-template/{TEMPLATE_ID}
POST /api/v1/email-template/{TEMPLATE_ID}/clone
POST /api/v1/email-template/{TEMPLATE_ID}/render
POST /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?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. Only updates imported HTML templates; does not currently update drag & drop templates.

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

from_email: string; The email address your email will be sent from and will be used in the reply-to header.
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 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"
  }
}

Integrate & Send Data

API References

Email Design

Templates API Overview

Libraries

API Endpoint

Summary of Resource URL Patterns

Authentication

Your Private API key

Errors

HTTP Status Code Summary

Versioning

Email Templates

List all templates

Arguments

Response

Creating a template

Arguments

Response

Updating an email template

Arguments

Response

Deleting template

Arguments

Response

Clone template

Arguments

Response

Render template

Arguments

Response

Render template and send email

Arguments

Response