Skip to main content
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

​
name
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.
​
channel
string
required
The messaging channel to use. Must be one of: sms, whatsapp, telegram, email, slack.
​
contact_list_id
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.
​
sender_id
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.
​
body
string
The plain-text message body. Required unless template is provided.
​
template
object
A WhatsApp-approved message template. Use instead of body when sending WhatsApp campaigns that require a pre-approved template.
​
scheduled_at
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
  }'

​
Response Fields

​
id
string
The unique campaign identifier, prefixed with cmp_.
​
status
string
The initial campaign status after creation. See Campaign Statuses.
​
name
string
The campaign name as provided in the request.
​
channel
string
The messaging channel used for this campaign.
​
total_recipients
integer
The total number of contacts targeted by this campaign.
​
created_at
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

StatusErrorDescription
400invalid_requestMissing required fields or malformed JSON body
401unauthorizedAPI key is missing or invalid
404not_foundThe specified contact_list_id does not exist
422validation_errorsender_id is not registered, or body and template are both absent
422insufficient_creditsNot enough credits to dispatch the campaign
429rate_limit_exceededToo 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"

​
Response Fields

​
id
string
The unique campaign identifier, prefixed with cmp_.
​
name
string
The campaign name as provided when created.
​
status
string
The current campaign status. See the Campaign Statuses table below.
​
channel
string
The messaging channel used for this campaign.
​
total_recipients
integer
The total number of contacts targeted by this campaign.
​
delivered
integer
The number of messages confirmed as delivered so far.
​
failed
integer
The number of messages that failed or were undeliverable.
​
created_at
string
ISO 8601 UTC timestamp of when the campaign was created.
​
sent_at
string
ISO 8601 UTC timestamp of when sending began. Null if the campaign has not started yet.
​
completed_at
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

StatusDescription
draftCampaign has been created but sending has not started
scheduledCampaign is queued and will begin sending at the specified scheduled_at time
processingMessages are actively being dispatched to recipients
sentAll messages have been dispatched to carriers; delivery confirmations may still be arriving
completedAll messages have reached a final delivery status — the campaign is fully resolved
failedThe 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
​
page
integer
Page number (default: 1).
​
per_page
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"
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
  }
}