Developer's Guide: Integrating MSpace's REST JSON Bulk SMS API into Your Custom Web or Mobile App

 

If you are developing a website, mobile application, CRM, e-commerce platform, school management system, hospital system, SACCO platform, booking application or any other software that needs to send SMS, you do not necessarily need to build an SMS delivery infrastructure from scratch.

You can connect your application to an SMS gateway through an API and allow your software to trigger messages automatically.

For example:

• A customer creates an account → send a welcome SMS

• A user resets a password → send a verification code

• A customer places an order → send an order confirmation

• A school publishes results → notify parents

• A patient books an appointment → send a reminder

• A SACCO records a payment → send a confirmation

• A customer makes a purchase → send a receipt notification

• A company needs to notify thousands of customers → trigger a bulk campaign

MSpace provides a REST-based Bulk SMS API that allows developers to send SMS programmatically, check SMS balances, query sub-users and retrieve delivery reports without having to manually log into the MSpace web application for every message.

This guide explains the basic architecture and shows developers how to integrate the current JSON API into a custom web or mobile application.

---

What Is the MSpace Bulk SMS API?

An API, or Application Programming Interface, allows two software systems to communicate.

Your application handles your business logic.

MSpace handles the SMS gateway.

The basic architecture looks like this:

Your Web/Mobile App

↓

Your Backend Server

↓

MSpace REST SMS API

↓

Mobile Network

↓

Customer's Phone

For example, a customer purchases something from your e-commerce application.

Your application records the order.

Your backend then sends an API request to MSpace.

MSpace processes the SMS request and returns a response containing information such as the message ID and sending status.

Your application can then store that information in your own database.

This creates an automated communication system.

---

What Can You Do With the API?

The current MSpace Bulk SMS API documentation provides several useful operations.

Developers can use the API to:

1. Send SMS

2. Check SMS account balance

3. Query delivery reports

4. List sub-account users

5. Query reseller clients

6. Top up sub-accounts

7. Top up reseller clients

For most application developers, the three most important operations are likely to be:

Send SMS

Check balance

Check delivery status

These allow your application to send messages and monitor what happened afterward.

---

Before You Start

You need an MSpace Bulk SMS account before using the API.

You also need an API key.

According to MSpace's current documentation, the API key can be generated from the Bulk SMS system by going to:

API → SMS → Generate Keys

You then generate a key for the appropriate user and copy it for use in your application.

You will generally need:

• MSpace Bulk SMS account

• MSpace username

• API key

• Approved sender ID where applicable

• Your application's backend

• A server capable of making HTTPS requests

• A database if you want to store message records

Your API key should be treated as a secret credential.

Do not place it directly inside a publicly distributed mobile application.

For a mobile app, requests should normally go through your own secure backend.

---

The Current SMS API Endpoint

The current MSpace JSON SMS endpoint is:

https://api.mspace.co.ke/smsapi/v2/sendtext

The request uses:

POST

The API key is supplied through the request header.

The current documentation specifies:

apikey: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

The JSON body contains:

{
    "username": "Your_Username",
    "senderId": "Your_Sender_Id",
    "recipient": "07XXXXXXXXX,2547XXXXXXXX",
    "message": "Your message."
}

MSpace documents both POST and GET methods, but for a modern application integration, the JSON POST approach is the cleaner pattern to use.

---

Understanding the JSON Request

Let's examine the main fields.

username

This identifies the MSpace account or user associated with the request.

Example:

"username": "mybusiness"

Use the username associated with your MSpace account.

---

senderId

This represents the sender identity used for the SMS.

For example:

"senderId": "MYBUSINESS"

The sender ID available to your account depends on your MSpace configuration and applicable network requirements.

---

recipient

This contains the destination phone number or numbers.

The current documentation shows that multiple recipients can be included in the request, separated by commas.

For example:

"recipient": "0712345678,254712345678"

For production systems, your application should normalize phone numbers consistently before sending.

For example, you might store Kenyan numbers internally in international format:

254712345678

rather than maintaining multiple formats throughout your database.

---

message

This is the actual SMS content.

For example:

"message": "Your order #1045 has been received. Thank you for shopping with us."

Your application can generate this dynamically.

That is where the real power of API integration begins.

---

A Complete Example Request

A simplified HTTP request would look like this:

POST https://api.mspace.co.ke/smsapi/v2/sendtext
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: application/json

