Campaigns API overview

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/or excluded 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 the options_static object to set send configuration options.

      • throttled
        Select this method to send to a certain percentage of recipients. Use the options_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 the options_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 is true 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:

1. Create a basic HTML template using the Create Template endpoint from our Templates API.
2. 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.

Burst API send jobs vs stream send jobs

How you handle your requests can impact the performance of your campaign send job.

Consider the goal of the campaign:

• The campaign is time-sensitive, designed to reach your audience as soon as possible.
• You are sending campaigns based on realtime data and require time between sends to collect and deliver data.

Here’s how each approach might affect campaign sends, based on your campaign's goals:

Burst API Calls in Campaign Sends

The burst method is recommended for one-off campaign sends.

Advantages:

• Efficiency: Sending a large number of campaign messages in a short period can be efficient for specific scenarios where all messages need to be delivered at once.
  • Example: you are offering a promotion to the first 100 customers who purchase XXX item. You want all profiles on the list to receive the campaign as fast as possible to ensure all customers have the same odds of success.
• Simplicity: Implementation is less complex; you can send a batch of messages in one go.
• Predictability: Easier to predict when messages will be sent and received since the send process is concentrated into a single burst.

Disadvantages:

• Rate Limits: API rate limits can be a significant constraint, as sending too many requests in a short period might lead to throttling or blocking. Check the API reference for the endpoint you are using to determine the rate limit.
• Deliverability Issues: Sending a large number of messages at once can increase the likelihood that email and message providers flag your sends as spam.

Stream API Calls in Campaign Sends

The stream method is recommended if you are sending long-term or continuous campaigns.

Advantages:

• Real-Time Delivery: Messages send as soon as the data becomes available, ensuring timely delivery.
• Rate Management: Continuous, paced delivery helps manage and stay within API rate limits.
• Load Distribution: Distributes the server load over time, reducing the risk of overload and downtime.
• Improved Deliverability: Lower risk of a spam flag, as messages are sent in a steady cadence.

Disadvantages:

• Complexity: Implementing a streaming solution may require persistent connections and more sophisticated error handling.
• Latency: There can be slight delays between data availability and message sending, depending on the stream's implementation.

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.

Next steps

Using your Klaviyo test account and Postman, try out the following:

1. Create a list with at least 1 profile in your Klaviyo test account and copy the list ID.
2. 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.
3. 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.
4. 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
5. With your campaign ID, estimate the campaign’s recipients with Create Campaign Recipient Estimation Job and send your campaign with Create Campaign Send Job.

Additional resources

• How to create and send an email campaign
• How to create and send an SMS campaign
• Understanding campaign schedule and send options
• Understanding Smart Sending in Klaviyo
• Understanding smart send time