Batch status
GET /api/messages/batch/{batch_id} - Aggregate status and members of a bulk send.
Endpoint
GET https://sms.esmsafrica.io/api/messages/batch/{batch_id}{batch_id} is the batch_id returned by Send bulk,
the personalised batch API or a
campaign.
Returns status counts and total cost for the whole batch, plus a paginated list
of its member messages.
Authentication
Authorization: Bearer esms_live_your_api_keyQuery parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Zero-based page index (default 0). |
limit | integer | Members per page, 1-200 (default 50). |
Response
{
"batch_id": "b6c2f1e0-1d2c-4a55-9b3f-8e6b0c2d4a11",
"total": 2,
"counts": {
"delivered": 1,
"submitted": 1
},
"cost": 2.4,
"charged": 0.0192,
"charged_currency": "USD",
"page": 0,
"limit": 50,
"messages": [
{
"id": "msg_abc123",
"phone": "+254712345678",
"status": "delivered",
"segments": 1,
"cost": 0.0096,
"error_code": null,
"created_at": "2026-08-14T12:30:00+00:00",
"delivered_at": "2026-08-14T12:30:04+00:00"
}
]
}| Field | Description |
|---|---|
total | Number of messages in the batch. |
counts | Message count per status (delivered, submitted, failed, ...). |
cost / cost_currency | Sum of the member messages' cost (what each one was charged, before refunds), in your wallet currency, like cost on List messages. |
charged / charged_currency | What your wallet paid for this batch (charges minus refunds), in your wallet currency. |
messages[] | Member messages for the requested page, newest first. |
For a batch that belongs to a campaign the response also has campaign_id,
the campaign status, total_recipients, estimated_cost, scheduled_at and
recipients (recipient counts by pending, sending, submitted, failed,
skipped, cancelled); before anything is sent total is 0 and the
campaign fields are still returned.
A batch scheduled with schedule_mode: "scheduled" has no messages until its
send time; until then this endpoint returns "status": "scheduled",
scheduled_at, total_recipients and estimated_cost. An unknown batch_id
returns 404.
Cancel a scheduled batch
POST https://sms.esmsafrica.io/api/messages/batch/{batch_id}/cancelFor a send-bulk batch: cancels a scheduled batch that has not started yet and
refunds the amount charged when it was scheduled. For a campaign batch it
cancels the campaign (recipients not sent yet are never charged) and returns
{"batch_id", "campaign_id", "status": "cancelled", "already_sent"}. Returns
{"batch_id": "...", "status": "cancelled", "refund": {"amount", "currency", "balance_after"}}.
A batch that is already sending, sent or cancelled returns 409 not_cancellable.
Example
curl https://sms.esmsafrica.io/api/messages/batch/b6c2f1e0-1d2c-4a55-9b3f-8e6b0c2d4a11 \
-H "Authorization: Bearer esms_live_your_api_key"List & search messages
GET /api/messages - List, filter and paginate sent messages; GET /api/messages/status for bulk lookups.
Templates
GET/POST/PATCH/DELETE /v1/templates - Saved message templates with merge fields, categories, transactional or promotional type, team or private visibility, and a starter pack.