Integrate SMS capabilities directly into your applications with our robust, well-documented API. Build powerful communication workflows with just a few lines of code.
The SMSALES API allows you to send SMS messages, check your account balance, and receive delivery reports programmatically. Our API follows REST principles and returns JSON responses.
The SMSALES API only accepts Content-Type: application/json and Accept:
application/json headers for all requests.
All API requests should be made to:
https://api.smsales.co.ke/api/v1/
SMSALES API uses OAuth 2.0 Authorization Grant Type with Basic Authentication to generate access tokens.
/token
| Header | Value | Description |
|---|---|---|
| Authorization | Basic YOUR_ACCOUNT_API_TOKEN | Base64 encoded account API token |
| Content-Type | application/json | Required for all requests |
| Accept | application/json | Required for all requests |
curl -X GET "https://api.smsales.co.ke/api/v1/token" \
-H "Authorization: Basic YOUR_ACCOUNT_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"const axios = require('axios');
const options = {
method: 'GET',
url: 'https://api.smsales.co.ke/api/v1/token',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Basic YOUR_ACCOUNT_API_TOKEN'
}
};<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.smsales.co.ke/api/v1/token',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Basic YOUR_ACCOUNT_API_TOKEN'
),
));
?>{
"data": {
"Token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"TokenType": "Bearer",
"Expires": 3600
}
}Send SMS messages to one or multiple recipients, check balances, and view sent messages.
/sms/send
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer YOUR_ACCESS_TOKEN | Access token from /token endpoint |
| Content-Type | application/json | Required for all requests |
| Accept | application/json | Required for all requests |
| Parameter | Type | Required | Description |
|---|---|---|---|
| api_sender | String | Yes | Your registered API Sender ID (check your sender ID list) |
| message | String | Yes | The SMS message content |
| phone_numbers | Array | Yes | Array of phone numbers in format ["2547XXXXXXXX","2540XXXXXXXX"] |
| scheduled_at | String | No | Scheduled time in format "Y-m-d H:i:s" |
| callback_url | String | No | URL to receive delivery reports (POST request) |
curl -X POST "https://api.smsales.co.ke/api/v1/sms/send" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"api_sender": "smsales",
"message": "Hello from SMSALES!",
"phone_numbers": ["2547XXXXXXXX","2540XXXXXXXX"],
"callback_url": "https://yourdomain.com/sms-callback"
}'const axios = require('axios');
const options = {
method: 'POST',
url: 'https://api.smsales.co.ke/api/v1/sms/send',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
},
data: {
"api_sender": "smsales",
"message": "Hello from SMSALES!",
"phone_numbers": ["2547XXXXXXXX","2540XXXXXXXX"]
}
};<?php
$curl = curl_init();
$data = array(
'api_sender' => 'smsales',
'message' => 'Hello from SMSALES!',
'phone_numbers' => array('2547XXXXXXXX', '2540XXXXXXXX')
);
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.smsales.co.ke/api/v1/sms/send',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer YOUR_ACCESS_TOKEN'
),
));
?>{
"data": {
"batch": "1DIIPJGDP4",
"message": "Accepted for dispatch..."
}
}/sms
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer YOUR_ACCESS_TOKEN | Access token from /token endpoint |
| Content-Type | application/json | Required for all requests |
| Accept | application/json | Required for all requests |
/sms/balance/account
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer YOUR_ACCESS_TOKEN | Access token from /token endpoint |
| Content-Type | application/json | Required for all requests |
| Accept | application/json | Required for all requests |
{
"data": {
"smsBalance": "57839",
"smsUsage": "47577"
}
}/sms/balance/sender
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer YOUR_ACCESS_TOKEN | Access token from /token endpoint |
| Content-Type | application/json | Required for all requests |
| Accept | application/json | Required for all requests |
{
"data": [
{
"sender": "SENDER01",
"slug": "sender01",
"unitPrice": "0.8",
"smsUsage": 14507,
"isActive": true
},
{
"sender": "SENDER02",
"slug": "sender02",
"unitPrice": "0.8",
"smsUsage": 21755,
"isActive": true
},
{
"sender": "SENDER03",
"slug": "sender03",
"unitPrice": "0.4",
"smsUsage": 9422,
"isActive": true
}
]
}Receive real-time delivery reports via webhooks. Configure a callback URL when sending SMS messages to receive delivery status updates.
When messages are sent, we'll send a POST request to your callback URL with the following payload:
{
"sent": true,
"sender": "SMSALES",
"apiSender": "smsales",
"phoneNumbers": [
"254XXXXXXXXX",
"254XXXXXXXXX",
"254XXXXXXXXX"
],
"batch": "1DIIPJGDP4",
"account": {
"smsBalance": "663",
"smsUsage": "24"
}
}| Field | Type | Description |
|---|---|---|
| sent | Boolean | Indicates if the SMS was successfully sent |
| sender | String | The sender name |
| apiSender | String | The API sender ID used |
| phoneNumbers | Array | List of phone numbers the SMS was sent to |
| batch | String | Unique batch identifier for the SMS |
| account.smsBalance | String | Remaining SMS balance after sending |
| account.smsUsage | String | SMS units used for this batch |
The API uses standard HTTP status codes and returns error details in the response body.
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | invalid_request | The request was malformed or missing required parameters |
| 401 | unauthorized | Invalid or missing Authorization header |
| 403 | forbidden | Invalid or expired token |
| 422 | unprocessable_entity | The request was well-formed but was unable to be followed due to semantic errors |
| 429 | rate_limit | Too many requests, rate limit exceeded |
| 500 | server_error | Internal server error |
Official SMSALES SDKs for popular programming languages. These libraries simplify integration by handling authentication, error handling, and API calls for you.
Official PHP library for SMSALES API integration. Supports Laravel, Symfony, and standalone PHP applications.
Node.js and browser JavaScript library. Includes TypeScript definitions and Promise-based API.
Python library for Django, Flask, and standalone scripts. Async support with asyncio.
Start integrating SMS capabilities into your applications today. Get your API token and send your first SMS in minutes.
Get API Token View Documentation