SMS API documentation for developers

Explore Celcom Africa's SMS, WhatsApp and USSD API docs - REST and SMPP support, PHP, Python and Node.js code samples, and a free sandbox to integrate messaging in under 10 minutes.

Get API key

REST ┬╖ JSON GET & POST No API call fees

POST /api/services/sendsms/

// Quick start - send your first SMS
const res = await fetch(
  'https://isms.celcomafrica.com/api/services/sendsms/',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      partnerID: 'YOUR_PARTNER_ID',
      apikey:    'YOUR_API_KEY',
      mobile:    '254712345678',
      message:   'Hello from Celcom!',
      shortcode: 'YOUR_SENDER_ID',
    }),
  }
);
// ΓåÆ { responses: [{ messageid: 8290842, ... }] }

99.99%

uptime

50+

Countries

850M+

Vol/Month

<5s

TAT

Quick navigation

REST

Send SMS API

GET & POST methods with code samples

POST

Error Codes

API response code reference

Introduction API parameters Send SMS API response Scheduling Delivery reports Account balance Error codes DEVELOPERS_FAQ

Introduction

Overview

Integrate your system with Celcom Africa's bulk SMS services using our REST API. The gateway delivers messages to multiple recipients quickly and efficiently - with real-time delivery reports and account balance queries built in.

Before you begin

Register for a free account
Open your dashboard and click GET API KEY & PARTNER ID
Copy a code sample below and send a test message with free credits

API parameters

Reference

All send-SMS requests require the parameters below. Optional fields enable scheduling and encoding options.

Parameter	Type	Required	Description
apikey	string	Required	Valid API key from your dashboard (GET API KEY & PARTNER ID).
partnerID	string	Required	Valid Partner ID from your dashboard.
message	string	Required	URL-encoded text message with valid GSM-7 characters.
shortcode	string	Required	Registered Sender ID or shortcode.
mobile	string	Required	Valid mobile number. Comma-separated for bulk sends.
pass_type	string	Optional	POST only. plain (default) or bm5 (base64-encoded message).
timeToSend	string	Optional	Schedule for future delivery - date string or Unix timestamp.

Send SMS

Core endpoint

GET

https://isms.celcomafrica.com/api/services/sendsms/?

Pass all parameters as URL query string values. Bulk recipients can be comma-separated in the mobile field.

GET request - PHP

php

$partnerID = "useraccountpartnerId";
$apikey = "useraccountapikey";
$shortcode = "INFOTEXT";
$mobile = "254712345678"; // comma-separated for bulk
$message = "This is a test message + = # @ _ -";

$finalURL = "https://isms.celcomafrica.com/api/services/sendsms/?"
  . "apikey=" . urlencode($apikey)
  . "&partnerID=" . urlencode($partnerID)
  . "&message=" . urlencode($message)
  . "&shortcode=$shortcode&mobile=$mobile";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $finalURL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo "Response: $response";

POST

https://isms.celcomafrica.com/api/services/sendsms/

Send a JSON body with Content-Type: application/json. Use pass_type: "plain" for normal text or bm5 for base64-encoded messages.

POST request - PHP

php

$url = 'https://isms.celcomafrica.com/api/services/sendsms/';
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$data = [
  'partnerID' => '00',
  'apikey'    => 'xxxxxxxxxxx',
  'mobile'    => '0712345678',
  'message'   => 'This is a test message',
  'shortcode' => 'INFOTEXT',
  'pass_type' => 'plain', // or bm5 (base64)
];

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
print_r($response);

POST request - Node.js

node.js

const response = await fetch(
  'https://isms.celcomafrica.com/api/services/sendsms/',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      partnerID: '00',
      apikey: 'xxxxxxxxxxx',
      mobile: '0712345678',
      message: 'This is a test message',
      shortcode: 'INFOTEXT',
      pass_type: 'plain',
    }),
  }
);

const data = await response.json();
console.log(data);

