Introduction

Welcome to the Bulk SMS API documentation. This API allows you to seamlessly integrate our SMS platform into your system for sending messages to your clients efficiently.

API Type: RESTful API

API Endpoint

POST https://bulksms.musren.co.ke/api/sms/v1/sendsms

Required Parameters

Parameter Type Description Example
api_key String Your unique API key found in your SMS account under My Profile abc123def456...
sender_id String Your assigned sender name 23107
message String The message content to be sent to recipients "Hello welcome to our sms platform"
phone String Recipient phone number(s). For multiple numbers, separate with commas 254712345678,254711223344

Request Examples

cURL

curl -X POST \
  'https://bulksms.musren.co.ke/api/sms/v1/sendsms' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "your_api_key_here",
    "sender_id": "23107",
    "message": "Hello welcome to our sms platform",
    "phone": "254712345678,254711223344"
  }'

JavaScript (Fetch)

fetch('https://bulksms.musren.co.ke/api/sms/v1/sendsms', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_key: 'your_api_key_here',
        sender_id: '23107',
        message: 'Hello welcome to our sms platform',
        phone: '254712345678,254711223344'
    })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Python (Requests)

import requests
import json

url = "https://bulksms.musren.co.ke/api/sms/v1/sendsms"
payload = {
    "api_key": "your_api_key_here",
    "sender_id": "23107",
    "message": "Hello welcome to our sms platform",
    "phone": "254712345678,254711223344"
}
headers = {
    "Content-Type": "application/json"
}

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

Response Format

{
    "status": "success",
    "message": "Messages sent successfully",
    "data": {
        "message_id": "MSG123456",
        "recipients": 2,
        "credits_used": 2
    }
}

Important Notes

  • Ensure all phone numbers are in the international format (e.g., 254712345678)
  • Multiple phone numbers should be comma-separated without spaces
  • Keep your API key secure and never share it publicly
  • The API has a rate limit of 100 requests per minute
  • Message content should be URL encoded when sending special characters

Error Handling

Error Code Description
400 Missing or invalid parameters
401 Invalid API key
403 Insufficient credits
429 Rate limit exceeded
500 Internal server error

Credit Balance API

The Credit Balance API allows you to query your current SMS credit balance programmatically.

POST https://bulksms.musren.co.ke/api/sms/v1/credit-balance

Required Parameters

Parameter Type Description
api_key String Your unique API key found in your SMS account under My Profile

Request Example

cURL

curl -X POST \
        'https://bulksms.musren.co.ke/api/sms/v1/credit-balance' \
        -H 'Content-Type: application/json' \
        -d '{
            "api_key": "your_api_key_here"
        }'

JavaScript (Fetch)

fetch('https://bulksms.musren.co.ke/api/sms/v1/credit-balance', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                api_key: 'your_api_key_here'
            })
        })
        .then(response => response.json())
        .then(data => console.log(data))
        .catch(error => console.error('Error:', error));

Response Format

Successful Response

[
            {
                "status": "200",
                "balance": "200"
            }
        ]

Error Response

[
            {
                "status": "403",
                "error": "Failed! API Key is invalid"
            }
        ]

Reports API

The Reports API allows you to retrieve detailed delivery statistics and message histories for your shortcodes.

Get Shortcode Statistics

GET /api/sms/reports/v1/shortcode/{shortcode}/status

Response Format

{
            "status": "success",
            "data": {
                "today": {
                    "total": 1250,
                    "delivered": 1000,
                    "failed": 50,
                    "pending": 200
                },
                "hourly": {
                    "2024-12-31 14:00": {
                        "delivered": 120,
                        "failed": 5,
                        "pending": 25
                    },
                    // ... more hourly entries
                }
            }
        }

Get Shortcode Messages

GET /api/sms/reports/v1/shortcode/{shortcode}/messages

Query Parameters

Parameter Type Description
status String Filter by status (Delivered, Failed, Pending)
start_date Date Start date for filtering messages (YYYY-MM-DD)
end_date Date End date for filtering messages (YYYY-MM-DD)
page Integer Page number for pagination (default: 1)
per_page Integer Number of records per page (default: 50, max: 100)

Response Format

{
            "status": "success",
            "data": [
                {
                    "message_id": "MSG123456",
                    "recipient": "254712345678",
                    "status": "Delivered",
                    "sent_at": "2024-12-31 14:30:00",
                    "delivered_at": "2024-12-31 14:30:05",
                    "units": 1
                }
            ],
            "meta": {
                "current_page": 1,
                "last_page": 10,
                "per_page": 50,
                "total": 500
            }
        }

Example Requests

Get Today's Statistics

curl -X GET \
        'https://bulksms.musren.co.ke/api/sms/reports/v1/shortcode/23107/status' \
        -H 'Authorization: Bearer your_api_key_here'

Get Filtered Messages

curl -X GET \
        'https://bulksms.musren.co.ke/api/sms/reports/v1/shortcode/23107/messages?status=Delivered&start_date=2024-12-01&end_date=2024-12-31&page=1&per_page=50' \
        -H 'Authorization: Bearer your_api_key_here'