Campaigns

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.

Trigger Types

When you build a campaign in the dashboard, you choose one of four trigger types:

• Event — starts when a user performs any of the trigger's listed events (for example, one purchase campaign listening on both a PhonePe and a QR payment event). An optional first occurrence mode fires only the first time Flameup has ever seen the event for that person — useful for treating a first login as a signup.
• 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. Only webhook campaigns can be triggered from the API. Calling the trigger endpoint on an event, schedule, or dynamic-schedule campaign returns 400 telling you so — those run from their own triggers only. To start something on demand, build it as a webhook campaign.

Trigger a Campaign

Start a campaign so it runs for its configured audience.

Endpoint: POST /api/v1/campaigns/{campaign_id}/trigger

Headers

Idempotency is opt-in: omit the header and the endpoint behaves exactly as it always has (it sends, and a retry sends again). When a key is honoured, the response echoes it back as idempotency_key, so you can tell an honoured key from an ignored one without guessing.

Request Body

// Generate once per logical trigger, then reuse it for every retry
const idempotencyKey = crypto.randomUUID();

const response = await fetch(
  `https://api.flameup.ai/api/v1/campaigns/${campaignId}/trigger`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`,
      // Reuse this exact key when retrying, so the retry replays
      // the first result instead of re-sending to the whole audience
      'Idempotency-Key': idempotencyKey
    },
    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`);
if (result.audience_truncated) {
  console.warn('Audience truncated at the safety ceiling — matching people were NOT triggered');
}

# Generate once per logical trigger, then reuse it for every retry
idempotency_key = str(uuid.uuid4())

response = requests.post(
    f'https://api.flameup.ai/api/v1/campaigns/{campaign_id}/trigger',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {API_KEY}',
        # Reuse this exact key when retrying
        'Idempotency-Key': idempotency_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" \
  -H "Idempotency-Key: 3f1c9a52-7f2e-4a1b-9c33-2b7e5d0a8e41" \
  -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,
  "idempotency_key": "3f1c9a52-7f2e-4a1b-9c33-2b7e5d0a8e41",
  "message": "Campaign 'Welcome Back' triggered for 42 people"
}

An idempotent replay — the same Idempotency-Key sent again inside the 24-hour window, after the first trigger finished — returns 202 with the original result and no second send:

{
  "success": true,
  "campaign_id": "550e8400e29b41d4a716446655440000",
  "status": "completed",
  "triggered_at": "2024-01-15T10:30:00Z",
  "people_queued": 42,
  "duplicate": true,
  "idempotency_key": "3f1c9a52-7f2e-4a1b-9c33-2b7e5d0a8e41",
  "message": "Campaign 'Welcome Back' was already triggered with this Idempotency-Key for 42 people; it was not sent again"
}

Errors

All flat-shape ({"error": "..."}):

Campaign Status

Campaigns move through the following statuses, all managed from the dashboard: