MboaSMS API

STABLE

Integrate SMS messaging into your applications with the MboaSMS Developer API. Send single or bulk SMS to recipients across 50+ countries with reliable delivery and real-time tracking.

🚀

Quick Start

Send your first SMS in under 2 minutes

🌍

50+ Countries

International coverage with local pricing

⚡

< 3s Delivery

Average delivery time worldwide

Base URL

All API requests should be made to the following base URL:

https://api.mboasms.com

All endpoints are relative to this base URL. For example, the send SMS endpoint is at https://api.mboasms.com/api/v1/developer/sms/send

Authentication

The MboaSMS API supports two authentication methods. Choose the one that best fits your use case.

1JWT Token Authentication

Authenticate by logging in to obtain a JWT token, then include it in the Authorization header of subsequent requests.

cURL

# Include JWT token in the Authorization header
curl -X POST https://api.mboasms.com/api/v1/developer/sms/send \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+237670000000"],
    "message": "Hello from MboaSMS!",
    "senderId": "MboaSMS"
  }'

2Basic Authentication

For simpler integrations, use HTTP Basic Authentication with your username and password encoded in Base64. Use the dedicated /send-with-auth endpoint.

cURL

# Basic Auth: username:password encoded in Base64
curl -X POST https://api.mboasms.com/api/v1/developer/sms/send-with-auth \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+237670000000"],
    "message": "Hello from MboaSMS!"
  }'

⚠️ Keep your credentials secure

Never expose your JWT tokens or credentials in client-side code. Always make API calls from your backend server.

Rate Limiting

To ensure service stability, API requests are subject to rate limiting.

Plan	Rate Limit	Period
Standard	100 requests	per minute
Premium	500 requests	per minute
Enterprise	Custom	Contact sales

ℹ️ Rate limit exceeded

When rate limited, the API returns a 429 Too Many Requests response. Retry after the duration indicated in the response headers.

Send SMS

POST/api/v1/developer/sms/send

Send SMS messages to one or more phone numbers. The user and enterprise are identified via JWT token. Phone numbers can be in international format (+237, +33, etc.) or local format (670...).

Requires JWT Authentication

Request Body

Parameter	Type	Required	Description
phoneNumbers	string[]	Required	Array of recipient phone numbers (international or local format)
message	string	Required	The SMS message content to send
senderId	string	Optional	Custom sender ID. Defaults to the company sender ID if not provided

Examples

cURL

curl -X POST https://api.mboasms.com/api/v1/developer/sms/send \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+237670000000", "+33612345678"],
    "message": "Bonjour! Votre code de verification est: 1234",
    "senderId": "MboaSMS"
  }'

JavaScript (Node.js)

JavaScript

const response = await fetch(
  "https://api.mboasms.com/api/v1/developer/sms/send",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_JWT_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phoneNumbers: ["+237670000000", "+33612345678"],
      message: "Bonjour! Votre code de verification est: 1234",
      senderId: "MboaSMS",
    }),
  }
);

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

Python

import requests

response = requests.post(
    "https://api.mboasms.com/api/v1/developer/sms/send",
    headers={
        "Authorization": "Bearer YOUR_JWT_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "phoneNumbers": ["+237670000000", "+33612345678"],
        "message": "Bonjour! Votre code de verification est: 1234",
        "senderId": "MboaSMS",
    },
)

print(response.json())

Response

200SMS sent successfully

JSON

{
  "success": true,
  "message": "SMS sent successfully",
  "data": {
    "totalSent": 2,
    "totalFailed": 0,
    "creditsUsed": 2
  }
}

Send SMS (Basic Auth)

POST/api/v1/developer/sms/send-with-auth

Send SMS messages using HTTP Basic Authentication (username:password encoded in Base64). This is a simpler alternative when JWT token management is not desired.

Requires Basic Authentication header

Headers

Parameter	Type	Required	Description
Authorization	string	Required	Basic {base64(username:password)}
Content-Type	string	Required	application/json

Request Body

Parameter	Type	Required	Description
phoneNumbers	string[]	Required	Array of recipient phone numbers
message	string	Required	The SMS message content
senderId	string	Optional	Custom sender ID

Example

cURL

# Encode credentials: echo -n "username:password" | base64
curl -X POST https://api.mboasms.com/api/v1/developer/sms/send-with-auth \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+237670000000"],
    "message": "Test message via Basic Auth"
  }'

Responses

200SMS sent successfully

401Unauthorized - invalid credentials

402Insufficient credits

Send Bulk SMS

POST/api/v1/developer/sms/send-bulk

Send SMS messages in bulk from an Excel (.xlsx) or CSV file. This endpoint is ideal for large-scale campaigns with personalized messages per recipient.

Requires JWT Authentication

💡 File Format

Column 1 (required): Phone number

Column 2 (optional): Message — if not present, the message query parameter is required

Supported formats: .xlsx, .csv

CSV delimiters: comma (,), semicolon (;), or tab

Query Parameters

Parameter	Type	Required	Description
message	string	Optional	Default message if the file doesn't contain a messages column
senderId	string	Optional	Custom sender ID. Defaults to the company sender ID if not provided

Request Body (multipart/form-data)

Parameter	Type	Required	Description
file	binary	Required	Excel (.xlsx) or CSV file with phone numbers and optionally messages

Example

cURL

# With personalized messages in the file
curl -X POST "https://api.mboasms.com/api/v1/developer/sms/send-bulk" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@contacts.xlsx"

# With a default message for all recipients
curl -X POST "https://api.mboasms.com/api/v1/developer/sms/send-bulk?message=Hello%20from%20MboaSMS&senderId=MyApp" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@phone_numbers.csv"

CSV File Example

CSV

+237670000000,Bonjour Jean! Votre commande #1234 est prete.
+237680000000,Bonjour Marie! Votre commande #5678 est prete.
+33612345678,Hello Paul! Your order #9012 is ready.

Responses

200Bulk SMS processed successfully

JSON

{
  "success": true,
  "message": "Bulk SMS processed successfully",
  "data": {
    "totalSent": 150,
    "totalFailed": 3,
    "creditsUsed": 150
  }
}

400Invalid file or request

Response Format

All API endpoints return JSON responses following a consistent format:

Success Response

JSON

{
  "success": true,
  "message": "SMS sent successfully",
  "data": {
    "totalSent": 2,
    "totalFailed": 0,
    "creditsUsed": 2
  }
}

Error Response

JSON

{
  "success": false,
  "message": "Invalid request",
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "details": "One or more phone numbers are invalid"
  }
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of requests.

Code	Status	Description
200	OK	Request succeeded — SMS sent or processed
400	Bad Request	Invalid request — missing or malformed parameters, invalid file format
401	Unauthorized	Authentication failed — invalid or missing JWT token / Basic Auth credentials
402	Payment Required	Insufficient credits — recharge your account to continue sending
429	Too Many Requests	Rate limit exceeded — wait before retrying
500	Server Error	Internal server error — contact support if the issue persists