Create and Manage Broadcast Campaigns

The Campaigns API lets you broadcast a message to an entire contact list in a single API call. Campaigns are ideal for promotional announcements, service notifications, and event reminders sent to hundreds or thousands of recipients simultaneously. You can send a campaign immediately or schedule it for a future date and time, and track its delivery progress through the campaign status endpoint.

Create a Campaign

POST https://api.zexa.ao/v1/campaigns

Request Parameters

string

required

A descriptive internal name for the campaign (e.g. Weekend Sale - June 2026). This name is visible only in your dashboard and API responses — recipients do not see it.

string

required

The messaging channel to use. Must be one of: sms, whatsapp, telegram, email, slack.

string

required

The ID of the contact list to target. All active contacts in the list will receive the campaign message. Retrieve list IDs from the Contacts API or your dashboard.

string

required

Your registered Sender ID (for SMS, WhatsApp, Telegram) or verified email address (for email) to use as the message origin. Use GET /sender-ids to list your registered Sender IDs.

string

The plain-text message body. Required unless template is provided.

object

A WhatsApp-approved message template. Use instead of body when sending WhatsApp campaigns that require a pre-approved template.

Show template fields

string

required

The exact name of the approved WhatsApp template.

string

required

The language code for the template (e.g. pt_BR, en_US).

array

An ordered array of string values to substitute into the template’s variable placeholders.

string

An ISO 8601 UTC datetime string specifying when to start sending the campaign (e.g. 2026-07-01T08:00:00Z). Set to null or omit entirely to begin sending immediately after the campaign is created.

Request Example

curl -X POST https://api.zexa.ao/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend Sale",
    "channel": "sms",
    "contact_list_id": "lst_abc123",
    "sender_id": "MYBRAND",
    "body": "Get 20% off this weekend only. Shop now at myapp.ao. Reply STOP to opt out.",
    "scheduled_at": null
  }'

import requests

response = requests.post(
    "https://api.zexa.ao/v1/campaigns",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "Weekend Sale",
        "channel": "sms",
        "contact_list_id": "lst_abc123",
        "sender_id": "MYBRAND",
        "body": "Get 20% off this weekend only. Shop now at myapp.ao. Reply STOP to opt out.",
        "scheduled_at": None,
    },
)

print(response.json())

Response Fields

string

The unique campaign identifier, prefixed with cmp_.

string

The initial campaign status after creation. See Campaign Statuses.

string

The campaign name as provided in the request.

string

The messaging channel used for this campaign.

integer

The total number of contacts targeted by this campaign.

string

ISO 8601 UTC timestamp of when the campaign was created.

Example response (201 Created):

{
  "id": "cmp_xyz789",
  "status": "processing",
  "name": "Weekend Sale",
  "channel": "sms",
  "total_recipients": 850,
  "created_at": "2026-06-24T10:00:00Z"
}

Error Scenarios

Status	Error	Description
`400`	`invalid_request`	Missing required fields or malformed JSON body
`401`	`unauthorized`	API key is missing or invalid
`404`	`not_found`	The specified `contact_list_id` does not exist
`422`	`validation_error`	`sender_id` is not registered, or `body` and `template` are both absent
`422`	`insufficient_credits`	Not enough credits to dispatch the campaign
`429`	`rate_limit_exceeded`	Too many requests — retry after the time indicated in `Retry-After`

Get Campaign Status

Retrieve the current status and delivery statistics for a specific campaign:

GET https://api.zexa.ao/v1/campaigns/{id}

curl https://api.zexa.ao/v1/campaigns/cmp_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.zexa.ao/v1/campaigns/cmp_xyz789",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

print(response.json())

Response Fields

string

The unique campaign identifier, prefixed with cmp_.

string

The campaign name as provided when created.

string

The current campaign status. See the Campaign Statuses table below.

string

The messaging channel used for this campaign.

integer

The total number of contacts targeted by this campaign.

integer

The number of messages confirmed as delivered so far.

integer

The number of messages that failed or were undeliverable.

string

ISO 8601 UTC timestamp of when the campaign was created.

string

ISO 8601 UTC timestamp of when sending began. Null if the campaign has not started yet.

string

ISO 8601 UTC timestamp of when all messages reached a final delivery status. Null if the campaign has not yet completed.

Example response:

{
  "id": "cmp_xyz789",
  "name": "Weekend Sale",
  "status": "completed",
  "channel": "sms",
  "total_recipients": 850,
  "delivered": 812,
  "failed": 38,
  "created_at": "2026-06-24T10:00:00Z",
  "sent_at": "2026-06-24T10:00:12Z",
  "completed_at": "2026-06-24T10:05:47Z"
}

Campaign Statuses

Status	Description
`draft`	Campaign has been created but sending has not started
`scheduled`	Campaign is queued and will begin sending at the specified `scheduled_at` time
`processing`	Messages are actively being dispatched to recipients
`sent`	All messages have been dispatched to carriers; delivery confirmations may still be arriving
`completed`	All messages have reached a final delivery status — the campaign is fully resolved
`failed`	The campaign could not be processed; contact support with the campaign ID

A campaign in processing status cannot be cancelled. Verify your contact list, message body, and schedule before submitting a campaign request.

List Campaigns

Retrieve a paginated list of all campaigns on your account:

GET https://api.zexa.ao/v1/campaigns

integer

Page number (default: 1).

integer

Results per page (default: 50, max: 100).

curl "https://api.zexa.ao/v1/campaigns?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.zexa.ao/v1/campaigns",
    params={"page": 1, "per_page": 20},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

print(response.json())

Example response:

{
  "data": [
    {
      "id": "cmp_xyz789",
      "name": "Weekend Sale",
      "status": "completed",
      "channel": "sms",
      "total_recipients": 850,
      "created_at": "2026-06-24T10:00:00Z"
    }
  ],
  "meta": {
    "total": 14,
    "page": 1,
    "per_page": 20
  }
}

Overview

Endpoints

Create and Manage Broadcast Campaigns — Zexa API

Create a Campaign

Request Parameters

Request Example

Response Fields

Error Scenarios

Get Campaign Status

Response Fields

Campaign Statuses

List Campaigns

​Create a Campaign

​Request Parameters

​Request Example

​Response Fields

​Error Scenarios

​Get Campaign Status

​Response Fields

​Campaign Statuses

​List Campaigns

Create a Campaign

Request Parameters

Request Example

Response Fields

Error Scenarios

Get Campaign Status

Response Fields

Campaign Statuses

List Campaigns