Campaigns API: manage audiences and messaging

The Campaigns API lets you programmatically manage the audience and message delivery of evergreen (continuous) campaigns in your BluBash workspace. You can add contacts individually or in bulk with per-contact scheduling, cancel queued messages before they are sent, and inspect message status at any point in the delivery lifecycle.

The Campaigns feature must be enabled on your workspace subscription to use the write endpoints. Read endpoints (list and get messages) may work even without the feature enabled. If you attempt a write operation without the feature, you will receive a 403 Forbidden response.

Base URL

https://api.blubash.io/api/v1/campaigns

Authentication

All requests require your Workspace API Key in the X-API-Key header.

X-API-Key: your_workspace_api_key
Content-Type: application/json

To obtain your API key, go to Settings → API Keys in your workspace admin panel.

Prerequisites

Evergreen campaigns must be created and configured in the BluBash platform before you can use this API. The API covers audience ingestion and message dispatch only.

Create an evergreen campaign in the platform

In the BluBash admin panel, create a new campaign with kind = EVERGREEN.

Configure channel, message, and rate limits

Set up the channel, message template, and rate limit rules for the campaign.

Copy the campaignId

Save the campaign and copy the campaignId shown in the platform. You will use this ID in every API call below.

Add contacts to audience

POST /api/v1/campaigns/:campaignId/audience

Adds one or more contacts to a campaign and defines the send schedule per contact. Each entry in the items array represents one contact and its scheduling configuration.

To add a single contact, send the items array with one element — the endpoint is the same for both single and batch operations.

Request body

string

An IANA timezone name (e.g. America/New_York) applied to all items whose datetime has no UTC offset and no schedule.timezone specified.

array

required

An array of contact + schedule objects. At least one item is required.

Show Item fields

string

The ID of an existing contact in your workspace. Required if identifier is not provided.

string

The contact’s channel identifier (e.g. a WhatsApp phone number). Required if contact_id is not provided. Used to look up or create the contact.

string

Display name for the contact. Used when creating a new contact record.

string

Email address of the contact. Used for lookup and contact creation.

object

Custom field values as a key-value object. Keys must be prefixed with cf_ (e.g. { "cf_plan": "pro" }).

string[]

Tags to apply to the contact. Tags are normalized automatically (trimmed, lowercased, deduplicated) and applied additively — existing tags are not removed.

object

Send schedule for this contact. Defaults to immediate if omitted.

Show Schedule fields

string

required

immediate to send as soon as possible, or absolute to schedule for a specific date and time.

string

ISO 8601 datetime string. Required when type is absolute. If the value includes a UTC offset or Z, the timezone field is ignored. If there is no offset, you must supply schedule.timezone or default_schedule_timezone.

string

IANA timezone name for converting a datetime without a UTC offset to UTC.

Contact resolution

When you provide identifier instead of contact_id, the platform resolves the contact in this order:

Looks up the contact by the channel identifier (e.g. normalized WhatsApp number).
If not found and email is provided, searches by email (case-insensitive).
- If found without a channel identifier, links the identifier to the contact.
- If found with a different channel identifier, returns a 400 error to prevent silent identity merging.
If still not found, creates a new contact using name, email, and identifier.

Scheduling rules

`datetime` format	Behavior
With `Z` or numeric offset (e.g. `+03:00`, `-0500`)	Treated as an absolute instant; `timezone` is ignored
Without offset (e.g. `2026-03-11T09:00:00`)	Requires `schedule.timezone` or `default_schedule_timezone` for UTC conversion

If datetime has no UTC offset and no timezone is provided (either in schedule.timezone or default_schedule_timezone), the request returns a 400 error.

Example request

{
  "default_schedule_timezone": "America/New_York",
  "items": [
    {
      "contact_id": "<CONTACT_ID_1>",
      "schedule": {
        "type": "immediate"
      }
    },
    {
      "identifier": "5511999999999",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "custom_fields": {
        "cf_plan": "pro",
        "cf_source": "api"
      },
      "tags": ["Hot Lead", "VIP Customer"],
      "schedule": {
        "type": "absolute",
        "datetime": "2026-03-10T14:30:00.000Z"
      }
    },
    {
      "contact_id": "<CONTACT_ID_3>",
      "schedule": {
        "type": "absolute",
        "datetime": "2026-03-11T09:00:00",
        "timezone": "America/New_York"
      }
    }
  ]
}

Response fields

array

required

One entry per input item, in the same order as the request.

Show Item fields

string

ID of the campaign message created for this contact.

string

ID of the resolved or created contact.

string | null

The scheduled send time formatted in the IANA timezone or offset that was provided. null for immediate sends.

string | null

The canonical UTC send time (always ends in Z). null for immediate sends.

string | null

The IANA timezone name (e.g. America/New_York) or numeric offset (e.g. -05:00) used for scheduling. null for immediate sends.

Example response

{
  "items": [
    {
      "messageId": "<MESSAGE_ID>",
      "contactId": "<CONTACT_ID_1>",
      "scheduled_at": null,
      "scheduled_at_utc": null,
      "timezone": null
    },
    {
      "messageId": "<MESSAGE_ID>",
      "contactId": "<CONTACT_ID_2>",
      "scheduled_at": "2026-03-10T14:30:00.000Z",
      "scheduled_at_utc": "2026-03-10T14:30:00.000Z",
      "timezone": null
    },
    {
      "messageId": "<MESSAGE_ID>",
      "contactId": "<CONTACT_ID_3>",
      "scheduled_at": "2026-03-11T09:00:00.000-05:00",
      "scheduled_at_utc": "2026-03-11T14:00:00.000Z",
      "timezone": "America/New_York"
    }
  ]
}

