Campaigns API Overview

The Campaigns API is used for creating and sending campaigns 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. This means a single resource or endpoint can and often does provide different functionality based on the HTTP verb used to access it. JSON is returned in all responses from the API, including errors.

Libraries

We are working on adding the Campaigns 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/campaigns
  • POST /api/v1/campaigns
  • GET /api/v1/campaign/{CAMPAIGN_ID}
  • PUT /api/v1/campaign/{CAMPAIGN_ID}
  • POST /api/v1/campaign/{CAMPAIGN_ID}/send
  • POST /api/v1/campaign/{CAMPAIGN_ID}/schedule
  • POST /api/v1/campaign/{CAMPAIGN_ID}/cancel
  • POST /api/v1/campaign/{CAMPAIGN_ID}/clone
  • POST /api/v1/campaign/{CAMPAIGN_ID}/recipients

Authentication

You authenticate to the Campaigns 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.

Campaigns in Account

Returns a list of all the campaigns you've created. The campaigns are returned in reverse sorted order by the time they were created.

Arguments
page
optional, integer, defaults to 0
For pagination, which page of results to return.
count
optional, integer, defaults to 50
For pagination, the number of results to return. The maximum number is 100.
Response

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

GET https://a.klaviyo.com/api/v1/campaigns curl https://a.klaviyo.com/api/v1/campaigns -G \ -d api_key=API_KEY { "object": "$list", "start" : 0, "end": 3, "page" : 0, "page_size": 3, "total": 3, "data": [ { "object" : "campaign", "id": "dqQnNW", "name" : "Campaign Name", "subject" : "Company Monthly Newsletter", "from_email" : "george.washington@example.com", "from_name" : "George Washington", "list_id" : "erRoOX", "template" : { "object" : "email-template", "id" : "fsSpPY", "html" : "<html><body><p>This is the email content</p></body></html>", }, "status" : "sent", "sent_at" : "2103-06-17 14:30:00", "created" : "2103-06-14 12:00:00" }, {...}, {...} ] }

Creating a Campaign

Creates a new campaign. The created campaign is a draft and is not automatically sent.

Arguments
list_id
string
The ID of the List object you will send this campaign to.
template_id
string
The ID of the Email Template object that will be the content of this campaign. Note the Email Template is copied when creating this campaign, so future changes to that Email Template will not alter the content of this campaign.
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
name
optional, string
A name for this campaign. If not specified, this will default to the subject of the campaign.
use_smart_sending
optional, boolean
If set, limits the number of emails sent to an individual within a short period. If not specified, defaults to True.
add_google_analytics
optional, boolean
If specified, adds Google Analytics tracking tags to links. If not specified, defaults to False.
Response

The newly created Campaign object with summary information.

POST https://a.klaviyo.com/api/v1/campaigns curl https://a.klaviyo.com/api/v1/campaigns \ -X POST \ -d api_key=API_KEY \ -d list_id=erRoOX \ -d template_id=gtTqQZ \ -d from_email=george.washington@example.com \ -d "from_name=George Washington" \ -d "subject=Company Monthly Newsletter" \ -d "name=Campaign Name" \ -d use_smart_sending=True \ -d add_google_analytics=True { "object" : "campaign", "id": "dqQnNW", "name" : "Campaign Name", "subject" : "Company Monthly Newsletter", "from_email" : "george.washington@example.com", "from_name" : "George Washington", "list_id" : "erRoOX", "template" : { "object" : "email-template", "id" : "fsSpPY", "html" : "<html><body><p>This is the email content</p></body></html>", }, "status" : "draft", "sent_at" : null, "created" : "2103-06-14 12:00:00" }

Campaign Information

Summary information for the campaign specified that includes the name, ID, list, subject, from email address, from name, status and date created.

Arguments

There are no arguments for this method.

Response

The Campaign object with summary information.

GET https://a.klaviyo.com/api/v1/campaign/{{ CAMPAIGN_ID }} curl https://a.klaviyo.com/api/v1/campaign/dqQnNW -G \ -d api_key=API_KEY \ { "object" : "campaign", "id": "dqQnNW", "name" : "Campaign Name", "subject" : "Company Monthly Newsletter", "from_email" : "george.washington@example.com", "from_name" : "George Washington", "list_id" : "erRoOX", "template" : { "object" : "email-template", "id" : "fsSpPY", "html" : "<html><body><p>This is the email content</p></body></html>", }, "status" : "draft", "sent_at" : null, "created" : "2103-06-14 12:00:00" }

Updating a Campaign

Update details of the campaign. You can update a campaign's name, subject, from email address, from name, template or list.

Arguments
list_id
optional, string
The ID of the List object you will send this campaign to.
template_id
optional, string
The ID of the Email Template object that will be the content of this campaign. Note the Email Template is copied when creating this campaign, so future changes to that Email Template will not alter the content of this campaign.
from_email
optional, string
The email address your email will be sent from and will be used in the reply-to header.
from_name
optional, string
The name or label associated with the email address you're sending from.
subject
optional, string
name
optional, string
A name for this campaign. If not specified, this will default to the subject of the campaign.
use_smart_sending
optional, boolean
If set, limits the number of emails sent to an individual within a short period. If not specified, defaults to True.
add_google_analytics
optional, boolean
If specified, adds Google Analytics tracking tags to links. If not specified, defaults to False.
Response

