API Documentation v2

Overview

The Bulk SMS API allows businesses to reliably send SMS messages to customers. It supports delivery reports via callback URLs (DLR), ideal for both production and testing environments.

• Format: RESTful, form-encoded POST requests
• Response: JSON
• DLR: Supports delivery report callbacks
• Testing: 15 SMS/day in testing mode
• Cost: 75 RWF per message

Authentication

The API uses three credentials for authentication. All three are required for every request.

Base URL

All API requests use the application/x-www-form-urlencoded content type.

Send SMS

Sends an SMS message to one or more recipients. Supports comma-separated recipient lists for bulk sending.

Parameters

Example Request

POST /api/v2/sms/send
Content-Type: application/x-www-form-urlencoded

api_key=your_api_key&username=your_username
&password=your_password
&recipients=250782589800,250782589801
&message=Test from BulkSMS!
&dlrurl=https://yourdomain.com/dlr-handler

Success Response

{
  "status": "success",
  "totalmessages": 2,
  "totalcost": 150,
  "unit": "RWF",
  "response": [
    {
      "status": "sent",
      "messageid": "118579716",
      "recipient": "250782589800",
      "message": "Test from BulkSMS!",
      "cost": 75
    },
    {
      "status": "failed",
      "messageid": "118579717",
      "recipient": "250782589801",
      "message": "Test from BulkSMS!",
      "cost": 75
    }
  ]
}

Code Examples

Choose your language to see the integration code:

<?php
$url = 'https://bulksms.schooldream.co.rw/api/v2/sms/send';
$data = [
    'api_key'    => 'your_api_key',
    'username'   => 'your_username',
    'password'   => 'your_password',
    'recipients' => '250782589800,250782589801',
    'message'    => 'Hello from BulkSMS!',
    'dlrurl'     => 'https://yourdomain.com/dlr',
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
echo $result['status']; // "success" or "error"

const axios = require('axios');

const data = {
  api_key: 'your_api_key',
  username: 'your_username',
  password: 'your_password',
  recipients: '250782589800,250782589801',
  message: 'Hello from BulkSMS!',
  dlrurl: 'https://yourdomain.com/dlr',
};

const response = await axios.post(
  'https://bulksms.schooldream.co.rw/api/v2/sms/send',
  data
);
console.log(response.data);

import requests

url = 'https://bulksms.schooldream.co.rw/api/v2/sms/send'
payload = {
    'api_key': 'your_api_key',
    'username': 'your_username',
    'password': 'your_password',
    'recipients': '250782589800,250782589801',
    'message': 'Hello from BulkSMS!',
    'dlrurl': 'https://yourdomain.com/dlr',
}

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

curl -X POST https://bulksms.schooldream.co.rw/api/v2/sms/send \
  -d "api_key=your_api_key" \
  -d "username=your_username" \
  -d "password=your_password" \
  -d "recipients=250782589800,250782589801" \
  -d "message=Hello from BulkSMS!" \
  -d "dlrurl=https://yourdomain.com/dlr"

Delivery Reports (DLR)

Delivery Reports let you track the final status of each message. Our system forwards delivery statuses to your custom callback URL via GET requests.

Callback URL Format

When you provide a dlrurl, our system sends a GET request with these parameters:

https://yourdomain.com/api?dnis=$dnis$&username=youruser&password=yourpass&command=deliver&dlvrMsgId=$messageID$&dlvrMsgStat=$status$

Callback Parameters

Example Callback

GET https://yourdomain.com/api/dlr-handler?dnis=250782589800&username=SmsUser&password=SmsPass&command=deliver&dlvrMsgId=118579716&dlvrMsgStat=D

Final Status Codes

Error Responses

When something goes wrong, the API returns an error response with a descriptive message.

{
  "status": "error",
  "message": "Invalid API key or credentials"
}

Common Errors

Frequently Asked Questions

How do I get my API key?

Contact us at info@digitalservicescenter.rw or call +250 788 822 935 to request your API credentials.

Can I send to multiple numbers?

Yes! Separate phone numbers with commas in the recipients field. Example: 250782589800,250782589801

What happens in testing mode?

You can send up to 15 SMS per day in testing mode. Once the limit is reached, you need to wait until the next day or request live access.

What phone number format should I use?

Use international format without the leading +: 250XXXXXXXXX. Example: 250788000001.

How long does delivery take?

Average delivery time is under 2 seconds. Most messages are delivered within 1 second.

Do you support custom sender IDs?

Yes, use the optional sender parameter. Contact us to register your desired sender ID.