POST request - Python

python

import requests

url = 'https://isms.celcomafrica.com/api/services/sendsms/'
payload = {
    'partnerID': '00',
    'apikey': 'xxxxxxxxxxx',
    'mobile': '0712345678',
    'message': 'This is a test message',
    'shortcode': 'INFOTEXT',
    'pass_type': 'plain',
}

response = requests.post(url, json=payload)
print(response.json())

API response

Parsing

A successful send returns a JSON object with a responses array. Save the messageid - you'll need it to query delivery reports.

Sample response

json

{
  "responses": [
    {
      "respose-code": 200,
      "response-description": "Success",
      "mobile": 254713482448,
      "messageid": 8290842,
      "networkid": "1"
    }
  ]
}

respose-code

HTTP-style status (200 = success)

messageid

Use for delivery report queries

networkid

Destination carrier network

Message scheduling

Optional

Schedule messages for future delivery by including the optional timeToSend parameter with a date string or Unix timestamp.

Scheduled send payload

json

{
  "apikey": "123456789",
  "partnerID": "123",
  "message": "this is a test message",
  "shortcode": "SENDERID",
  "mobile": "254712345678",
  "timeToSend": "2019-09-01 18:00"
}

Delivery reports

POST

https://isms.celcomafrica.com/api/services/getdlr/

Query delivery status for a sent message using the messageID from the send response.

Get delivery report - PHP

php

$url = 'https://isms.celcomafrica.com/api/services/getdlr/';
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$data = [
  'partnerID' => '00',
  'apikey'    => 'xxxxxxxxxxxxx',
  'messageID' => '123456789',
];

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
print_r(curl_exec($curl));

Account balance

POST

https://isms.celcomafrica.com/api/services/getbalance/

Check remaining SMS credits before sending campaigns or integrating balance alerts into your application.

Get account balance - PHP

php

$url = 'https://isms.celcomafrica.com/api/services/getbalance/';
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$data = [
  'partnerID' => '00',
  'apikey'    => 'xxxxxxxxxxxxx',
];

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
print_r(curl_exec($curl));

Error codes

Reference

API responses include a numeric code in each response object. Use this table to diagnose failed requests.

Code	Description
`200`	Successful request
`1001`	Invalid sender ID
`1002`	Network not allowed
`1003`	Invalid mobile number
`1004`	Low bulk credits
`1005`	Failed - system error
`1006`	Invalid credentials
`1007`	Failed - system error
`1008`	No delivery report
`1009`	Unsupported data type
`1010`	Unsupported request type
`4090`	Internal error - retry after 5 minutes
`4091`	No Partner ID set
`4092`	No API key provided
`4093`	Details not found

Frequently asked questions

DEVELOPERS_FAQ

Register for a free account, open your dashboard and click GET API KEY & PARTNER ID to retrieve credentials. Review this documentation, copy a code sample in your language, and test with free SMS credits. Integration typically takes under 10 minutes.

Any language that can make HTTP requests. We provide working examples in PHP, Python, and Node.js. The API uses standard REST principles with JSON responses.

SMS Gateway API is our general-purpose REST API for marketing and notifications. A2P SMS Gateway is enterprise-grade for mission-critical messaging like OTPs and banking alerts, with premium routing and higher SLA. Both use similar endpoints.

Use the Get Delivery Report endpoint with the messageID returned from the send response. You can also view reports in your dashboard or configure webhooks for automatic notifications.

No strict rate limits for standard usage. API access is free - you only pay for SMS credits used, starting from KES 0.25 per SMS with volume discounts. See our SMS pricing for full rate tiers.

Yes. Pass the optional timeToSend parameter with a date string (e.g. 2019-09-01 18:00) or Unix timestamp. The API queues and delivers the message at the specified time.

Introduction API parameters Send email API response Scheduling

Introduction

Overview

