Send Messages and List Sender IDs — Zexa Messages API

The Messages API lets you send a single message to one recipient on any channel supported by Zexa — SMS, WhatsApp, Telegram, email, or Slack. Each successful request returns a unique message ID and an initial delivery status. Use the message ID to poll for status updates, or set up a webhook to receive delivery events pushed to your server in real time.

Send a Message

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

Request Parameters

string

required

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

string

required

The recipient identifier. Use an E.164-formatted phone number (e.g. +244912345678) for sms, whatsapp, and telegram. Use an email address for email. Use a Slack channel ID or user ID for slack.

string

required

Your registered Sender ID or verified email address. Sender IDs are configured in your Zexa dashboard under Settings → Senders. Use GET /sender-ids to retrieve your registered Sender IDs programmatically.

string

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

string

The email subject line. Applies to the email channel only.

string

An HTML body for email messages. When provided alongside body, the body field serves as the plain-text fallback for email clients that do not render HTML.

object

A WhatsApp-approved message template. Use this instead of body for WhatsApp messages 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 (e.g. ["Maria", "150"]).

string

An ISO 8601 UTC datetime string specifying when to send the message (e.g. 2026-07-01T09:00:00Z). Omit this field to send the message immediately.

Request Examples

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": "Your verification code is 482910. It expires in 10 minutes."
  }'

curl -X POST https://api.zexa.ao/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "to": "maria@example.com",
    "from": "noreply@myapp.ao",
    "subject": "Your order has been confirmed",
    "body": "Hi Maria, your order #10294 has been confirmed and is being prepared.",
    "html": "<p>Hi Maria,</p><p>Your order <strong>#10294</strong> has been confirmed and is being prepared.</p>"
  }'

curl -X POST https://api.zexa.ao/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+244923456789",
    "from": "+244900000001",
    "template": {
      "name": "order_confirmation",
      "language": "pt_BR",
      "variables": ["Maria", "10294", "2026-06-25"]
    }
  }'

import requests

response = requests.post(
    "https://api.zexa.ao/v1/messages",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "sms",
        "to": "+244912345678",
        "from": "ZEXA",
        "body": "Your verification code is 482910. It expires in 10 minutes.",
    },
)

print(response.json())

Response Fields

string

The unique message identifier, prefixed with msg_ (e.g. msg_a1b2c3d4). Use this ID to retrieve the message status later.

string

The initial delivery status of the message. See the Delivery Statuses table below.

string

The channel the message was sent on.

string

The recipient identifier as provided in the request.

string

ISO 8601 UTC timestamp of when the message was created.

Example response (201 Created):

{
  "id": "msg_a1b2c3d4",
  "status": "queued",
  "channel": "sms",
  "to": "+244912345678",
  "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
`422`	`validation_error`	`to` is not in E.164 format, or `from` is not a registered Sender ID
`422`	`insufficient_credits`	Account does not have enough credits to send the message
`429`	`rate_limit_exceeded`	Too many requests — retry after the time indicated in `Retry-After`

Delivery Statuses

Status	Description
`queued`	Message has been accepted and is waiting to be dispatched to the carrier or channel
`sent`	Message has been dispatched to the downstream carrier or channel provider
`delivered`	The carrier or channel confirmed successful delivery to the recipient’s device
`failed`	Delivery failed after all retry attempts; check the `error` field for the reason
`undeliverable`	The destination is permanently unreachable (e.g. invalid number, deactivated account)

Get Message Status

Retrieve the current status of a message by its ID. For production workloads, prefer webhooks over polling to reduce latency and API usage.

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

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

import requests

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

print(response.json())

Example response:

{
  "id": "msg_a1b2c3d4",
  "status": "delivered",
  "channel": "sms",
  "to": "+244912345678",
  "created_at": "2026-06-24T10:00:00Z",
  "delivered_at": "2026-06-24T10:00:05Z"
}

For production applications, use webhooks to receive delivery status updates in real time rather than polling this endpoint. Polling introduces latency and counts against your rate limit.

List Sender IDs

Retrieve all Sender IDs registered on your account. The from field in a send request must match one of these values for SMS, WhatsApp, and Telegram messages.

GET https://api.zexa.ao/v1/sender-ids

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

import requests

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

print(response.json())

Response Fields

array

An array of Sender ID objects registered to your account.

Show Sender ID object fields

string

The unique identifier for this Sender ID record (e.g. sid_abc123).

string

The Sender ID string used in the from field when sending messages (e.g. MYBRAND).

string

The channel this Sender ID is approved for: sms, whatsapp, or telegram.

string

Approval status of the Sender ID: active, pending, or rejected.

string

ISO 8601 UTC timestamp of when the Sender ID was registered.

object

Pagination metadata.

Show meta fields

integer

Total number of Sender IDs registered on the account.

integer

Current page number.

integer

Number of results per page.

Example response:

{
  "data": [
    {
      "id": "sid_abc123",
      "name": "MYBRAND",
      "channel": "sms",
      "status": "active",
      "created_at": "2026-01-15T08:00:00Z"
    },
    {
      "id": "sid_def456",
      "name": "+244900000001",
      "channel": "whatsapp",
      "status": "active",
      "created_at": "2026-02-10T12:30:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 50
  }
}

To register a new Sender ID or manage existing ones in the dashboard, visit Sender IDs. Sender ID registration may require carrier approval and can take up to 72 hours depending on the channel and country.

Overview

Endpoints

Send Messages and List Sender IDs — Zexa Messages API

Send a Message

Request Parameters

Request Examples

Response Fields

Error Scenarios

Delivery Statuses

Get Message Status

List Sender IDs

Response Fields

​Send a Message

​Request Parameters

​Request Examples

​Response Fields

​Error Scenarios

​Delivery Statuses

​Get Message Status

​List Sender IDs

​Response Fields

Send a Message

Request Parameters

Request Examples

Response Fields

Error Scenarios

Delivery Statuses

Get Message Status

List Sender IDs

Response Fields