{
  "username": "Your_Username",
  "senderId": "YOURBRAND",
  "recipient": "254712345678",
  "message": "Your appointment is confirmed for 10:00 AM tomorrow."
}

The API can then return a JSON response containing the message ID, recipient and status. MSpace's documented successful-send response includes a messageId and a status description indicating that the message was sent successfully.

---

Example Response

A response can look like:

{
    "message": [
        {
            "messageId": "49032372",
            "recipient": "0722XXXXXX",
            "status": 111,
            "statusDescription": "Message sent succesfully"
        }
    ]
}

The important value here is:

messageId

You should consider storing that ID in your own database.

Why?

Because you can use it later when checking the delivery report.

---

Why You Should Store the Message ID

Imagine your application sends an SMS to 50,000 customers.

Your database could contain:

Customer	Phone	Message ID	Status
John	254712345678	49032372	Sent
Mary	254723456789	49032373	Sent
Peter	254734567890	49032374	Sent

Your application can later query the MSpace delivery report using the relevant message ID.

This means your application does not have to treat every SMS as simply:

Sent = Delivered

Those are different stages.

---

Checking SMS Delivery Status

MSpace provides a delivery-report endpoint:

https://api.mspace.co.ke/smsapi/v2/deliveryreport

The request requires the API key and JSON body containing the username and message ID.

Example:

{
    "username": "Your_Username",
    "messageId": "49032372"
}

A response can contain:

{
    "message": [
        {
            "messageId": "49032372",
            "recipient": "0722XXXXXX",
            "status": 3,
            "statusDescription": "Delivered"
        }
    ]
}

This allows your application to distinguish between messages that were successfully submitted and messages for which a delivery status is available.

---

Example Python Integration

Python developers can use libraries such as requests to communicate with the API.

A basic implementation can look like this:

import requests

url = "https://api.mspace.co.ke/smsapi/v2/sendtext"

headers = {
    "apikey": "YOUR_API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "username": "YOUR_USERNAME",
    "senderId": "YOUR_SENDER_ID",
    "recipient": "254712345678",
    "message": "Your appointment is confirmed for tomorrow at 10:00 AM."
}

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

print(response.json())

Do not hard-code your real API key into source code that will be publicly distributed.

For production applications, load credentials from secure environment variables or a secrets-management system.

---

Example PHP Integration

PHP developers can use cURL.

For example:

<?php

$url = "https://api.mspace.co.ke/smsapi/v2/sendtext";

$payload = [
    "username" => "YOUR_USERNAME",
    "senderId" => "YOUR_SENDER_ID",
    "recipient" => "254712345678",
    "message" => "Your order has been received. Thank you."
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "apikey: YOUR_API_KEY",
        "Content-Type: application/json",
        "Accept: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_TIMEOUT => 30
]);

$response = curl_exec($ch);

