Campaigns

3 endpoints, each with examples that open in the console prefilled.

All resourcesGuide: Campaigns and statements

POST/api/v1/campaignscampaigns:writeTry in console

Create campaign

Create, schedule, validate, or queue a bulk WhatsApp campaign.

Body parameters

namerequired	string
business_id	string
channelrequired	string
channel_id	string
audiencerequired	object
template_id	string
template_variables	object
mode	string

A campaign dispatches real sends, so (on top of campaigns:write) the key must be authorised to send on the campaign's channel: the umbrella messages:send, or the channel's least-privilege send scope (whatsapp:send / sms:send / email:send).
Set test_mode: true to validate audience counts without queueing.
Pass business_id when creating campaigns for one managed business.
WhatsApp templates are attached to a specific WhatsApp number; pass channel_id to choose the sending number explicitly.
Email campaigns require subject (supports {{n}} variables) and may pass document_source to attach a per-recipient PDF.
A WhatsApp statement run uses a template with a DOCUMENT header and document_source: mode: "url_field" with field_key (a contact custom field holding the https URL for each recipient), mode: "url" for one file to everyone, or mode: "library" for files uploaded in the dashboard (matched to contacts by phone or a custom field in the filename, kept 90 days). filename_template (for example "Statement {{first_name}}.pdf") is required for a DOCUMENT header.
missing_policy decides a recipient with no document: "skip" sends to everyone else and marks that recipient failed with document_missing; "block" refuses a campaign sent now with 400 validation_failed and details.missing_count, and nothing is created.
A scheduled campaign is checked when it fires, not when you create it: the call answers 202 with status "scheduled". If a recipient then has no document under "block", the campaign is closed unsent and a campaign_blocked alert in the workspace names the missing count.
Email campaigns may pass block_content, a block-editor document ({ version: 1, blocks: [...] } with heading/text/button/image/divider/spacer/columns/hero/social/video/html blocks), instead of body; it compiles to branded HTML plus a plain-text part per recipient at send time. Pass either body or block_content, not both.
An email template_id that references a block-designed template carries its design automatically; an inline block_content overrides it.
A starter template's example link (https://example.com, with or without a path) or placeholder image (https://placehold.co/...) left in block_content, or in the design a template_id carries, is refused with 400 validation_failed and details.code: "placeholder_content". Replace them and send again.
Audience accepts { type: "all" }, { type: "list", list_id } or { type: "segment", segment_id }. Pass a segment id to target a smart audience evaluated at send time.
To schedule, set mode: "schedule" and scheduled_at (ISO 8601, at most 90 days ahead); the response status is then scheduled. Sends less than 30s out collapse back to immediate.
Optional fields: description (internal label), preheader (email preview text, supports {{n}}), unique_entries (default true; dedupes recipients that match twice) and engagement_limit (cap the number of recipients).

curl -X POST "https://app.blueticked.com/api/v1/campaigns" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: change-me-per-request-0001" \
  -d '{
  "name": "Launch announcement",
  "business_id": "22222222-2222-4222-9222-222222222222",
  "channel": "whatsapp",
  "channel_id": "11111111-1111-4111-9111-111111111111",
  "audience": {
    "type": "list",
    "list_id": "8f0d0b9a-0000-4000-9000-abcdef123456"
  },
  "template_id": "1f2f3f4f-0000-4000-9000-abcdef123456",
  "template_variables": {
    "1": {
      "source": "first_name"
    },
    "2": {
      "source": "custom",
      "value": "Blueticked"
    }
  },
  "mode": "now"
}'

Response

{
  "campaign_id": "8701a57c-11df-4a63-a950-0f22206d6bdf",
  "status": "active_in_progress",
  "message_count": 240,
  "queued": true,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

GET/api/v1/campaignscampaigns:readTry in console

List campaigns

Fetch campaign status, counters, filters and cursor pagination.

Query parameters

limit

string

Filter by status or channel for operational dashboards.
channel is whatsapp, sms or email. telegram answers 400 validation_failed (details.field channel): Telegram is not a channel customers can use.

curl -X GET "https://app.blueticked.com/api/v1/campaigns?limit=50" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY"

Response

{
  "data": [
    {
      "id": "8701a57c-11df-4a63-a950-0f22206d6bdf",
      "name": "Launch announcement",
      "channel": "whatsapp",
      "status": "active_in_progress",
      "counts": {
        "sent": 240,
        "delivered": 198,
        "failed": 3
      }
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}

GET/api/v1/campaigns/{id}campaigns:readTry in console

Get a campaign

Fetch one campaign's status and delivery counters.

Poll this for progress, or subscribe to message.* webhooks per recipient.

curl -X GET "https://app.blueticked.com/api/v1/campaigns/{id}" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY"

Response

{
  "id": "8701a57c-11df-4a63-a950-0f22206d6bdf",
  "name": "Launch announcement",
  "description": null,
  "channel": "whatsapp",
  "status": "active_in_progress",
  "scheduled_at": null,
  "template_id": "7af1270d-94ba-4661-9fc4-0d3852469977",
  "counts": {
    "sent": 240,
    "delivered": 198,
    "failed": 3,
    "opened": 130,
    "clicked": 12,
    "bounced": 0,
    "complained": 0
  },
  "created_at": "2026-05-22T10:30:00.000Z",
  "updated_at": "2026-05-22T10:35:00.000Z",
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}