Introduction

SayaSMS API Reference

The SayaSMS API is a RESTful web service that lets you send and receive SMS messages programmatically across Africa. Our base URL is:

https://api.sms.sayaradius.co.ke/v1

Authentication

All API requests must include your API key in the Authorization header using Bearer token format.

🔑 API Keys
Generate your API keys from the Dashboard → API Keys section. Keep your live key secret — never expose it client-side.

# Include your API key in all requests
curl https://api.sms.sayaradius.co.ke/v1/messages \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json"

Send an SMS

Send a single SMS message to one or more recipients.

POST /v1/messages

Request body

to array Required Array of E.164 phone numbers e.g. ["+254712345678"]

from string Required Sender ID (max 11 alphanumeric or 15 numeric chars)

body string Required Message content (max 918 chars for multi-part SMS)

callback_url string Optional Webhook URL to receive delivery reports

scheduled_at string Optional ISO 8601 datetime to schedule message delivery

curl -X POST https://api.sms.sayaradius.co.ke/v1/messages \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["+254712345678", "+254722111222"],
    "from": "SAYARADIUS",
    "body": "Hello! Your verification code is 834921.",
    "callback_url": "https://yourapp.com/webhooks/sms"
  }'

Response

200 OK

{
  "status": "queued",
  "message_id": "msg_01HX4ZQ9GKD2VP7C9XR3MNBVT4",
  "recipients": [
    {
      "number": "+254712345678",
      "status": "queued",
      "cost": "KES 0.90",
      "message_id": "msg_01HX4ZQ9GKD2VP7C9XR3MNBVT4_1"
    },
    {
      "number": "+254722111222",
      "status": "queued",
      "cost": "KES 0.90",
      "message_id": "msg_01HX4ZQ9GKD2VP7C9XR3MNBVT4_2"
    }
  ],
  "total_cost": "KES 1.80",
  "created_at": "2026-03-13T14:30:00.000Z"
}

Bulk SMS

Send personalized messages to thousands of recipients at once. Supports template variables for personalization.

POST /v1/messages/bulk

curl -X POST https://api.sms.sayaradius.co.ke/v1/messages/bulk \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "MYSHOP",
    "messages": [
      {
        "to": "+254712345678",
        "body": "Hi Grace, your order #KE2041 is ready!"
      },
      {
        "to": "+254722111222",
        "body": "Hi Peter, your order #KE2042 has shipped."
      }
    ],
    "callback_url": "https://yourapp.com/webhooks/sms"
  }'

Webhooks & Delivery Reports

SayaSMS sends an HTTP POST to your callback_url when a message status changes. Configure your endpoint in the Dashboard or per-request.

⚡ Tip
Your webhook endpoint must return a 200 OK within 10 seconds. SayaSMS will retry up to 3 times on failure with exponential backoff.

Delivery report payload

POST · Your webhook URL

{
  "event": "message.delivered",
  "message_id": "msg_01HX4ZQ9GKD2VP7C9XR3MNBVT4_1",
  "to": "+254712345678",
  "status": "delivered",
  "network": "Safaricom",
  "delivery_time": "2026-03-13T14:30:02.489Z",
  "latency_ms": 2489
}

Event types

message.queued Message accepted and queued for delivery

message.sent Message submitted to carrier network

message.delivered Message confirmed delivered to handset

message.failed Message delivery failed (includes reason)

Account Balance

Retrieve your current credit balance.

GET /v1/account/balance

200 OK

{
  "balance": 4280,
  "currency": "KES",
  "sms_credits": 4280,
  "account_id": "acc_01HX4ZQ9GK...",
  "updated_at": "2026-03-13T14:30:00.000Z"
}

SDKs & Libraries

Official client libraries to get you started quickly.

JS

Node.js npm install sayasms

Py

Python pip install sayasms

PHP

PHP composer require sayasms/sayasms

☕

Java Maven: com.sayasms:sayasms-java