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.
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)
https://a.klaviyo.com
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.
To view your API key, you need to log in.
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.
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.
Returns a list of all the campaigns you've created. The campaigns are returned in reverse sorted order by the time they were created.
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"
},
{...},
{...}
]
}
Creates a new campaign. The created campaign is a draft and is not automatically sent.
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"
}
Summary information for the campaign specified that includes the name, ID, list, subject, from email address, from name, status and date created.
There are no arguments for this method.
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"
}
Update details of the campaign. You can update a campaign's name, subject, from email address, from name, template or list.
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"
}
The endpoint queues a campaign for immediate delivery.
There are no arguments for this method.
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 for a time in the future.
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 send. Marks a campaign as cancelled regardless of it's current status.
There are no arguments for this method.
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"
}
Create a copy of a campaign. The new campaign starts as a draft.
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"
}
Summary information about email recipients for the campaign specified that includes each recipients email, customer ID, and status.
asc or desc. Defaults to asc.
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="
}