Send SMS

Endpoint

For sending messages, the base url is:

@bulk_base/api/v1

{info} This endpoint is rate limited to 200 requests per minute per account. Exceeding it returns HTTP 429. Use batches of up to 100 messages per request for higher throughput.

Method

Method URI
POST /send-sms

Request Params

Param Type Description
sender string(required) The Sender ID to send the message with
message string(required) Short Message to be sent
phone string(required) Phone Number to receive message. Should start with country code with 12 characters (e.g 254 for kenya) or 07 with 10 characters for Kenya or 7 with 9 characters for Kenya.
correlator string(optional) A Unique identifier generated by YOUR system, for each message. We forward delivery receipts together with your correlator, to help you identify the message in your system associated with the delivery receipt
link_id string(varies) An initiator identifier that was sent by an originating message, MUST be provided when sending on-demand messages
endpoint string(optional) Your endpoint that we will call to send delivery receipt for a given message. Click HERE for the structure

Sample Request Header

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_TOKEN

{warning} Accept: application/json is required. Without it, an authentication failure returns a 302 redirect to the HTML login page instead of a JSON 401.

Sample Request Body

{
  "sender": "SENDERID",
  "message": "Test API",
  "phone": "07XXXXXXXX",
  "correlator": 1
}

Sample Success Response

StatusCode 200

Content

{
  "status": true,
  "message": "Message successfully queued!",
  "data": {
    "correlator": 2,
    "uniqueId": "unique-string",
    "phone": "254XXXXXXXXX",
    "sms_units": 1
  }    
}

Sending in Batches

This reduces network and resource usage by chunking multiple messages into a single request.

{danger} For batch sending, a maximum of 100 concurrent messages can be sent on a single JSON request body

[
    {
        "sender": "SENDERID",
        "message": "Test API",
        "phone": "07XXXXXXXX",
        "correlator": 1
     },
     {
        "sender": "SENDERID",
        "message": "Test API 2",
        "phone": "07XXXXXXXX",
        "correlator": 2
     }
]

Sample Success Response

StatusCode 200

Content

[
    {
        "status": true,
        "message": "Message successfully queued!",
        "data": {
            "correlator": 1,
            "uniqueId": "unique-string",
            "phone": "254XXXXXXXXX",
            "sms_units": 1
        }
    },
    {
        "status": true,
        "message": "Message successfully queued!",
        "data": {
            "correlator": 2,
            "uniqueId": "unique-string",
            "phone": "254XXXXXXXXX",
            "sms_units": 1
        }
    }
]

> {info} Official SDKs can be obtained HERE.

Also consider having a look at our responses format HERE In order to anticipate all the formats our responses are returned in, and hence a better handling of the same.

Sample Error Response

Code 401

Reason Invalid or Missing Token

Content

{
    "status": false,
    "message": "Unauthenticated."
}

{info} Consider having a look at our responses format HERE, in order to anticipate all the formats our responses are returned in, and hence a better handling of the same.

Send Via URL

Alternatively, you can send messages directly via a GET METHOD.

The endpoint is:

@bulk_base/api/v1/send-basic-sms

Request Params

All the parameters listed here, apply. They should instead be appended as GET parameters

A sample request is:

@bulk_base/api/v1/send-basic-sms?username=testuser&password=testpassword&sender=SENDERID&message=Hello&phone=07XXXXXXXX&correlator=1

{warning} Replace testuser and testpassword with the username and password you use to log into the portal.

{danger} These credentials appear in the URL, so they are recorded in server access logs, browser history and Referer headers, and they grant full access to your portal account. Use the token-authenticated POST /send-sms wherever you can, and treat this endpoint as a convenience for low-volume or legacy integrations only.

Delivery Receipts Structure

All Requested delivery receipts will be delivered via a POST method with the below structure. 

{
     "phone": "254XXXXXXXXX",
     "correlator": 2,
     "uniqueId": "unique-string",
     "deliveryStatus": "DeliveredToTerminal",
     "deliveryTime": "2020-01-01 00:00:00"
 }

Fetching Delivery Status

Delivery receipts are pushed to your endpoint as they arrive. If you would rather ask us, this endpoint returns the current status of messages you have already sent, looked up by the correlator you supplied.

Method URI
POST /fetch-delivery

{info} Rate limited to 2000 requests per minute. A request may carry up to 1000 correlators, and at most 1000 messages are returned.

Request Params

Param Type Description
correlator string(either) A single correlator to look up
correlators array(either) Up to 1000 correlators to look up at once

{warning} Send one of correlator or correlators. Omitting both returns 422.

Sample Request

{
    "correlators": ["order-1001", "order-1002"]
}

Sample Success Response

StatusCode 200

{
    "status": true,
    "count": 2,
    "data": [
        {
            "correlator": "order-1001",
            "phone": "2547XXXXXXXX",
            "delivery_time": "2026-01-01 09:15:22",
            "status": 3,
            "remarks": "DeliveredToTerminal",
            "created_at": "2026-01-01 09:15:02",
            "updated_at": "2026-01-01 09:15:22"
        }
    ]
}

{info} Messages still awaiting a receipt are not returned. Only messages that have reached a settled state appear here, so an absent correlator means either that we are still waiting for the network, or that the correlator is not one of yours.

Nothing Found

StatusCode 404

{
    "status": false,
    "message": "No messages found for the given correlator(s)",
    "count": 0,
    "data": []
}