if ($response === false) {
    echo "Request failed: " . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>

The MSpace documentation also provides sample implementations for several programming environments, including Python, PHP and C#.

---

Example JavaScript / Node.js Backend

If your application uses Node.js, you can make the API request from your backend.

For example:

const response = await fetch(
  "https://api.mspace.co.ke/smsapi/v2/sendtext",
  {
    method: "POST",
    headers: {
      "apikey": process.env.MSPACE_API_KEY,
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    body: JSON.stringify({
      username: process.env.MSPACE_USERNAME,
      senderId: "YOUR_SENDER_ID",
      recipient: "254712345678",
      message: "Your order has been confirmed."
    })
  }
);

const data = await response.json();

console.log(data);

The important security principle is that the MSpace API credentials remain on your server rather than being exposed to users.

---

How a Mobile App Should Use the API

Suppose you are building an Android or iOS application.

A common mistake would be:

Mobile App → MSpace API directly

This could expose your API credentials.

A better architecture is:

Mobile App

↓

Your Backend API

↓

MSpace API

↓

Customer

The mobile application communicates with your backend.

Your backend validates the request and decides whether an SMS should be sent.

It then securely communicates with MSpace.

This also gives you more control over:

• Authentication

• Rate limiting

• Logging

• Validation

• Permissions

• Fraud prevention

• Message templates

• Customer records

---

Example: E-Commerce Application

Imagine an online store.

A customer places an order.

Your application records:

Order ID: 1045
Customer: John
Phone: 254712345678
Amount: KES 4,500
Status: Paid

Your backend can generate:

Your order #1045 has been confirmed. Amount paid: KES 4,500. We will notify you when your order is dispatched.

The backend sends that message through MSpace.

The workflow becomes:

Customer places order

↓

Payment confirmed

↓

Database updated

↓

Backend triggers MSpace API

↓

SMS submitted

↓

Message ID stored

↓

Delivery status checked

This is far more scalable than having staff manually send confirmation messages.

---

Example: School Management System

A school management application could use the API to automatically send:

• Fee payment confirmations

• Exam result notifications

• Attendance alerts

• Meeting reminders

• Emergency notices

• School calendar reminders

• Fee balance reminders

For example:

Dear Parent, a payment of KES 10,000 has been received for student John Kamau. Thank you.

The school management system generates the message automatically after recording the payment.

---

Example: Hospital or Clinic System

A healthcare application could trigger:

Your appointment with Dr. Otieno is confirmed for Monday at 10:00 AM.

It could also send:

• Appointment reminders

• Booking confirmations

• Rescheduling notifications

• Follow-up reminders

• Payment confirmations

The API becomes a communication component inside the healthcare system.

---

Example: SACCO or Financial Platform

A SACCO application could trigger SMS after:

• Deposit

• Withdrawal

• Loan repayment

• Loan application

• Loan approval

• Account update

• Meeting reminder

For example:

Your payment of KES 5,000 has been received. Your SACCO account has been updated.

The transaction happens inside the SACCO's system.

The SMS happens automatically through the API.

---

Example: Booking Platform

A hotel, restaurant or travel application can trigger:

Your booking is confirmed for 18 October at 7:00 PM. Booking reference: BK10452.

Other possible automated notifications include:

• Reservation confirmation

• Check-in reminder

• Booking changes

• Cancellation confirmation

• Payment confirmation

• Travel reminders

This is particularly useful when the application handles a high volume of bookings.

---

Checking the SMS Account Balance

Your application can also check the SMS account balance.

The current endpoint is:

https://api.mspace.co.ke/smsapi/v2/balance

A POST request contains the username:

{
    "username": "your_username"
}

The documented response is an integer representing the SMS balance.

For example:

7628

You could use this information to build an internal monitoring system.

For example:

SMS balance: 7,628

Then your application could notify an administrator when the balance falls below a threshold.

---

Building an SMS Monitoring System

For a larger application, you could create an internal dashboard.

SMS Dashboard

Available SMS: 7,628

Messages sent today: 4,291

Delivered: 4,050

Pending: 130

Failed: 111

Low balance alert: No

Your application can obtain the underlying information through API calls and your own message database.

This gives the business more visibility over its communication infrastructure.

---

Handling API Errors

No API integration should assume that every request will succeed.

Your application should handle:

• HTTP 400 errors

• HTTP 404 errors

• Authentication errors

• Invalid parameters

• Network failures

• Timeout errors

• Insufficient SMS balance

• Invalid recipient numbers

MSpace's documentation specifically advises checking the endpoint, request method and API-key spelling when errors occur.

Your application should also log failures.

For example:

SMS ID: 49032372
Recipient: 254712345678
Status: Failed
Error: Invalid recipient
Time: 2026-10-02 18:32

That makes troubleshooting much easier.

---

Validate Phone Numbers Before Sending

Your application should validate recipient numbers before making the API request.

For example, you may want to normalize Kenyan numbers from:

0712345678

to:

254712345678

before sending.

Do not blindly assume that every value stored in your customer database is a valid mobile number.

A production system should validate:

• Country code

• Number length

• Numeric format

• Empty values

• Duplicate recipients

This reduces avoidable API errors.

---

Don't Put Your API Key in Front-End Code

This deserves special emphasis.

Never do this in a publicly accessible JavaScript application:

const API_KEY = "my-secret-key";

Anyone who can inspect the application could potentially obtain the credential.

Instead:

Frontend

→ sends request to your backend

Backend

→ validates request

Backend

→ authenticates with MSpace

MSpace

→ sends SMS

The API key stays on the server.

---

Create Reusable SMS Functions

Rather than writing the complete API request every time your application needs to send an SMS, create a reusable function.

For example:

sendSMS(recipient, message)

Then your business logic can simply call:

sendSMS(customer.phone, confirmationMessage)

The function handles:

• API authentication

• Request construction

• Error handling

• Response processing

• Logging

• Message ID storage

This makes the rest of your application cleaner.

---

Store Your SMS Records

A production application should maintain its own SMS log.

For example:

ID	Customer	Recipient	Message ID	Status
1	John	254712345678	49032372	Sent
2	Mary	254723456789	49032373	Delivered
3	Peter	254734567890	49032374	Failed

This allows administrators to investigate communication problems without searching through application logs.

---

Design Your Integration for Scale

If your application sends only a few messages per day, a simple synchronous API call may be sufficient.

If your application sends thousands or tens of thousands of messages, consider using a queue.

Instead of:

User action → API request → wait for SMS response

you can build:

User action

↓

Create notification job

↓

Message queue

↓

SMS worker

↓

MSpace API

↓

Store result

This prevents heavy SMS traffic from slowing down the main application.

It also makes retries easier.

---

Separate Transactional and Marketing Messages

Your application may send different categories of SMS.

Transactional

Examples:

• OTP

• Payment confirmation

• Booking confirmation

• Order confirmation

• Account notification

Marketing

Examples:

• Promotions

• Discounts

• Product launches

• Sales campaigns

• Special offers

Keeping these categories separate helps your development team manage templates, permissions, reporting and customer communication more systematically.

Marketing communication should also be handled in accordance with applicable consent, privacy and messaging requirements.

---

Use the API as Part of a Larger System

The MSpace API does not have to be a standalone SMS button.

It can become part of your entire software ecosystem.

For example:

CRM

→ MSpace SMS

E-commerce

→ MSpace SMS

ERP

→ MSpace SMS

School Management System

→ MSpace SMS

Hospital Management System

→ MSpace SMS

Mobile App

→ Your Backend

→ MSpace SMS

Website

→ Your Backend

→ MSpace SMS

The possibilities depend on your application's architecture and business requirements.

---

A Complete Example Architecture

Consider an online marketplace.

Customer

Places an order.

↓

Web Application

Records the order.

↓

Backend

Checks payment status.

↓

Notification Service

Creates SMS message.

↓

MSpace API

Receives JSON request.

↓

MSpace

Processes SMS.

↓

Mobile Network

Delivers message.

↓

MSpace Delivery Report

Returns delivery information.

↓

Your Database

Stores delivery status.

↓

Admin Dashboard

Displays communication status.

This is a scalable way of adding SMS communication to a software product.

---

Common Developer Mistakes to Avoid

1. Exposing the API key

Keep credentials server-side.

2. Assuming API submission means delivery

Store the message ID and check delivery information where required.

3. Sending unvalidated phone numbers

Normalize and validate recipients.

4. Hard-coding credentials

Use environment variables or secure secrets management.

5. Ignoring API errors

Log failures and make them visible to administrators.

6. Sending duplicate messages

Use unique transaction or notification IDs where appropriate.

7. Building SMS logic directly into every feature

Create a reusable notification service.

8. Ignoring message length and formatting

Test the actual SMS content your application generates.

9. Putting API credentials inside mobile applications

Use a secure backend.

10. Failing to monitor SMS balance

A successful application can suddenly stop sending messages if the available SMS credit is exhausted.

---

A Simple Development Checklist

Before launching your integration, confirm:

MSpace account

• Bulk SMS account created

• Sender ID configured where required

• API access enabled

Authentication

• API key generated

• API key stored securely

• Credentials not exposed to users

Development

• JSON POST request implemented

• Recipient validation implemented

• Error handling implemented

• Timeout handling implemented

• Message IDs stored

Delivery

• Delivery report integration tested

• Failed messages handled

• Delivery status stored

Monitoring

• SMS balance monitored

• Logs created

• Administrator alerts configured where appropriate

Production

• Test numbers verified

• Message templates reviewed

• Consent requirements considered

• Rate and volume requirements checked

• Backup/error procedures tested

---

Start Building With the MSpace SMS API

For developers, the biggest advantage of an SMS API is that messaging becomes part of the application rather than a separate manual task.

Your software can decide when a message needs to be sent.

Your backend can generate the appropriate content.

MSpace can handle the SMS gateway connection.

Your application can then store the response and monitor delivery.

The current MSpace REST JSON API provides endpoints for sending SMS, checking balances and retrieving delivery reports, making it suitable for developers building custom web applications, mobile applications and business platforms.

If you are building a software product that needs automated SMS communication, you can explore MSpace and create an account here:

https://mspace.co.ke/r/C3D8071C4D

Whether you are building an e-commerce platform, school system, healthcare application, CRM, booking platform, financial application or custom mobile app, integrating SMS at the backend can turn ordinary software events into immediate customer communication.

Build the application once. Let the communication happen automatically.