Reach any mobile number across Safaricom, Airtel and Telkom with a single API call. Send to one recipient or thousands; Sozuri queues, routes and delivers each message and pushes a status callback as it completes.

• Request parameters
• Response parameters
• Sample request
• Delivery callback
• Error responses
• Retries & backoff
• Submission rate (TPS)

Request parameters

The request body is JSON (or form-encoded). Every field below sits at the top level.

Postman screenshot:

How sender IDs are matched

Each recipient is sent under the sender ID registered to your project for their network, matched exactly on three things: the name with its capitalisation, the type, and the network. A sender ID registered as Aba transactional on Safaricom reaches Safaricom numbers only. An Airtel number in the same request is sent only if Aba is also registered as transactional on Airtel; AbA transactional or Aba promotional on Airtel do not count.

A recipient on a network where the sender ID is not registered is not sent and not charged. The rest of the request goes ahead, and that recipient comes back with status sender_not_registered and statusCode 24. To send one name to every network, register that exact name, for each type you use, on Safaricom, Airtel and Telkom.

{
    "messageData": {
        "messages": 1
    },
    "recipients": [
        {
            "messageId": "MSGBLK6012A7E8B90A21611835368",
            "to": "2547251642xx",
            "status": "accepted",
            "statusCode": "11",
            "bulkId": "bulk6012a7e8b904e1611835368",
            "messagePart": 1,
            "type": "transactional"
        },
        {
            "messageId": "MSGBLK6012A7E8B90A41611835368",
            "to": "2547326971xx",
            "status": "sender_not_registered",
            "statusCode": "24",
            "bulkId": "bulk6012a7e8b904e1611835368",
            "messagePart": 1,
            "type": "transactional"
        }
    ]
}

messages counts only the messages accepted for sending. On /api/v1/messaging an accepted recipient reads sent rather than accepted; the refused one is the same in both versions.

Response parameters

The response is a JSON object summarising what Sozuri accepted for delivery:

Sample response from Postman:

Sample request

A single request can target one or thousands of recipients. Sozuri responds synchronously with a unique messageId per recipient, then pushes asynchronous status updates to your callback URL as each message progresses.

Required headers

POST /api/v1/messaging
Content-Type: application/json
Authorization: Bearer Your_Project_API_KEY

Sample GET request

https://sozuri.net/api/v1/messaging?apiKey=Your_Project_API_KEY&project=Your_Project_name&channel=sms&from=MySenderID&to=254722xxx675&message=SozuriTestSMS

Sample POST request

POST /api/v1/messaging HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf.......R9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/json

{
    "project": "my project",
    "from": "MySenderID",
    "to": "2547251642xx,2547326971xx",
    "campaign": "Promo Nai",
    "channel": "sms",
    "message": "Test SMS.",
    "type": "promotional"
}

POST /api/v1/messaging HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf45EZAQMJ.......SUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/xml

<request>
    <project>my project</project>
    <from>MySenderID</from>
    <to>2547251642xx,2547326971xx</to>
    <campaign>Promo Nai</campaign>
    <channel>sms</channel>
    <message>Test SMS.</message>
    <type>promotional</type>
</request>

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://sozuri.net/api/v1/messaging",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode([
        "project"  => "my project",
        "from"     => "MySenderID",
        "to"       => "2547251642xx,2547326971xx",
        "campaign" => "Promo Nai",
        "channel"  => "sms",
        "message"  => "Test SMS.",
        "type"     => "promotional",
    ]),
    CURLOPT_HTTPHEADER => [
        "Accept: application/json",
        "Authorization: Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF",
        "Content-Type: application/json",
    ],
));

$response = curl_exec($curl);
curl_close($curl);

echo $response;

const response = await fetch("https://sozuri.net/api/v1/messaging", {
    method: "POST",
    headers: {
        "Authorization": "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF",
        "Content-Type": "application/json",
        "Accept": "application/json"
    },
    body: JSON.stringify({
        project: "my project",
        from: "MySenderID",
        to: "2547251642xx,2547326971xx",
        campaign: "Promo Nai",
        channel: "sms",
        message: "Test SMS.",
        type: "promotional"
    })
});

console.log(await response.json());

require 'uri'
require 'net/http'
require 'json'

uri = URI("https://sozuri.net/api/v1/messaging")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF"
request["Content-Type"]  = "application/json"
request["Accept"]        = "application/json"
request.body = {
  project: "my project",
  from: "MySenderID",
  to: "2547251642xx,2547326971xx",
  campaign: "Promo Nai",
  channel: "sms",
  message: "Test SMS.",
  type: "promotional"
}.to_json

puts http.request(request).body

import requests

response = requests.post(
    "https://sozuri.net/api/v1/messaging",
    headers={
        "Authorization": "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "project": "my project",
        "from": "MySenderID",
        "to": "2547251642xx,2547326971xx",
        "campaign": "Promo Nai",
        "channel": "sms",
        "message": "Test SMS.",
        "type": "promotional",
    },
)
print(response.json())

HttpResponse<String> response = Unirest.post("https://sozuri.net/api/v1/messaging")
    .header("Authorization", "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF")
    .header("Content-Type",  "application/json")
    .header("Accept",        "application/json")
    .body("{\"project\":\"my project\",\"from\":\"MySenderID\",\"to\":\"2547251642xx,2547326971xx\","
        + "\"campaign\":\"Promo Nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"promotional\"}")
    .asString();

