Mambo SMS API Documentation

Welcome to the Mambo SMS API documentation!

To use the API, you'll first need to create a Mambo SMS account. Sign up here if you don't have one yet.

Once you've created an account, log in and navigate to the "API Settings" page via the sidebar (for desktop users) or the hamburger menu (for mobile users). From there, generate your API key, which you'll use in your functions to send SMS messages, as shown in the examples provided in this documentation.

For support, contact us on +256-775-508-171 or email us on info@mambosms.com.

Endpoint

POST https://api.mambosms.com/v1/send-sms

Request Parameters

  • message: The intended message to send as an SMS.
  • recipients: The recipients for whom the message is intended (comma-separated).
  • message_category:
    • non_customised: SMS comes from a random contact/number.
    • info: Comes with the INFO word as message ID.
    • customised: Subscribed message from MTN, Airtel, or UTL.
  • sender_id: SMS sender ID (not more than 11 characters).

Example cURL Request


function CallApi_func($method, $url, $data = false, $dataType = 'json', $apiKey = null)
{
    $curl = curl_init();
    
    $headers = array();
    
    switch ($method) 
    {
        case "POST":
            curl_setopt($curl, CURLOPT_POST, 1);
            if ($data) 
            {
                if ($dataType === 'json') 
                {
                    $headers[] = 'Content-Type: application/json';
                    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
                } 
                else 
                {
                    $headers[] = 'Content-Type: multipart/form-data';
                    curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
                }
            }
            break;
        default:
            if ($data) 
            {
                $url = sprintf("%s?%s", $url, http_build_query($data));
            }
    }
    
    curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    
    if ($apiKey) 
    {
        $headers[] = 'Authorization: ' . $apiKey;
    }

    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    
    $result = curl_exec($curl);
    
    if (curl_errno($curl)) {
        $error_msg = curl_error($curl);
    }
    
    curl_close($curl);
    
    if (isset($error_msg)) {
        return array('error' => $error_msg);
    }
    
    return json_decode($result, true);
}

Example Node.js Request


const axios = require('axios');

const url = 'https://api.mambosms.com/v1/send-sms';
const data = {
    message: 'test message',
    recipients: '0756xxxx, 0756xxxx',
    message_category: 'non_customised',
    sender_id: 'test sender id'
};
const apiKey = 'your_api_key';

axios.post(url, data, {
    headers: {
        'Authorization': ` ${apiKey}`,
        'Content-Type': 'application/json'
    }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Example Java Request


import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class ApiExample {
    public static void main(String[] args) {
        try {
            URL url = new URL("https://api.mambosms.com/v1/send-sms");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Authorization", " your_api_key");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);
            
            String jsonInputString = "{ \"message\": \"test message\", \"recipients\": \"0756xxxx, 0756xxxx\", \"message_category\": \"non_customised\", \"sender_id\": \"test sender id\" }";
            
            try(OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);
            }
            
            // Print response code and response
            System.out.println("Response Code: " + conn.getResponseCode());
            // Add response reading logic here
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Example Python Request


import requests

url = 'https://api.mambosms.com/v1/send-sms'
data = {
    'message': 'test message',
    'recipients': '0756xxxx, 0756xxxx',
    'message_category': 'non_customised',
    'sender_id': 'test sender id'
}
headers = {
    'Authorization': ' your_api_key',
    'Content-Type': 'application/json'
}

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

Example Go Request


package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://api.mambosms.com/v1/send-sms"
    data := map[string]string{
        "message": "test message",
        "recipients": "0756xxxx, 0756xxxx",
        "message_category": "non_customised",
        "sender_id": "test sender id",
    }
    
    jsonData, _ := json.Marshal(data)
    
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", " your_api_key")
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    
    defer resp.Body.Close()
    fmt.Println("Response Status:", resp.Status)
    // Add response reading logic here
}

Example Ruby Request


require 'net/http'
require 'json'

url = URI.parse('https://api.mambosms.com/v1/send-sms')
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url.request_uri)
request['Authorization'] = ' your_api_key'
request['Content-Type'] = 'application/json'
request.body = {
    message: 'test message',
    recipients: '0756xxxx, 0756xxxx',
    message_category: 'non_customised',
    sender_id: 'test sender id'
}.to_json

response = http.request(request)
puts response.body

Example C# Request


using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var url = "https://api.mambosms.com/v1/send-sms";
        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("", "your_api_key");
        
        var data = new
        {
            message = "test message",
            recipients = "0756xxxx, 0756xxxx",
            message_category = "non_customised",
            sender_id = "test sender id"
        };
        
        var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync(url, content);
        var responseString = await response.Content.ReadAsStringAsync();
        
        Console.WriteLine(responseString);
    }
}

Successful Response


{
    "statusCode": 201,
    "success": true,
    "messages": [
        "SMS successfully sent to 9 recipients."
    ],
    "data": {
        "recipients_count": 9,
        "message_count": 2,
        "sms_sent": 18,
        "sms_cost": 900,
        "new_balance": 8580,
        "unsupported_contacts_count": 0,
        "unsupported_contacts": []
    }
}

Unsuccessful Response


{
    "statusCode": 401,
    "success": false,
    "messages": [
        "Invalid session"
    ],
    "data": []
}