SMS API DOCUMENTATION

The SMS API allows you to send SMS messages from your application using a simple HTTP API.

You can send messages to one or multiple recipients in a single request, use idempotency keys to prevent duplicate requests, and receive delivery reports through a callback URL.

Endpoint

POST /api/v1/sms

The full URL depends on your API environment:

{{BASE_URL}}/api/v1/sms

What you need

Before making requests, you need:

An active account
An SMS API application
An API key
An API secret
A registered sender name
Sufficient account balance

Warning

Keep your API secret private. Do not expose it in frontend JavaScript, mobile applications, public repositories, or other client-side code.

Request limits

Limit	Value
Recipients per request	10,000
Maximum SMS parts	6
Idempotency key retention	60 seconds
Rate limit	300 requests/second per IP

Tips

A single request can contain up to 10,000 recipients. If you need to send to more recipients, split them into multiple requests.

Basic request

A request to send an SMS looks like this:

POST {{BASE_URL}}/api/v1/sms
Content-Type: application/json

X-API-KEY: your-api-key
X-API-SECRET: your-api-secret
Idempotency-Key: unique-request-key

{
  "msisdns": [
    "254701234567",
    "254701234568"
  ],
  "message": "Hello from ",
  "sender_name": ""
}

Response

When the request is accepted, the API queues the SMS and returns a batch ID.

{
  "success": true,
  "message": "SMS queued successfully.",
  "error": null,
  "data": {
    "batch_id": "20bc680b-974d-4f33-affa-273414ebb77f",
    "sms_count": 1,
    "total_recipients": 2,
    "cost_cents": 200,
    "status": "queued"
  }
}

The batch_id identifies the original SMS request and can also be used to associate delivery reports with the request.

Tips

Save the batch_id returned by the API. It identifies the SMS request and is used to associate delivery reports with the original request.

Documentation

Delivery reports

You can configure a callback URL on your SMS API application to receive delivery reports.

The callback contains the batch ID, recipient mobile number and delivery status.

See Delivery Reports for details.