Send transactional and notification emails through Celcom Africa's Email API. Authenticate with your partner credentials, set from/to addresses, and optionally schedule delivery.

Before you begin

Register for a free account
Open your dashboard and click GET API KEY & PARTNER ID
Use an approved from_address on your account

API parameters

Reference

All send-email requests require the parameters below. Optional fields enable encoding and scheduling.

Parameter	Type	Required	Description
apikey	string	Required	Valid API key from your dashboard (GET API KEY & PARTNER ID).
partnerID	string	Required	Partner ID attached to your account.
from_address	string	Required	Sender email address (approved/registered from-address).
to_address	string	Required	Destination / receiver email address.
subject	string	Required	Email subject line.
body	string	Required	Email message body.
pass_type	string	Optional	plain (default) or bm5 (base64-encoded body).
timeToSend	string	Optional	Optional. Schedule for future delivery.

Send email

Core endpoint

POST

https://isms.celcomafrica.com/api/services/send-email

Send a JSON body with Content-Type: application/json. Use pass_type: "plain" for normal text or bm5 for a base64-encoded body.

POST request - PHP

php

$url = 'https://isms.celcomafrica.com/api/services/send-email';
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$data = [
  'partnerID'    => '00',
  'apikey'       => 'xxxxx',
  'from_address' => 'info@test.com',
  'to_address'   => 'test@gmail.com',
  'subject'      => 'Test Message API',
  'body'         => 'This is a test message',
  'pass_type'    => 'plain', // or bm5 (base64)
];

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
print_r($response);

POST request - Node.js

node.js

const response = await fetch(
  'https://isms.celcomafrica.com/api/services/send-email',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      partnerID: '00',
      apikey: 'xxxxx',
      from_address: 'info@test.com',
      to_address: 'test@gmail.com',
      subject: 'Test Message API',
      body: 'This is a test message',
      pass_type: 'plain',
    }),
  }
);

const data = await response.json();
console.log(data);

POST request - Python

python

import requests

url = 'https://isms.celcomafrica.com/api/services/send-email'
payload = {
    'partnerID': '00',
    'apikey': 'xxxxx',
    'from_address': 'info@test.com',
    'to_address': 'test@gmail.com',
    'subject': 'Test Message API',
    'body': 'This is a test message',
    'pass_type': 'plain',
}

response = requests.post(url, json=payload)
print(response.json())

API response

Parsing

A successful send returns a JSON object with the recipient, message ID, and credit cost. Save messageid for your records.

Sample response

json

{
  "response-code": 200,
  "response-description": "Success",
  "recipient": "test@gmail.com",
  "messageid": "xxxx",
  "cost": 1
}

response-code

200 = success

messageid

Unique ID for the sent email

cost

Credits charged for the send

Message scheduling

Optional

Schedule emails for future delivery by including the optional timeToSend parameter.

Scheduled send payload

json

{
  "partnerID": "00",
  "apikey": "xxxxx",
  "from_address": "info@test.com",
  "to_address": "test@gmail.com",
  "subject": "Scheduled email",
  "body": "This message will send later",
  "pass_type": "plain",
  "timeToSend": "2019-09-01 18:00"
}

Introduction API parameters Phone format Send OTP API response Error codes

Introduction

Overview

The WhatsApp OTP API lets partners send one-time password messages over WhatsApp. Use it for login verification, 2FA, and account confirmation flows with an approved sender ID.

Before you begin

Register for a free account
Retrieve your API key and Partner ID
Confirm your approved WhatsApp senderID

API parameters

Reference

All WhatsApp OTP requests require the parameters below.

Parameter	Type	Required	Description
apiKey	string	Required	API authentication key issued to the partner.
partnerID	string	Required	Unique partner identifier.
mobile	string	Required	Recipient Kenyan mobile number in international format. Example: 254712345678.
message	string	Required	OTP message text, typically including a numeric code (e.g. Your OTP is 2345).
senderID	string	Required	Approved WhatsApp sender ID as an international phone number. Example: 254700000000.

