eSMS AfricaeSMS Africa
API ReferenceSMS API

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_key

Query parameters

ParameterTypeDescription
pageintegerZero-based page index (default 0).
limitintegerMembers 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"
    }
  ]
}
FieldDescription
totalNumber of messages in the batch.
countsMessage count per status (delivered, submitted, failed, ...).
cost / cost_currencySum of the member messages' cost (what each one was charged, before refunds), in your wallet currency, like cost on List messages.
charged / charged_currencyWhat 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}/cancel

For 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"

On this page