Zexa REST API — Overview, Base URL, and Quick Reference

The Zexa REST API gives you programmatic access to every feature available in the Zexa dashboard — send messages across SMS, WhatsApp, Telegram, email, and Slack; manage contacts and contact lists; launch broadcast campaigns; and track delivery status in real time. Every request follows a consistent JSON-based format, making it straightforward to integrate Zexa into any backend stack or automation workflow.

Base URL

All API requests target the following base URL:

https://api.zexa.ao/v1

Every endpoint path is appended to this base. For example, to check your account’s credit balance:

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

Request Format

Send all request bodies as JSON and include the Content-Type: application/json header on every POST and PATCH request. The API always responds with JSON, regardless of whether the request succeeds or fails.

curl -X POST https://api.zexa.ao/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "sms", "to": "+244912345678", "from": "ZEXA", "body": "Hello!"}'

Authentication

Every request must include your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate API keys in your dashboard under Settings → API Keys. See the Authentication page for full details, key rotation guidance, and security best practices.

Rate Limits

The API enforces per-account rate limits to ensure fair usage across all customers. When you exceed your limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your retry logic — wait a short interval after the first failure, then double the wait time on each subsequent retry before trying again.

The Retry-After response header on a 429 response indicates the number of seconds to wait before retrying.

Error Responses

All errors return a consistent JSON body so you can handle them uniformly in your code:

{
  "error": "invalid_request",
  "message": "The 'to' field must be in E.164 format.",
  "details": { "field": "to", "value": "912345678" },
  "request_id": "req_abc123"
}

Field	Description
`error`	A machine-readable error code string
`message`	A human-readable description of what went wrong
`details`	Additional context, such as the invalid field and value
`request_id`	Unique identifier for the request — include this when contacting support

HTTP Status Codes

The API uses standard HTTP status codes to indicate the outcome of each request.

Code	Meaning
`200`	Success
`201`	Resource created
`204`	Success — no content (e.g. DELETE requests)
`400`	Bad request — malformed syntax or missing required fields
`401`	Unauthorized — API key is missing or invalid
`404`	Resource not found
`422`	Unprocessable entity — request was well-formed but failed validation
`429`	Rate limit exceeded
`500`	Internal server error — try again later

Pagination

All list endpoints support cursor-based pagination via the page and per_page query parameters. The default page size is 50; the maximum is 100.

curl "https://api.zexa.ao/v1/contacts?page=2&per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Every paginated response wraps results in a data array alongside a meta object:

{
  "data": [ ],
  "meta": {
    "total": 340,
    "page": 2,
    "per_page": 25
  }
}

Use meta.total together with per_page to calculate the number of pages and determine when you have retrieved all records.

Endpoint Reference

The table below lists every public endpoint in the Zexa REST API and where it is documented.

Method	Endpoint	Description	Reference
`POST`	`/messages`	Send a single message on any channel	Messages
`GET`	`/messages/{id}`	Retrieve a message and its delivery status	Messages
`GET`	`/sender-ids`	List your registered Sender IDs	Messages
`POST`	`/campaigns`	Create and launch a broadcast campaign	Campaigns
`GET`	`/campaigns`	List all campaigns	Campaigns
`GET`	`/campaigns/{id}`	Retrieve campaign status and delivery stats	Campaigns
`POST`	`/contacts`	Add or import a contact	Contacts
`GET`	`/contacts`	List and search contacts	Contacts
`DELETE`	`/contacts/{id}`	Permanently remove a contact	Contacts
`POST`	`/webhooks`	Register a delivery-status webhook	Webhooks
`GET`	`/credits`	Check your current credit balance	Authentication

Next Steps

Authentication

Generate your API key and learn how to pass it securely in every request.

Send a Message

Send your first message across any supported channel with a single API call.

Campaigns

Broadcast messages to entire contact lists using the Campaigns API.

Contacts

Build and manage your recipient database programmatically.

Webhooks

Receive real-time delivery status events pushed directly to your server.

​Base URL

​Request Format

​Authentication

​Rate Limits

​Error Responses

​HTTP Status Codes

​Pagination

​Endpoint Reference

​Next Steps

Authentication

Send a Message

Campaigns

Contacts

Webhooks

Sender IDs

Base URL

Request Format

Authentication

Rate Limits

Error Responses

HTTP Status Codes

Pagination

Endpoint Reference

Next Steps