Campaigns
Trigger dashboard-created messaging campaigns via the API
Overview
Campaigns are automated messaging workflows that send push notifications to your users based on triggers. Campaigns are created and managed in the Flameup dashboard — including their trigger type, audience, templates, and schedule. The API's role is to trigger a campaign so it runs for its configured audience.
campaigns:trigger to trigger a campaign via the API.Trigger Types
When you build a campaign in the dashboard, you choose one of four trigger types:
- Event — starts when a user performs a specific action (for example, a signup or purchase).
- Webhook — started by calling the trigger endpoint below. Ideal for backend-initiated notifications and third-party integrations.
- Schedule — runs at defined times (for example, a weekly digest).
- Dynamic Schedule — sends relative to a per-user date (for example, a trial-expiration reminder).
The trigger type and its configuration are set in the dashboard. Any campaign can be started on demand from the API using the trigger endpoint — this is the primary path for webhook campaigns and is also useful for testing.
Trigger a Campaign
Start a campaign so it runs for its configured audience.
Endpoint: POST /api/v1/campaigns/{campaign_id}/trigger
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
workspace_id | string | Yes | The workspace that owns the campaign. Must match your API key's workspace. |
trigger_data | object | No | Custom context data passed to the campaign workflow for personalization. |
const response = await fetch(
`https://api.flameup.ai/api/v1/campaigns/${campaignId}/trigger`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
body: JSON.stringify({
workspace_id: WORKSPACE_ID,
// Optional custom data for personalization
trigger_data: {
promo_code: 'SAVE20',
expires: '2024-02-01'
}
})
}
);
const result = await response.json();
console.log(`Triggered for ${result.people_queued} people`);
response = requests.post(
f'https://api.flameup.ai/api/v1/campaigns/{campaign_id}/trigger',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {API_KEY}'
},
json={
'workspace_id': WORKSPACE_ID,
'trigger_data': {
'promo_code': 'SAVE20'
}
}
)
result = response.json()
curl -X POST "https://api.flameup.ai/api/v1/campaigns/{campaign_id}/trigger" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_api_key" \
-d '{
"workspace_id": "your_workspace_id",
"trigger_data": {"promo_code": "SAVE20"}
}'
Response
A successful trigger returns HTTP 202 Accepted:
{
"success": true,
"campaign_id": "550e8400e29b41d4a716446655440000",
"status": "processing",
"triggered_at": "2024-01-15T10:30:00Z",
"people_queued": 42,
"message": "Campaign triggered for audience"
}
| Field | Description |
|---|---|
success | Whether the trigger was accepted |
campaign_id | The campaign that was triggered |
status | processing while the audience is being queued, or completed |
triggered_at | Timestamp when the trigger was accepted |
people_queued | Number of people in the campaign's audience |
message | Human-readable status message |
Campaign Status
Campaigns move through the following statuses, all managed from the dashboard:
Draft
Initial state. Campaign is not active and won't trigger.
Scheduled
Campaign is scheduled to activate at a future time.
Active
Campaign is live and will trigger based on its configuration.
Paused
Campaign is temporarily stopped. Can be resumed.
Completed
Campaign has finished (for one-time campaigns).
Archived
Campaign has been archived and is no longer active.
Failed
Campaign failed due to an error.