Cancel a queued message

POST /api/v1/campaigns/:campaignId/messages/:messageId/cancel

Cancels the delivery of a specific campaign message that is still in the queue. Cancelling one message does not affect any other messages in the campaign.

Only messages with status QUEUED can be cancelled. Messages that are already SENDING, SENT, or FAILED cannot be cancelled.

Response

{
  "id": "<MESSAGE_ID>",
  "status": "CANCELLED"
}

List campaign messages

GET /api/v1/campaigns/:campaignId/messages?limit=50&offset=0

Returns a paginated list of messages for the campaign, each with its current status.

Query parameters

number

default:"50"

Number of results to return per page.

number

default:"0"

Number of results to skip for pagination.

Get a specific message

GET /api/v1/campaigns/:campaignId/messages/:messageId

Returns the details and current status of a single campaign message.

Message statuses

Status	Description
`PENDING`	Awaiting processing
`QUEUED`	Queued for delivery — can be cancelled
`SENDING`	Currently being sent
`SENT`	Delivered successfully
`FAILED`	Delivery failed
`CANCELLED`	Cancelled via API

Recommended workflow

Configure the campaign in the platform

Create an evergreen campaign in the BluBash admin panel and copy the campaignId.

Add contacts to the audience

Call POST /api/v1/campaigns/:campaignId/audience with your items array.

Choose a schedule per contact

Use schedule.type = immediate for instant delivery, or schedule.type = absolute with a datetime for scheduled delivery.

Cancel if needed

If you need to stop a queued message, call POST /api/v1/campaigns/:campaignId/messages/:messageId/cancel.

Monitor message status

Use GET /api/v1/campaigns/:campaignId/messages to inspect delivery status across the campaign.

Code examples

curl -X POST https://api.blubash.io/api/v1/campaigns/{campaignId}/audience \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "identifier": "5511999999999",
        "name": "Jane Smith",
        "tags": ["Hot Lead"],
        "schedule": {
          "type": "immediate"
        }
      }
    ]
  }'

curl -X POST https://api.blubash.io/api/v1/campaigns/{campaignId}/audience \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "default_schedule_timezone": "America/New_York",
    "items": [
      {
        "contact_id": "contact_abc123",
        "schedule": {
          "type": "absolute",
          "datetime": "2026-04-01T10:00:00"
        }
      }
    ]
  }'

curl -X POST https://api.blubash.io/api/v1/campaigns/{campaignId}/audience \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "default_schedule_timezone": "America/New_York",
    "items": [
      {
        "contact_id": "contact_001",
        "schedule": { "type": "immediate" }
      },
      {
        "identifier": "5511888887777",
        "name": "Pedro Lima",
        "custom_fields": {
          "cf_plan": "enterprise"
        },
        "tags": ["VIP Customer", "Hot Lead"],
        "schedule": {
          "type": "absolute",
          "datetime": "2026-04-05T09:00:00",
          "timezone": "America/New_York"
        }
      },
      {
        "contact_id": "contact_003",
        "schedule": {
          "type": "absolute",
          "datetime": "2026-04-06T12:00:00.000Z"
        }
      }
    ]
  }'

curl -X POST https://api.blubash.io/api/v1/campaigns/{campaignId}/messages/{messageId}/cancel \
  -H "X-API-Key: your_api_key"

curl -X GET "https://api.blubash.io/api/v1/campaigns/{campaignId}/messages?limit=50&offset=0" \
  -H "X-API-Key: your_api_key"

Error reference

Status	Message	Cause
`400`	`Each item must provide contact_id or identifier`	An item has neither `contact_id` nor `identifier`
`400`	`Identifier is invalid`	`identifier` is empty or invalid after normalization
`400`	`schedule.timezone (IANA) is required when datetime has no UTC offset`	`datetime` has no offset and no timezone was provided
`400`	`Campaign is not an evergreen campaign`	The `campaignId` belongs to a non-evergreen campaign
`400`	`Cannot add contacts to cancelled or failed campaigns`	Campaign status is `CANCELLED` or `FAILED`
`400`	`Cannot add contacts while the campaign is paused. Resume the campaign first.`	Campaign status is `PAUSED`
`400`	`Contact found by email already has a different identifier for this campaign channel`	Email lookup found a contact with a conflicting channel identifier
`400`	`Contact does not have a valid channel identifier for this campaign channel`	The resolved contact has no valid identifier for the campaign’s channel
`401`	—	Missing or invalid API key
`403`	`Campaigns feature is not available in your current plan`	The Campaigns feature is not enabled on your subscription
`404`	`Campaign not found`	The `campaignId` does not exist in your workspace

Overview

Endpoints

Campaigns API: manage audiences and messaging

Base URL

Authentication

Prerequisites

Add contacts to audience

Request body

Contact resolution

Scheduling rules

Example request

Response fields

Example response

Cancel a queued message

Response

List campaign messages

Query parameters

Get a specific message

Message statuses

Recommended workflow

Code examples

Error reference

​Base URL

​Authentication

​Prerequisites

​Add contacts to audience

​Request body

​Contact resolution

​Scheduling rules

​Example request

​Response fields

​Example response

​Cancel a queued message

​Response

​List campaign messages

​Query parameters

​Get a specific message

​Message statuses

​Recommended workflow

​Code examples

​Error reference

Base URL

Authentication

Prerequisites

Add contacts to audience

Request body

Contact resolution

Scheduling rules

Example request

Response fields

Example response

Cancel a queued message

Response

List campaign messages

Query parameters

Get a specific message

Message statuses

Recommended workflow

Code examples

Error reference