API triggered campaigns

Template campaigns executed by the external API

Template campaigns can be created using the UI on the platform, but triggered later via the Campaign Execute API.

You can find API-triggered campaigns on the Create Campaign page (Campaigns > Create campaign > Single-stage > Triggered > API-triggered), and build them like any regular campaign.


Step on the campaign creation wizard showing the different types of triggered campaigns.

Any available outbound channel may be triggered by an API execution and multiple channels can be used in your template if required.

These messages are typically transactional with a mixture of fixed content in the template and variables sent via API. Use the double curly brace syntax to add variables, eg. {{variable_name}}. Further information can be found in the guide on dynamic content.


Once the template is configured with the channel, content, variables, etc., make the campaign live with the Review & Launch button like any other campaign. The campaign will be listed in Campaigns > Existing campaigns > Live. Here you will find the campaign ID, which is needed to trigger the campaign using the Campaign Execute API.


Send transactional emails or SMS

If you want to use the API to send transactional emails or SMS, the principles would be the same in both cases. First, you create a template API campaign with necessary placeholders for dynamically changing content. To illustrate how this is used below is a classic transactional example of sending a gate update to an airline customer via an SMS message:

In this example, you would then use the campaign execute method to trigger the campaign when gate information becomes available on the backend. App token and campaign ID are used to target the right campaign in your project, and the params are set for the flight information (flight_num, time and gate_num). Finally to target users who are checked in for the flight we are adding a condition in the segment tab to target users who are on the list for the flight by targeting by user ID and providing an array of customer IDs to target.

curl --request POST \
  --url https://external-api.xtremepush.com/api/external/execute/campaign \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "apptoken": "APP_TOKEN",
    "id": "CAMPAIGN_ID",
    "params": {
      "flight_num": "EI105", 
      "time": "10:30",
      "gate_num": "B100" 
    "target_by": "user_id",
    "target": ["USER_ID"]

If you want to construct the full content of the message on your backend you can just place single params in the various content fields on the template from the Xtremepush platform, such as in the example below, where {{from}} is included in the from name field to dynamically generate the from name and {{text}} in the text field:


From names

When populating an SMS from name dynamically, remember that from names must be between 3 and 11 characters long. For more details review our SMS settings guide.

The same principle outlined above for SMS can be applied to email, the main difference with email is the potential to have more complex content in the body of the email such as a list of personalised product recommendations with images, etc. There are examples of the more dynamic content that can be added to emails using this approach in the following user guides:

Webhooks for deliveries and responses

For API-based campaigns, you can post back delivery and click-through info to your own endpoints for tracking purposes, if necessary. This will work for both the template and trigger and create and send patterns. See details about how to configure these in the API campaign model properties.