Messaging

Campaigns

Create automated messaging campaigns triggered by events, schedules, or API calls

Overview

Campaigns are automated messaging workflows that send push notifications to your users based on triggers. Flameup supports multiple trigger types to cover different use cases.

Required Permissions: campaigns:read to view, campaigns:write to create/modify, campaigns:trigger to manually trigger.

Campaign Object

A campaign in Flameup has the following structure:

{
  "id": "camp_550e8400e29b41d4a716446655440000",
  "workspace_id": "ws_abc123",
  "name": "Welcome Series",
  "status": "active",
  "trigger_type": "event",
  "trigger_config": {
    "event_name": "signed_up",
    "delay_minutes": 5
  },
  "segments": ["all_users"],
  "filters": {},
  "template_id": "tmpl_123",
  "subject": "Welcome!",
  "variables": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

Trigger Types

Flameup supports four types of campaign triggers:

Trigger when a user performs an action

Event-triggered campaigns start when a user performs a specific event. Perfect for:

Welcome messages after signup
Order confirmations
Feature adoption nudges
Re-engagement after inactivity

{
  "trigger_type": "event",
  "trigger_config": {
    "event_name": "signed_up",
    "delay_minutes": 0,
    "properties": {
      "plan": "free"
    }
  }
}

Field	Type	Description
`event_name`	string	The event that triggers the campaign
`delay_minutes`	integer	Wait time in minutes before sending (0 = immediate)
`properties`	object	Event property conditions (optional)

Trigger via API call

Webhook-triggered campaigns are started by calling the trigger endpoint. Perfect for:

Backend-initiated notifications
Third-party integrations
Custom workflow triggers
Testing and debugging

{
  "trigger_type": "webhook",
  "trigger_config": {
    "auth_required": true
  }
}

To trigger:

POST /api/v1/workspaces/{workspace_id}/campaigns/{campaign_id}/trigger

Trigger at specific times

Scheduled campaigns run at defined times. Perfect for:

Daily/weekly digests
Promotional announcements
Holiday campaigns
Regular check-ins

{
  "trigger_type": "schedule",
  "trigger_config": {
    "schedule_type": "cron",
    "cron_expression": "0 9 * * MON",
    "timezone": "America/New_York"
  }
}

Field	Type	Description
`schedule_type`	string	Type of schedule: `cron` or `one_time`
`cron_expression`	string	Cron expression (for cron schedules)
`scheduled_at`	timestamp	Specific time (for one-time schedules)
`timezone`	string	IANA timezone for schedule

Trigger based on user attributes

Dynamic schedules trigger based on user-specific dates. Perfect for:

Birthday messages
Subscription renewal reminders
Trial expiration notices
Anniversary celebrations

{
  "trigger_type": "dynamic_schedule",
  "trigger_config": {
    "attribute": "trial_ends_at",
    "offset_days": -3,
    "time": "10:00",
    "timezone_attribute": "timezone"
  }
}

Field	Type	Description
`attribute`	string	User attribute containing the date
`offset_days`	integer	Days before (-) or after (+) the date
`time`	string	Time to send (HH:MM format)
`timezone_attribute`	string	User attribute for timezone

Create a Campaign

Create a new campaign.

Endpoint: POST /api/v1/workspaces/{workspace_id}/campaigns

const response = await fetch(
  `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/campaigns`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      name: 'Welcome Series',
      trigger_type: 'event',
      trigger_config: {
        event_name: 'signed_up',
        delay_minutes: 5
      },
      template_id: 'tmpl_welcome',
      subject: 'Welcome to {{app_name}}!',
      variables: {
        app_name: 'Acme',
        first_name: '{{first_name}}'
      },
      segments: ['all_users']
    })
  }
);

const campaign = await response.json();

response = requests.post(
    f'https://api.flameup.ai/api/v1/workspaces/{WORKSPACE_ID}/campaigns',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {API_KEY}'
    },
    json={
        'name': 'Welcome Series',
        'trigger_type': 'event',
        'trigger_config': {
            'event_name': 'signed_up',
            'delay_minutes': 5
        },
        'template_id': 'tmpl_welcome',
        'subject': 'Welcome to {{app_name}}!',
        'variables': {
            'app_name': 'Acme',
            'first_name': '{{first_name}}'
        },
        'segments': ['all_users']
    }
)

campaign = response.json()

curl -X POST "https://api.flameup.ai/api/v1/workspaces/{workspace_id}/campaigns" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "name": "Welcome Series",
    "trigger_type": "event",
    "trigger_config": {
      "event_name": "signed_up",
      "delay_minutes": 5
    },
    "template_id": "tmpl_welcome",
    "subject": "Welcome to {{app_name}}!",
    "variables": {"app_name": "Acme"},
    "segments": ["all_users"]
  }'

