SMS API Documentation

Base URL

https://api.kenyasms.co.ke/v1

Authentication

All requests require an API key passed in the X-API-Key header.

X-API-Key: your_api_key_here

Send Single SMS

POST /v1/sms/send

{
  "to": "0712345678",
  "message": "Hello from KenyaSMS!",
  "sender_id": "MYBRAND"
}

Response

{
  "success": true,
  "message_id": "msg_abc123",
  "status": "queued",
  "cost": 0.45,
  "currency": "KES"
}

Send Bulk SMS

POST /v1/sms/bulk

{
  "sender_id": "MYBRAND",
  "message": "Your monthly statement is ready.",
  "recipients": ["0712345678", "0723456789", "0734567890"]
}

Personalized SMS (Mail Merge)

POST /v1/sms/personalized

{
  "sender_id": "MYBRAND",
  "messages": [
    {"to": "0712345678", "message": "Hi John, balance: KES 5,000"},
    {"to": "0723456789", "message": "Hi Jane, balance: KES 12,300"}
  ]
}

Check Delivery Status

GET /v1/sms/status/{message_id}

Calculate Cost

POST /v1/sms/calculate

{
  "message": "Your message text here",
  "recipients_count": 1000,
  "message_type": "promotional"
}

Account Balance

GET /v1/account/balance

Response:
{
  "balance": 15000.50,
  "currency": "KES"
}

Code Examples

PHP

$ch = curl_init('https://api.kenyasms.co.ke/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: your_api_key',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '0712345678',
        'message' => 'Hello from KenyaSMS!',
        'sender_id' => 'MYBRAND',
    ]),
]);
$response = curl_exec($ch);

Python

import requests

response = requests.post(
    'https://api.kenyasms.co.ke/v1/sms/send',
    headers={'X-API-Key': 'your_api_key'},
    json={
        'to': '0712345678',
        'message': 'Hello from KenyaSMS!',
        'sender_id': 'MYBRAND',
    }
)
print(response.json())

Node.js

const response = await fetch('https://api.kenyasms.co.ke/v1/sms/send', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '0712345678',
    message: 'Hello from KenyaSMS!',
    sender_id: 'MYBRAND',
  }),
});
const data = await response.json();

Rate Limits

Tier	Requests/Second
Bronze	10 TPS
Silver	25 TPS
Gold	50 TPS
Diamond	100 TPS

Error Codes

Code	Description
401	Invalid or missing API key
402	Insufficient balance
422	Validation error (invalid phone, empty message)
429	Rate limit exceeded