Quick Start

Code samples

Copy-paste recipes for sending an SMS with the Sozuri API in seven languages, plus raw HTTP. Drop in your project name, API key and one of your sender IDs (exactly as registered, for the recipient’s network and the message type), run it, and the message is queued for delivery straight away.

The SMS endpoint is https://sozuri.net/api/v1/messaging. Use the Run in Postman button or Download collection in the sidebar to try the API without writing a line of code.

Send your first SMS

1. Set the request headers
POST /api/v1/messaging
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
2. (Quick) Sample GET request
https://sozuri.net/api/v1/messaging?apiKey=YOUR_API_KEY&project=My%20Project&from=MySenderID&to=254700000001&campaign=Nai-Promo&message=SozuriTestSMS&type=promotional
3. Sample POST request — pick your language
POST /api/v1/messaging HTTP/1.1
Host: sozuri.net
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

{
    "project": "My Project",
    "from": "MySenderID",
    "to": "254700000001,254733000002",
    "campaign": "Promo Nai",
    "message": "Test SMS.",
    "type": "promotional"
}
<?php

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://sozuri.net/api/v1/messaging",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode([
        "project"  => "My Project",
        "from"     => "MySenderID",
        "to"       => "254700000001,254733000002",
        "campaign" => "Promo Nai",
        "message"  => "Test SMS.",
        "type"     => "promotional",
    ]),
    CURLOPT_HTTPHEADER => [
        "Accept: application/json",
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json",
    ],
]);
echo curl_exec($curl);
curl_close($curl);
const response = await fetch("https://sozuri.net/api/v1/messaging", {
    method: "POST",
    headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Accept": "application/json"
    },
    body: JSON.stringify({
        project: "My Project",
        from: "MySenderID",
        to: "254700000001,254733000002",
        campaign: "Promo Nai",
        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 YOUR_API_KEY"
request["Content-Type"]  = "application/json"
request["Accept"]        = "application/json"
request.body = {
    project: "My Project", from: "MySenderID", to: "254700000001,254733000002",
    campaign: "Promo Nai", 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 YOUR_API_KEY",
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "project": "My Project", "from": "MySenderID",
        "to": "254700000001,254733000002", "campaign": "Promo Nai",
        "message": "Test SMS.", "type": "promotional",
    },
)
print(response.json())
HttpResponse<String> response = Unirest.post("https://sozuri.net/api/v1/messaging")
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type",  "application/json")
    .header("Accept",        "application/json")
    .body("{\"project\":\"My Project\",\"from\":\"MySenderID\",\"to\":\"254700000001,254733000002\","
        + "\"campaign\":\"Promo Nai\",\"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 YOUR_API_KEY");
request.AddParameter("application/json",
    "{\"project\":\"My Project\",\"from\":\"MySenderID\",\"to\":\"254700000001,254733000002\","
  + "\"campaign\":\"Promo Nai\",\"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 YOUR_API_KEY' \
    -d '{
        "project": "My Project",
        "from": "MySenderID",
        "to": "254700000001,254733000002",
        "campaign": "Promo Nai",
        "message": "Test SMS.",
        "type": "promotional"
    }'
4. Expected response
{
    "messageData": { "messages": 2 },
    "recipients": [
        {
            "messageId": "8f3c2a1e9b7d4c6f0a5e2d1b3c4f5a6b7c8d9e0f",
            "to": "254700000001",
            "status": "sent",
            "statusCode": "11",
            "bulkId": "bulk6537f1c2a9b3e4.825912061698123456",
            "messagePart": 1,
            "type": "promotional"
        },
        {
            "messageId": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d",
            "to": "254733000002",
            "status": "sent",
            "statusCode": "11",
            "bulkId": "bulk6537f1c2a9b3e4.825912061698123456",
            "messagePart": 1,
            "type": "promotional"
        }
    ]
}

The same request to /api/v2/messaging answers "status": "accepted". A refused request comes back with HTTP 200 and a messageData.message starting Error. — see Error responses.

Recipes for every channel

This page shows the SMS happy path. For full request/response, multi-language samples, callbacks and edge cases, jump to the channel docs:

Bulk SMS

Send to one or thousands across Safaricom, Airtel and Telkom.

WhatsApp

Choose between a number linked by QR code and the official WhatsApp Business Platform; both send through one API.

Airtime

Airtime top-up is not available at the moment.

Payments

M-Pesa STK Push into your own Paybill or Till.

Contacts

Phonebook + groups for targeted campaigns.

Webhooks

Receive delivery and inbound events in real time.

Have your first message on its way.

Sign up, register a sender ID, copy a snippet, paste your API key, and watch a real SMS arrive.

Get an API key Import Postman collection