How To Set Up An API Triggered Broadcast

How To Set Up An API Triggered Broadcast

Remember that API triggered broadcasts are a little bit different from segment triggered and event triggered campaigns. The campaign isn't triggered by a user's membership in a specific segment; you define the recipients, but the campaign is triggered to the people who meet those conditions when your API call is received by

Getting started

To create a new API triggered broadcast, click Triggered in the left-hand menu, and press the Create Campaign button:

Campaign Setup - Create a Triggered Campaign

Then, choose the API Triggered Broadcast option.

Step 1: Define recipients

One thing you'll note here is that defining recipients is optional for this campaign type. You can specify who should receive your broadcast here, but you can also do this in your API call.

The API call is more dynamic, and overrides whatever you set here. However, if you know that your broadcast should go to the same segment(s) each time, feel free to set your conditions here.

Define recipients ia API or segment/attribute conditions

Here, you can add one or more segment or attribute conditions. Using AND means that your users need to match all the segments before they will receive messages. OR means that it's enough for a user to be part of any one of the segments in order to match.

Step 2: Add actions to the workflow

API Triggered Broadcasts are designed to perform all actions in the workflow at the time of the broadcast. As such, Delays and Time Windows cannot be added to the workflow of an API Triggered Broadcast.

You can add Email, Slack, Twilio SMS and Urban Airship Push messages as well as Attribute Updates and Webhooks.


When you choose to add an email, it will be added to your workflow. Give it a name and press "Save Email" to confirm your choice. (If you change your mind and you no longer want to add an email action or if you pressed the button by mistake, you can always cancel or delete it.)

Workflow - Email Options

Each email comes with a variety of options:

  • Email behavior - Choose between "Queue Draft”, "Send Automatically” and "Don’t Send”. Any email set on "Don’t send” will be skipped. "Queue Draft" is the default; this means that the email draft will be generated, but not sent until you approve it.
  • Add Content - Create and personalize your message in the composer. More on this below.
  • Add A/B test - Split the email into two different versions to see which one performs better
  • Delete Email - Remove the email from the workflow. Be careful! Once deleted, an email cannot be recovered.
  • Close - Returns you to the Workflow view, so that you can add additional actions or modify existing ones.

Changing the default sending behavior:

The default behaviour is "Tracking enabled and don't send to unsubscribed":

Unsubscribe button

To change this, click Edit, choose the options best suited for you and press "Update”:

Unsubscribe button

These settings are on a per-email basis. We recommend leaving this on the default setting so that you don't send emails to people who have unsubscribed.


A webhook action allows you to connect to just about any public API. We have detailed documentation on webhook actions if you'd like to add one of these. Push Notifications

This action allows you to send push notifications directly from We have guidance on how to add and compose them:

Slack Messages, Twilio SMS, or Urban Airship Push

Similar to webhook actions, these options allow you to quickly connect to Slack, Twilio, or Urban Airship. Before you can add them from your workflow, you'll need to enable them for each workspace. Once enabled, just select one from the actions dropdown to add it. If you need more details, we have in-depth guides for each:

Action Conditions

Action Conditions are action-specific checks, and for API triggered broadcasts, they're checked against the customer just before a message is sent or drafted. For example, you might only want to send an SMS if a user has a phone number set. If an action condition isn't met, the message is skipped.

To add an action condition to a message, open the message in the workflow and you'll see the button to add action conditions:

Adding Action Conditions in API triggered broadcast

This will open up the conditions editor. You can add or edit up to four conditions, based on customer attributes or segment membership.

Note that you cannot add delays and time windows for API triggered broadcasts.

Moving actions

If there's more than one item in your workflow, you have the option to choose exactly where to add any further actions by clicking the desired "ADD [ELEMENT] HERE" area.

Workflow - Add email here

Move elements from one position to another by pressing the "Move" button and choosing a new workflow area.

Workflow - Move email here

Using customer and trigger data in your messages

You can then create your email in the Composer, and use all of its features— including all your customer data! You can do this in a few ways:

  • Using Liquid: all of your customers' attributes are available to you here.
  • Using trigger data: When you trigger this campaign, you can include a JSON data payload. To preview what that data would look like, you can copy and paste it into the composer.

Data preview for API Triggered Broadcast

If you've triggered this broadcast before, previous data payloads will be available to you for preview, but you'll have to send the data again if you want to use it in the messages.

Step 3: Select a conversion goal

After setting up your messages, you can add a conversion goal:

Goal page

Conversion tracking allows you to track the success of your emails, SMS, and push notifications, so you'll want to choose a relevant segment (a person using a feature, signing up for a paid plan, no longer being inactive, etc.). If a user enters/exits that segment after being sent the message, they'll be tracked as a conversion.

Learn more about conversions.

Step 4: Review and activate your broadcast

Review is the final step of the broadcast creation process. It's an overview of the entire setup, so take a look to make sure you haven't forgotten anything. "Needs fixing" labels is applied to anything that is preventing you from moving forward.

This API Triggered Broadcast needs fixing

If everything looks right, you can activate your broadcast!

Curious about what happens when recipients or messages are modified for active broadcasts? We have answers.

Step 5: Sending Information

You'll be brought to this page as soon as your broadcast is activated, and it contains all the information you need to get sending. To do this, you'll need to trigger via our API.

For more comprehensive information on structuring your API calls, check out our API documentation.


Your campaign has been activated. Now, you'll be able to start sending.

Was this article helpful?