Before you begin
Check out our general API overview to make sure you’re ready to get started with specific endpoints.
A campaign is a way to send a targeted message to an audience (lists and/or segments). Unlike a flow, which is triggered every time a condition is met, a campaign is a scheduled message (e.g., a holiday sale announcement via SMS). Our Campaigns API supports email and SMS campaigns with the following endpoint categories:
-
Campaigns
Create, retrieve, update, and delete email and SMS campaigns.
-
Messages
Retrieve and update campaign messages.
-
Jobs
Send a campaign using a campaign send job, or fetch an estimated number of recipients using a recipient estimation job.
-
Relationships
Access data on campaign messages, tags, and templates related to a specific campaign.
Use cases
The Campaigns API supports a number of use cases. Some of the more common use cases include:
- Use smart send time as a send strategy to schedule a campaign and manage the campaign send job’s status.
- Preview content by fetching a template associated with an email campaign’s message.
- Estimate the number of recipients for a given campaign.
- Clone and resend an existing campaign to different audiences.
Campaigns will not be sent out to profiles who have not provided consent (implicit for email and explicit for SMS). Learn about best practices for collecting email and SMS consent.
Data model
Email and SMS campaigns are similar in structure, but differ in how they are sent and tracked, for example, only email campaigns can track clicks and opens. Here's an example of each campaign:
{
"type": "campaign",
"id": "01H5QQV9F57XJHJDMD86RX4QM5",
"attributes": {
"name": "Holiday Sale: Email Campaign",
"status": "Draft",
"archived": false,
"audiences": {
"included": [
"WEmgye",
"YsMa4H",
"YzykDM"
],
"excluded": []
},
"send_options": {
"use_smart_sending": true,
"ignore_unsubscribes": false
},
"tracking_options": {
"is_add_utm": false,
"utm_params": [],
"is_tracking_clicks": true,
"is_tracking_opens": true
},
"send_strategy": {
"method": "immediate",
"options_static": null,
"options_throttled": null,
"options_sto": null
},
"created_at": "2023-07-19T18:50:52.779945+00:00",
"scheduled_at": null,
"updated_at": "2023-07-19T18:53:05.424510+00:00",
"send_time": null
},
"relationships": {
"campaign-messages": {
"data": [
{
"type": "campaign-message",
"id": "01H5QQV9FGJ1H66PGPER6WN9F5"
}
],
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H5QQV9F57XJHJDMD86RX4QM5/relationships/campaign-messages/",
"related": "https://a.klaviyo.com/api/campaigns/01H5QQV9F57XJHJDMD86RX4QM5/campaign-messages/"
}
},
"tags": {
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H5QQV9F57XJHJDMD86RX4QM5/relationships/tags/",
"related": "https://a.klaviyo.com/api/campaigns/01H5QQV9F57XJHJDMD86RX4QM5/tags/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H5QQV9F57XJHJDMD86RX4QM5/"
}
},
{
"type": "campaign",
"id": "01H5QN6TP7DTSJXBHSTW44E9PD",
"attributes": {
"name": "Holiday Sale: SMS Campaign",
"status": "Draft",
"archived": false,
"audiences": {
"included": [
"TUeZtq"
],
"excluded": []
},
"send_options": {
"use_smart_sending": true
},
"tracking_options": {
"is_add_utm": false,
"utm_params": []
},
"send_strategy": {
"method": "immediate",
"options_static": null,
"options_throttled": null,
"options_sto": null
},
"created_at": "2023-07-19T18:04:45.134268+00:00",
"scheduled_at": null,
"updated_at": "2023-07-19T18:05:02.347146+00:00",
"send_time": null
},
"relationships": {
"campaign-messages": {
"data": [
{
"type": "campaign-message",
"id": "RNCyHC"
}
],
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H5QN6TP7DTSJXBHSTW44E9PD/relationships/campaign-messages/",
"related": "https://a.klaviyo.com/api/campaigns/01H5QN6TP7DTSJXBHSTW44E9PD/campaign-messages/"
}
},
"tags": {
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H5QN6TP7DTSJXBHSTW44E9PD/relationships/tags/",
"related": "https://a.klaviyo.com/api/campaigns/01H5QN6TP7DTSJXBHSTW44E9PD/tags/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H5QN6TP7DTSJXBHSTW44E9PD/"
}
},
A campaign has the following structure:
-
id
(required)The campaign id.
-
attributes (required)
-
name
(required)The campaign name.
-
audiences
(required)An object containing fields for
included
and/orexcluded
audiences (lists and/or segment IDs) for the campaign. -
send_strategy
-
An object containing one of the following
method
(string) values that determines how the campaign will be sent (see API reference):-
static
Select this method if you want all recipients to receive the email at the same time. Use theoptions_static
object to set send configuration options. -
throttled
Select this method to send to a certain percentage of recipients. Use theoptions_throttled
object to set send configuration options. -
immediate (default)
Select this method if you want to send a campaign immediately. -
smart_send_time
Select this method (available to eligible senders) to determine and set the ideal send time for your audience(s). Use theoptions_sto
object to set send configuration option.
-
-
-
send_options
-
An object containing the following sending option(s) shared by email and SMS campaigns:
-
use_smart_sending
(default)A boolean option to use smart sending for your campaign (defaults to
true
). Smart sending skips recipients who have already received an email or SMS within a designated time frame.
-
-
-
tracking_options
-
An object containing the following tracking options shared by email and SMS campaigns:
-
is_add_utm
Indicates if the campaign needs UTM parameters.
-
utm_params
An array of objects representing UTM parameters. If
is_add_utm
istrue
and the list is empty, company defaults will be used.Email campaigns have the following additional tracking options:
-
is_tracking_clicks
Whether the campaign is tracking click events (defaults to
true
). -
is_tracking_opens
Whether the campaign is tracking open events (defaults to
true
).
-
-
-
-
-
campaign-messages
-
An object containing the message associated with the campaign, with the following attributes:
-
channel
The channel for the message (email or SMS).
-
label
The optional label or name on the message.
-
content
For email campaigns, this object contains various fields including, but not limited to, the email’s subject line, sending address, and reply-to address. For SMS campaigns, this object should only include a body object for the message.
-
render_options
An object containing additional options for rendering the message:
-
shorten_links
A boolean option that allows you to shorten links in the message.
-
add_org_prefix
A boolean option that allows you to add an organizational prefix to the beginning of the message to identify your company as the sender.
-
add_info_link
A boolean option that allows you to add a link to your custom company information page to the message.
-
add_opt_out_language
A boolean option that allows you to include a phrase at the end of the message with SMS opt out information.
-
-
-
Smart send time and smart sending
Smart send time and smart sending are robust automations that help you build healthy relationships with your target audience. Both tools leverage customer data to achieve customer-first interactions.
Smart send time
This feature helps you determine the optimal time to email your customers by analyzing trends of when your target audiences are most likely to open your email campaigns.
Note that you must be able to send campaigns to an audience of 12,000 or greater to be eligible for smart send time.
Smart sending
This feature prevents you from sending a recipient too many messages at once. Recipients who have recently received an email or SMS campaign within a set time frame (for example, within 24 hours) will be skipped from receiving the campaign.
Recipients who are skipped from campaigns due to smart sending will not automatically receive the campaign at a later date. Learn more about resending email campaigns.
Send an email campaign
Create an email campaign
To create an email campaign, your request payload for Create Campaign should be formatted like the example below:
{
"data": {
"type": "campaign",
"attributes": {
"name": "Holiday Sale",
"audiences": {
"included": [
"YzykDM"
]
},
"send_strategy": {
"method": "static",
"options_static": {
"datetime": "2024-02-10T00:00:00"
}
},
"campaign-messages": {
"data": [
{
"type": "campaign-message",
"attributes": {
"channel": "email",
"label": "Don't miss our holiday sale!",
"content": {
"subject": "Don't miss our holiday sale!",
"preview_text": "Our holiday sale ends soon! Shop now for up to 70% off!",
...
}
}
}
]
}
}
}
}
Update your campaign
Once the campaign has been created, it will be in “draft” status until it is scheduled to be sent. While your email campaign is in draft, you can update the following:
-
Campaign attributes
Retrieve your campaign ID (Get Campaigns) and call Update Campaign to update campaign attributes such as send and tracking options.
-
Campaign message
Use your campaign ID to fetch the campaign message (Get Campaign Campaign Messages) and call Update Campaign to update your campaign’s message.
Assign a template to an email campaign
After you create an email campaign, you’ll need to add content by assigning a template to the campaign’s message:
- Create a basic HTML template using the Create Template endpoint from our Templates API.
- Assign the template you just created to your campaign’s message using the Assign Campaign Message Template endpoint.
Note that if you do not add a template to your email campaign, you will not be able to schedule a campaign send job.
Schedule a campaign send job
Once you’ve created your email campaign with an assigned template:
- You can estimate the number of campaign recipients with Create Campaign Recipient Estimation Job (see Estimate campaign recipients).
- The campaign is ready to be scheduled in a campaign send job with the Create Campaign Send Job endpoint (see Schedule a campaign send job).
Send an SMS campaign
Create an SMS campaign
To create an SMS campaign, your request payload to Create Campaign should be formatted like the example below:
{
"data": {
"type": "campaign",
"attributes": {
"name": "Holiday Sale",
"audiences": {
"included": [
"YzykDM"
]
},
"send_strategy": {
"method": "static",
"options_static": {
"datetime": "2024-02-13T00:00:00"
}
},
"campaign-messages": {
"data": [
{
"type": "campaign-message",
"attributes": {
"channel": "sms",
"label": "Don't miss our holiday sale!",
"content": {
"body": "Our holiday sale ends soon! Shop now for up to 70% off!"
}
}
}
]
}
}
}
}
Update your campaign
Once the campaign has been created, it will be in “draft” status until it is scheduled to be sent. While your SMS campaign is in draft, you can update the following:
-
Campaign attributes
Retrieve your campaign ID (Get Campaigns) and call Update Campaign to update campaign attributes such as send and tracking options.
-
Campaign message
Use your campaign ID to fetch the campaign message (Get Campaign Campaign Messages) and call Update Campaign to update your campaign’s message.
Schedule a campaign send job
When your SMS campaign is ready to be scheduled:
- Estimate the number of campaign recipients with Create Campaign Recipient Estimation Job (see Estimate campaign recipients).
- Schedule the campaign with the Create Campaign Send Job endpoint (see Schedule a campaign send job).
Estimate campaign recipients
Our Campaigns API allows you to run an estimation of your expected recipient count before sending your campaign with Create Campaign Recipient Estimation Job. Once scheduled, you can use Get Campaign Recipient Estimation Job to check on the job’s status (“queued,” “processing,” “cancelled,” or “complete”) and retrieve the estimated recipient count.
Schedule a campaign send job
When your email or SMS campaign is ready to be sent, you can call Create Campaign Send Job to asynchronously trigger a campaign send. Once scheduled, you can use Get Campaign Send Job to check on the job’s status (“queued,” “processing,” “cancelled,” or “complete”). You can use Update Campaign Send Job to revert the campaign to a draft or cancel the campaign entirely. Note that if you cancel a campaign and would like to resend it, you’ll have to use Create Campaign Clone which will create a clone of the desired campaign in “draft” status, and then schedule a new campaign send job.
Get Campaign(s)
The Get Campaigns endpoint is useful for fetching data about email and SMS campaigns, such as included audiences. Note that for fetching campaigns, you’ll need to include a channel filter for listing either email or SMS campaigns; otherwise you will receive a 400 error. When making a Get Campaign or Get Campaigns request, here’s an example of how it could look:
curl --request GET \
--url 'https://a.klaviyo.com/api/campaigns/?filter=equals(messages.channel, 'email')' \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-12-15'
{
"data": [
{
"type": "campaign",
"id": "01HP76BB2M2R3MSXY1HPGN0ZBS",
"attributes": {
"name": "Holiday Sale",
"status": "Draft",
"archived": false,
"audiences": {
"included": [
"YzykDM"
],
"excluded": []
},
"send_options": {
"use_smart_sending": true,
"ignore_unsubscribes": false
},
"tracking_options": {
"is_add_utm": false,
"utm_params": [],
"is_tracking_clicks": true,
"is_tracking_opens": true
},
"send_strategy": {
"method": "static",
"options_static": {
"datetime": "2024-02-10T00:00:00+00:00",
"is_local": false,
"send_past_recipients_immediately": null
},
"options_throttled": null,
"options_sto": null
},
"created_at": "2024-02-09T15:04:04.445304+00:00",
"scheduled_at": null,
"updated_at": "2024-02-09T15:04:04.534816+00:00",
"send_time": null
},
"relationships": {
"campaign-messages": {
"data": [
{
"type": "campaign-message",
"id": "01HP76BB31VBAJ2JYFMMETTAXN"
}
],
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01HP76BB2M2R3MSXY1HPGN0ZBS/relationships/campaign-messages/",
"related": "https://a.klaviyo.com/api/campaigns/01HP76BB2M2R3MSXY1HPGN0ZBS/campaign-messages/"
}
},
"tags": {
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01HP76BB2M2R3MSXY1HPGN0ZBS/relationships/tags/",
"related": "https://a.klaviyo.com/api/campaigns/01HP76BB2M2R3MSXY1HPGN0ZBS/tags/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01HP76BB2M2R3MSXY1HPGN0ZBS/"
}
},
...
],
"links": {
"self": "https://a.klaviyo.com/api/campaigns/?filter=equals(messages.channel,%27email%27)",
"next": null,
"prev": null
}
}
Querying campaigns
Querying campaigns with the Campaigns API is useful for viewing email and SMS campaign statuses. Check out the supported query parameters below and test them with our latest Postman collection. Note that support for given operators 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 campaigns, e.g., email campaigns with a name containing “sale.” Learn about the filter query parameter. Note that for fetching campaigns, you’ll need to include a channel filter for listing either email or SMS campaigns; otherwise you will receive a 400 error. | GET /api/campaigns?filter=equals(messages.channel, ‘email’) GET /api/campaigns?filter=equals(messages.channel, ‘sms’) GET /api/campaigns?filter=and(equals(messages.channel,’email’),contains(name, ‘sale’) |
fields | Request for only specified campaign data (e.g., audiences). Learn more about sparse fieldsets. | GET /api/campaigns?filter=equals(messages.channel, ‘email’)&fields[campaign]=audiences.included |
include | Include related resources in the response, e.g., campaign messages. Learn about the include query parameter. | GET /api/campaigns?include=campaign-messages GET /api/campaign-messages/:id/?include=template |
Next steps
Using your Klaviyo test account and Postman, try out the following:
- Create a list with at least 1 profile in your Klaviyo test account and copy the list ID.
- Create an email campaign with the Create Campaign endpoint with your list ID in the list of included audiences. Copy the campaign message ID from your created campaign.
- Next, append a template to the campaign message of the campaign you just created. You can create a HTML template with the Create Template endpoint and access its template ID in the response.
- With your campaign message and template IDs, call the Assign Campaign Message Template endpoint. Make the following Get Campaign Message call to view the template related to your campaign message:
GET /api/campaign-messages/:id/?include=template
- With your campaign ID, estimate the campaign’s recipients with Create Campaign Recipient Estimation Job and send your campaign with Create Campaign Send Job.