List Campaigns

Retrieve all campaigns in a workspace.

Endpoint: GET /api/v1/workspaces/{workspace_id}/campaigns

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status: `draft`, `active`, `paused`, `completed`, `archived`, `scheduled`, `failed`
`trigger_type`	string	Filter by trigger type
`limit`	integer	Number of results (default 50)
`offset`	integer	Pagination offset

const response = await fetch(
  `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/campaigns?status=active`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const { campaigns, total } = await response.json();

response = requests.get(
    f'https://api.flameup.ai/api/v1/workspaces/{WORKSPACE_ID}/campaigns',
    headers={'Authorization': f'Bearer {API_KEY}'},
    params={'status': 'active'}
)

data = response.json()
campaigns = data['campaigns']

Get Campaign Details

Retrieve a specific campaign.

Endpoint: GET /api/v1/workspaces/{workspace_id}/campaigns/{campaign_id}

const response = await fetch(
  `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/campaigns/${campaignId}`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const campaign = await response.json();

Update a Campaign

Modify an existing campaign.

Endpoint: PUT /api/v1/workspaces/{workspace_id}/campaigns/{campaign_id}

const response = await fetch(
  `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/campaigns/${campaignId}`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      name: 'Welcome Series v2',
      trigger_config: {
        event_name: 'signed_up',
        delay_minutes: 10
      }
    })
  }
);

curl -X PUT "https://api.flameup.ai/api/v1/workspaces/{workspace_id}/campaigns/{campaign_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{"name": "Welcome Series v2"}'

Campaign Status

Campaigns have the following statuses:

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.

Activate a Campaign

Update the campaign status to active using the PUT endpoint:

await fetch(
  `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/campaigns/${campaignId}`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ status: 'active' })
  }
);

Pause a Campaign

Update the campaign status to paused using the PUT endpoint:

await fetch(
  `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/campaigns/${campaignId}`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ status: 'paused' })
  }
);

Trigger a Campaign Manually

For webhook-triggered campaigns, or to test any campaign:

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

const response = await fetch(
  `https://api.flameup.ai/api/v1/workspaces/${WORKSPACE_ID}/campaigns/${campaignId}/trigger`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      // Target specific users
      user_ids: ['user_123', 'user_456'],

      // Or use filters
      filters: {
        plan: 'premium'
      },

      // Custom data for personalization
      data: {
        promo_code: 'SAVE20',
        expires: '2024-02-01'
      }
    })
  }
);

const result = await response.json();
console.log(`Triggered for ${result.people_queued} users`);

response = requests.post(
    f'https://api.flameup.ai/api/v1/workspaces/{WORKSPACE_ID}/campaigns/{campaign_id}/trigger',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {API_KEY}'
    },
    json={
        'user_ids': ['user_123', 'user_456'],
        'data': {
            'promo_code': 'SAVE20'
        }
    }
)

result = response.json()

curl -X POST "https://api.flameup.ai/api/v1/workspaces/{workspace_id}/campaigns/{campaign_id}/trigger" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "user_ids": ["user_123", "user_456"],
    "data": {"promo_code": "SAVE20"}
  }'

Templates & Variables

Campaigns reference templates by template_id and use variables for personalization with Handlebars-style syntax:

{
  "template_id": "tmpl_order_shipped",
  "subject": "Hi {{first_name}}!",
  "variables": {
    "first_name": "{{first_name}}",
    "order_id": "{{order_id}}"
  }
}

Available Variables

Variable	Source	Description
`{{first_name}}`	Person	User's first name
`{{last_name}}`	Person	User's last name
`{{email}}`	Person	User's email
`{{attributes.*}}`	Person	Any user attribute
`{{event.*}}`	Event	Event properties (event triggers)
`{{data.*}}`	Trigger	Custom trigger data

Fallback Values

Provide fallbacks for missing data:

{{first_name|default:"there"}}

Campaign Examples

Send a welcome message 5 minutes after signup:

{
  "name": "Welcome Series",
  "trigger_type": "event",
  "trigger_config": {
    "event_name": "signed_up",
    "delay_minutes": 5
  },
  "template_id": "tmpl_welcome",
  "subject": "Welcome to Acme!",
  "variables": {
    "first_name": "{{first_name}}"
  },
  "segments": ["all_users"]
}

Delete a Campaign

Endpoint: DELETE /api/v1/workspaces/{workspace_id}/campaigns/{campaign_id}

Deleting a campaign is permanent. Consider pausing instead if you may want to resume later.

curl -X DELETE "https://api.flameup.ai/api/v1/workspaces/{workspace_id}/campaigns/{campaign_id}" \
  -H "Authorization: Bearer your_api_key"

Was this page helpful?

Built with Documentation.AI

Last updated today