var client  = new RestClient("https://sozuri.net/api/v1/messaging");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept",        "application/json");
request.AddHeader("Content-Type",  "application/json");
request.AddHeader("Authorization", "Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF");
request.AddParameter("application/json",
    "{\"project\":\"my project\",\"from\":\"MySenderID\",\"to\":\"2547251642xx,2547326971xx\","
  + "\"campaign\":\"Promo Nai\",\"channel\":\"sms\",\"message\":\"Test SMS.\",\"type\":\"promotional\"}",
    ParameterType.RequestBody);

IRestResponse response = client.Execute(request);

curl -X POST https://sozuri.net/api/v1/messaging \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer LOx5JPdqf0lvf45EZAQMJm85OSUzyxR9X9XDJ4PFxRqVrt9dx83cWiwfTQMF' \
    -d '{
        "project": "my project",
        "from": "MySenderID",
        "to": "2547251642xx,2547326971xx",
        "campaign": "Promo Nai",
        "channel": "sms",
        "message": "Test SMS.",
        "type": "promotional"
    }'

Sample JSON response

{
    "messageData": {
        "messages": 2
    },
    "recipients": [
        {
            "messageId": "MSGBLK6012A7E8B90A21611835368",
            "to": "2547251642xx",
            "status": "accepted",
            "statusCode": "11",
            "bulkId": "bulk6012a7e8b904e1611835368",
            "messagePart": 1,
            "type": "promotional"
        },
        {
            "messageId": "MSGBLK6012A7E8B90A41611835368",
            "to": "2547326971xx",
            "status": "accepted",
            "statusCode": "11",
            "bulkId": "bulk6012a7e8b904e1611835368",
            "messagePart": 1,
            "type": "promotional"
        }
    ]
}

Delivery callback

Sozuri pushes a POST to your configured webhook each time a message changes state. Callbacks may arrive out of order — use the messageId and timestamp to update your records reliably.

Configure your callback URL from your project at Manage API › Callback URLs.

{
    "project": "yourproject_name",
    "messageId": "MSGBLK5F96B6A0CC2EB1603712672",
    "channel": "sms",
    "status": "success",
    "network": "safaricom",
    "type": "bulkDelivery",
    "timestamp": "1603713484"
}

Optional callback authentication

Every delivery callback carries your project’s Auth Key in the body as authKey, plus an X-Sozuri-Signature HMAC header over the raw body. Check either one before you process a callback. Both are generated for you and live under Manage API › Callback URLs › Webhook security — see Verifying authenticity.

Error responses

The most common errors you’ll see on the SMS endpoint. Each response uses the SMS error envelope — messageData.message. A refused request is returned with HTTP 200 and a message starting Error., so check the message as well as the status. Authentication errors (Project not found., Unknown project.) are shared across channels and documented on the Authentication page.

{
    "messageData": {
        "message": "Error. Insufficient balance. Top up and try again."
    }
}

{
    "messageData": {
        "message": "Error. Failure loading group contacts for custom bulk sms. When you include contact parameters like {{fname}} in the message, ensure to ONLY include recipients from existing Contact Groups"
    }
}

{
    "messageData": {
        "message": "Error. Enter the sender ID (from) to send under. It must be a sender ID registered to this project."
    }
}

{
    "messageData": {
        "message": "Error. 'ABA' is not a registered transactional sender ID on this project. Sender IDs are matched exactly, case included, and per network: register 'ABA' as a transactional sender ID on each network you send to."
    }
}

{
    "messageData": {
        "message": "Error. None of these messages was sent: 'Aba' (transactional) is registered on Safaricom only, and every recipient is on Airtel. Nothing was charged."
    }
}

{
    "message": "The given data was invalid.",
    "errors": {
        "type": ["The type field is required."]
    }
}

{
    "messageData": {
        "message": "Error. No valid SMS processing branch found. Please check your request parameters."
    }
}

{
    "messageData": {
        "message": "Error. A system error was encountered. Sozuri support has been notified of the same."
    }
}

Retries & backoff

Network blips and brief routing transients are expected at any scale. Building correct retry behaviour into your client makes the difference between a smooth bulk run and a hand-managed incident. Branch your retry logic on error_code (stable) and retryable — never on the human-readable message text.

Which errors to retry

Recommended backoff curve

Exponential backoff with full jitter (uniform random between 0 and the upper bound). Full jitter prevents thundering-herd retries when many clients all hit a transient failure at the same instant.

Pseudocode

for attempt in 1..5:
    response = POST /api/v1/messaging
    if response.status == 200:
        return success

    if response.body.retryable == false:
        return fail(response.body.error_code)

    wait_ms = retry_after_header_ms
              or min(30000, random(0, 1000 * 2^(attempt - 1)))
    sleep(wait_ms)

return fail("MAX_RETRIES_EXCEEDED", request_id=response.body.id)

Submission rate (TPS)

Sozuri’s aggregate carrier capacity is 400 messages per second across all telcos combined (Safaricom + Airtel + Telkom). This is the platform ceiling; sustained submission above it triggers RATE_LIMITED (HTTP 429).

Within that aggregate, we recommend each project stay under 100 TPS sustained. That leaves headroom for several concurrent high-volume customers running large jobs at the same time, which is the normal pattern we see on the platform.

Pacing recommendations for bulk runs

Probing platform readiness before a scheduled run

Before launching a large bulk run, probe GET /api/v1/status (no authentication required). If the overall status is operational, proceed. If degraded with the relevant carrier still operational, the run will most likely succeed but consider deferring the start by a few minutes. If down, defer the run.

What to do on RATE_LIMITED

The retry/backoff logic above will work, but the better fix is pacing: repeatedly hitting 429 wastes round-trips and increases the chance some messages miss their delivery window. If you are consistently being rate-limited at the recommended pacing, your project may need a higher per-project allowance — contact support@sozuri.net.