Phone number format

Important

Both mobile and senderID must use international Kenyan formats without spaces or plus signs:

2547XXXXXXXX

Example: 254712345678

2541XXXXXXXX

Example: 254100123456

Send WhatsApp OTP

Core endpoint

POST

https://isms.celcomafrica.com/api/services/whatsapp/sendotp

POST a JSON body with Content-Type: application/json. Note the credential field is apiKey (camelCase), unlike the SMS and Email APIs which use apikey.

Sample request - cURL

bash

curl --request POST 'https://isms.celcomafrica.com/api/services/whatsapp/sendotp' \
  --header 'Content-Type: application/json' \
  --data '{
    "apiKey": "YOUR_API_KEY",
    "partnerID": "xx",
    "mobile": "254712345678",
    "message": "Your OTP is 2345",
    "senderID": "254700000000"
  }'

POST request - PHP

php

$url = 'https://isms.celcomafrica.com/api/services/whatsapp/sendotp';
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$data = [
  'apiKey'    => 'YOUR_API_KEY',
  'partnerID' => 'xx',
  'mobile'    => '254712345678',
  'message'   => 'Your OTP is 2345',
  'senderID'  => '254700000000',
];

curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($curl);
print_r($response);

POST request - Node.js

node.js

const response = await fetch(
  'https://isms.celcomafrica.com/api/services/whatsapp/sendotp',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      apiKey: 'YOUR_API_KEY',
      partnerID: 'xx',
      mobile: '254712345678',
      message: 'Your OTP is 2345',
      senderID: '254700000000',
    }),
  }
);

const data = await response.json();
console.log(data);

POST request - Python

python

import requests

url = 'https://isms.celcomafrica.com/api/services/whatsapp/sendotp'
payload = {
    'apiKey': 'YOUR_API_KEY',
    'partnerID': 'xx',
    'mobile': '254712345678',
    'message': 'Your OTP is 2345',
    'senderID': '254700000000',
}

response = requests.post(url, json=payload)
print(response.json())

API response

Parsing

A successful request returns response-code: 200 and a messageid.

Sample success response

json

{
  "response-code": 200,
  "response-description": "success",
  "messageid": "MSG123456789"
}

Sample error response

json

{
  "response-code": 1003,
  "response-description": "Validation Errors. Check errors and try again",
  "errors": "[]"
}

Error codes

Reference

Use this table to diagnose failed WhatsApp OTP requests.

Code	Description
`200`	OTP accepted successfully
`1003`	Validation errors (e.g. invalid phone number or sender ID)
`1006`	Invalid credentials
`402`	Low balance
`500`	Internal server error

Ready to integrate?

Get your free API key, test with complimentary credits, and go live in minutes. Developer support is available 24/7.

Get API key Talk to support

SMS API documentation for developers

Quick navigation

Send SMS API

Delivery Reports

Account Balance

Error Codes

Introduction

API parameters

Send SMS

API response

Message scheduling

Delivery reports

Account balance

Error codes

Frequently asked questions

Introduction

API parameters

Send email

API response

Message scheduling

Introduction

API parameters

Phone number format

Send WhatsApp OTP

API response

Error codes

Ready to integrate?

SMS API documentation for developers

Quick navigation

Send SMS API

Delivery Reports

Account Balance

Error Codes

Introduction

API parameters

Send SMS

API response

Message scheduling

Delivery reports

Account balance

Error codes

Frequently asked questions

How do I get started with the SMS API?

What programming languages are supported?

What is the difference between SMS Gateway API and A2P SMS Gateway?

How do I check delivery status of sent messages?

What are the API rate limits and pricing?

Can I schedule SMS messages using the API?

Introduction

API parameters

Send email

API response

Message scheduling

Introduction

API parameters

Phone number format

Send WhatsApp OTP

API response

Error codes

Ready to integrate?