The Campaign object with summary information including updated details.

PUT https://a.klaviyo.com/api/v1/campaign/{{ CAMPAIGN_ID }} curl https://a.klaviyo.com/api/v1/campaign/dqQnNW \ -X PUT \ -d api_key=API_KEY \ -d "subject=Different Subject" \ -d "template_id=cpPlLU" { "object" : "campaign", "id": "dqQnNW", "name" : "Campaign Name", "subject" : "Different Subject", "from_email" : "george.washington@example.com", "from_name" : "George Washington", "list_id" : "erRoOX", "template" : { "object" : "email-template", "id" : "boOkKT", "html" : "<html><body><p>This is different email content</p></body></html>", }, "status" : "draft", "sent_at" : null, "created" : "2103-06-14 12:00:00" }

Send a Campaign Immediately

The endpoint queues a campaign for immediate delivery.

Arguments

There are no arguments for this method.

Response

A dictionary with a single key status which should be queued.

POST https://a.klaviyo.com/api/v1/campaign/{{ CAMPAIGN_ID }}/send curl https://a.klaviyo.com/api/v1/campaign/dqQnNW/send \ -X POST \ -d api_key=API_KEY { "status" : "queued" }

Schedule a Campaign

Schedule a campaign for a time in the future.

Arguments
send_time
datetime
A timestamp of the format "%Y-%m-%d %H:%M:%S" in the UTC timezone.
Response

A dictionary with a single key status which should be queued.

POST https://a.klaviyo.com/api/v1/campaign/{{ CAMPAIGN_ID }}/schedule curl https://a.klaviyo.com/api/v1/campaign/dqQnNW/schedule \ -X POST -d api_key=API_KEY \ -d "send_time=2013-06-14 00:00:00" { "status" : "queued" }

Cancel a Campaign

Cancel a campaign send. Marks a campaign as cancelled regardless of it's current status.

Arguments

There are no arguments for this method.

Response

The Campaign object with summary information including updated details.

POST https://a.klaviyo.com/api/v1/campaign/{{ CAMPAIGN_ID }}/cancel curl https://a.klaviyo.com/api/v1/campaign/dqQnNW/cancel \ -X POST \ -d api_key=API_KEY { "object" : "campaign", "id": "dqQnNW", "name" : "Campaign Name", "subject" : "Company Monthly Newsletter", "from_email" : "george.washington@example.com", "from_name" : "George Washington", "list_id" : "erRoOX", "template" : { "object" : "email-template", "id" : "boOkKT", "html" : "<html><body><p>This is the email content</p></body></html>", }, "status" : "cancelled", "sent_at" : null, "created" : "2103-06-14 12:00:00" }

Clone a Campaign

Create a copy of a campaign. The new campaign starts as a draft.

Arguments
name
string
The name for the new campaign. All other properties of the campaign will remain the same. Note, the template for the new campaign will be cloned from the existing template so changes to the existing campaign's content will not alter the content of the new campaign.
list_id
string
The ID of the List object you will send this campaign to.
Response

The new Campaign object with summary information including updated details.

POST https://a.klaviyo.com/api/v1/campaign/{{ CAMPAIGN_ID }}/clone curl https://a.klaviyo.com/api/v1/campaign/dqQnNW/clone \ -X POST \ -d api_key=API_KEY \ -d "name=Cloned Campaign" { "object" : "campaign", "id": "erRoOX", "name" : "Cloned Campaign", "subject" : "Company Monthly Newsletter", "from_email" : "george.washington@example.com", "from_name" : "George Washington", "list_id" : "erRoOX", "template" : { "object" : "email-template", "id" : "boOkKT", "html" : "<html><body><p>This is the email content</p></body></html>", }, "status" : "draft", "sent_at" : null, "created" : "2103-06-14 12:00:00" }

Campaign Recipient Information

Summary information about email recipients for the campaign specified that includes each recipients email, customer ID, and status.

Arguments
count
optional, integer, defaults to 5000
For pagination, the number of results to return. The maximum number is 25000.
sort
optional, string
Order results chronologically, in ascending or descending order. The possible values are asc or desc. Defaults to asc.
offset
optional, string
For pagination, if a response to this endpoint includes a next_offset, use that value to get the next page of recipients.
Response

A list of dictionaries with keys status, email, customer_id and variation_id for each email recipient.

GET https://a.klaviyo.com/api/v1/campaign/{{ CAMPAIGN_ID }}/recipients curl https://a.klaviyo.com/api/v1/campaign/dqQnNW/recipients \ -G \ -d api_key=API_KEY \ -d "count=2" { "count" : 2, "data" : [ { "status" : "Sent", "customer_id" : "dqQnNW", "email" : "abraham.lincoln@example.com", "variation_id" : null }, { "status" : "Sent", "customer_id" : "5ta2Hr", "email" : "george.washington@example.com", "variation_id" : null } ], "next_offset" : "Z2VvcmdlLndhc2hpbmd0b25AZXhhbXBsZS5jb20=" }