Campaigns API: feed ongoing campaigns

The Campaigns API feeds a BluBash Ongoing Campaign from your system. Each contact you send joins the campaign audience and receives the configured message, right away or at the scheduled time. Use it for sign-up welcomes, post-purchase messages, reminders, and lead nurturing.

Campaigns are sent through WhatsApp. An Ongoing Campaign has no fixed list: contacts join over time, manually, through the API, or through the RD Station Marketing integration. In the API, the Ongoing Campaign corresponds to the EVERGREEN type.

Base URL

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

Authentication

Send the workspace API Key in the X-API-Key header. See API introduction →.

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

The Campaigns feature must be included in the workspace plan. Without it, write operations return 403 with the message Campaigns feature is not available in your current plan.

Prerequisites

The API does not create campaigns. It only adds contacts and controls the messages of an Ongoing Campaign that already exists in BluBash.

Create the Ongoing Campaign

In Campaigns, create a campaign of the Ongoing Campaign type. Choose the WhatsApp channel, the message (template or text), and the send limit. See Create a campaign →.

Copy the endpoint

Open the campaign, go to the Integrations tab, and expand Campaign API. Copy the Audience endpoint. The campaignId is the part between /campaigns/ and /audience.

Keep the campaign active

You cannot add contacts to a paused, cancelled, or failed campaign.

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/campaigns/{campaignId}/audience`	Adds contacts to the audience and schedules the send
`POST`	`/api/v1/campaigns/{campaignId}/messages/{messageId}/cancel`	Cancels a queued message
`GET`	`/api/v1/campaigns/{campaignId}/messages`	Lists the campaign messages
`GET`	`/api/v1/campaigns/{campaignId}/messages/{messageId}`	Gets one message

Add contacts to the audience

POST /api/v1/campaigns/{campaignId}/audience

Adds one or more contacts to the campaign and sets the schedule for each one. Each entry in the items array is one contact.

To add a single contact, send items with one element. The same endpoint handles single and batch requests.

Request body

string

IANA time zone (for example, America/New_York) applied to items whose datetime has no UTC offset and that do not set schedule.timezone.

array

required

List of contacts with the schedule for each one. At least one item is required.

Show Item fields

string

ID of an existing contact in the workspace. Required if identifier is not sent.

string

Contact identifier on the campaign channel, such as the WhatsApp number with country and area code (5511999999999). Required if contact_id is not sent. Used to find or create the contact.

string

Contact name. Used when creating a new contact.

string

Contact email. Used to find and to create the contact.

object

Additional fields as key and value. Keys use the cf_ prefix, for example { "cf_plan": "pro" }.

string[]

Tags applied to the contact. BluBash trims spaces, converts to lowercase, and removes duplicates. Tags are added to the existing ones; none are removed.

object

Send schedule for this contact. If omitted, the send is immediate.

Show Schedule fields

string

required

immediate to send as soon as possible or absolute to send at a set date and time.

string

Date and time in ISO 8601. Required when type is absolute. If the value has a UTC offset or Z, timezone is ignored. Without an offset, set schedule.timezone or default_schedule_timezone.

string

IANA time zone used to convert a datetime without an offset to UTC.

Contact resolution

When you send identifier instead of contact_id, BluBash looks for the contact in this order:

By the channel identifier (for example, the normalized WhatsApp number).
If not found and email is present, by email, case-insensitive.
- If the contact found has no identifier on the channel, the identifier is linked to it.
- If the contact found has a different identifier on the channel, the API returns 400, to avoid merging different people.
If still not found, it creates a new contact with name, email, and identifier.

Scheduling rules

`datetime` format	Behavior
With `Z` or a numeric offset (for example, `-03:00` or `+0530`)	Treated as an absolute instant. `timezone` is ignored.
Without offset (for example, `2026-03-11T09:00:00`)	Requires `schedule.timezone` or `default_schedule_timezone` to convert to UTC.

If the datetime has no offset and no time zone is set, the request returns 400.

Request example

{
  "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": "website"
      },
      "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 result per item sent, in the same order as the request.

Show Item fields

string

ID of the campaign message created for the contact.

string

ID of the contact found or created.

string | null

Scheduled time in the given time zone or offset. null for immediate sends.

string | null

Scheduled time in UTC, always ending in Z. null for immediate sends.

string | null

IANA time zone (for example, America/New_York) or numeric offset (for example, -05:00) used for the schedule. null for immediate sends.

Response example

{
  "items": [
    {
      "messageId": "<MESSAGE_ID_1>",
      "contactId": "<CONTACT_ID_1>",
      "scheduled_at": null,
      "scheduled_at_utc": null,
      "timezone": null
    },
    {
      "messageId": "<MESSAGE_ID_2>",
      "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_3>",
      "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 send of a specific message that is still queued. Other campaign messages are not affected.

Only messages with the QUEUED status can be cancelled. SENDING, SENT, or FAILED messages cannot.

Response

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

List campaign messages

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

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

Query parameters

number

default:"50"

Number of results per page.

number

default:"0"

Number of results to skip, for pagination.

Get a message

GET /api/v1/campaigns/{campaignId}/messages/{messageId}

Returns the details and current status of one campaign message.

Message statuses

Status	Description
`PENDING`	Waiting to be processed
`QUEUED`	Queued for sending. Can be cancelled
`SENDING`	Being sent
`SENT`	Sent successfully
`FAILED`	Send failed
`CANCELLED`	Cancelled through the API

Recommended workflow

Set up the campaign in BluBash

Create the Ongoing Campaign and copy the endpoint from the Integrations tab.

Add contacts

Call POST /api/v1/campaigns/{campaignId}/audience with the items array, for example on every new sign-up in your system.

Choose the schedule

Use schedule.type = immediate for an immediate send or schedule.type = absolute with datetime for a scheduled send.

Cancel if needed

To stop a queued message, call POST /api/v1/campaigns/{campaignId}/messages/{messageId}/cancel.

Track delivery

Use GET /api/v1/campaigns/{campaignId}/messages to check the status. In BluBash, contacts added through the API appear with the API source in the campaign details.

When the contact replies to the campaign message, the conversation continues on the WhatsApp channel. The AI agent or your team takes over according to the channel setup.

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_ID>",
        "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_ID_1>",
        "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_ID_3>",
        "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 time zone was set
`400`	`Campaign is not an evergreen campaign`	The `campaignId` belongs to a Single Campaign
`400`	`Cannot add contacts to cancelled or failed campaigns`	The campaign is `CANCELLED` or `FAILED`
`400`	`Cannot add contacts while the campaign is paused. Resume the campaign first.`	The campaign is `PAUSED`
`400`	`Contact found by email already has a different identifier for this campaign channel`	The email belongs to a contact with another identifier on the channel
`400`	`Contact does not have a valid channel identifier for this campaign channel`	The contact has no valid identifier on the campaign channel
`401`	-	Missing or invalid API Key
`403`	`Campaigns feature is not available in your current plan`	Campaigns are not included in the workspace plan
`404`	`Campaign not found`	The `campaignId` does not exist in the workspace

Overview

Endpoints

Campaigns API: feed ongoing campaigns

Base URL

Authentication

Prerequisites

Endpoints

Add contacts to the audience

Request body

Contact resolution

Scheduling rules

Request example

Response fields

Response example

Cancel a queued message

Response

List campaign messages

Query parameters

Get a message

Message statuses

Recommended workflow

Code examples

Error reference

Next steps

Manage campaigns

Channels API

​Base URL

​Authentication

​Prerequisites

​Endpoints

​Add contacts to the audience

​Request body

​Contact resolution

​Scheduling rules

​Request example

​Response fields

​Response example

​Cancel a queued message

​Response

​List campaign messages

​Query parameters

​Get a message

​Message statuses

​Recommended workflow

​Code examples

​Error reference

​Next steps

Manage campaigns

Channels API

Base URL

Authentication

Prerequisites

Endpoints

Add contacts to the audience

Request body

Contact resolution

Scheduling rules

Request example

Response fields

Response example

Cancel a queued message

Response

List campaign messages

Query parameters

Get a message

Message statuses

Recommended workflow

Code examples

Error reference

Next steps