Send an API-triggered campaign

An API-triggered campaign has no schedule in the console. Your server starts it with one call and decides when it goes out. It sends to the audience saved on the campaign, or to recipients the call names. Use it when your own system decides when a message goes out and what it says.

For one-to-one messages the customer is waiting for, such as OTPs, use a transactional endpoint instead.

Before you start

• A published template.
• A server key that is allowed to manage campaigns. See API keys.

Steps

1. Click New campaign and enter a Name.
2. Choose the Channel, and set Campaign type to API triggered.

3. Optionally set the Audience to send to by default. A trigger call that names no audience uses it. Then click Next: Content and pick the template.
4. On Delivery, there is no schedule. The step shows the same Trigger and Repeats and exit settings as an event-triggered campaign. Your server starts this campaign, so you can leave Trigger event empty.

5. Optionally pin a provider, then continue to Limits, Goals and Review. Click Save & publish.

What happens next

The campaign is ready to be fired from your server with its campaign id and a server key. Each firing becomes a run you can follow in Read a campaign's results. Frequency caps and quiet hours still apply unless you untick them under Limits.

Fire it from your server

POST /v1/campaigns/{campaignIdOrSlug}/trigger

The path takes the campaign's id or its slug (for example market-open-alert). Authenticate with a server key that has the campaigns.create_manage scope.

{
  "variables": { "nifty": 24850.5, "change": "+0.4%" },
  "idempotencyKey": "market-open-2026-10-21"
}

• audience is optional. Leave it out to send to the audience saved on the campaign (set it on the Audience step). To override it for one call, give exactly one of allUsers, segmentId, or externalIds (up to 5,000 customer ids). Unknown ids are skipped. The campaign's exclusion rule applies to allUsers and segmentId, not to a list you name. A call with no audience on a campaign with none saved is rejected with AUDIENCE_REQUIRED.
• variables are read by the template as {{campaign.nifty}} (also {{event.nifty}}). A value the call leaves out fails that send unless the placeholder has a default, such as {{campaign.change | default:"flat"}}. Values are inserted as plain text, so send numbers already formatted the way you want them shown.
• idempotencyKey makes a retry safe. The same key within 24 hours sends nothing more and returns deduplicated: true.

The call returns 202 straight away; the run is built in the background.