Mambo SMS API

Send SMS messages programmatically using the Mambo SMS API.

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

Once you have an account, log in and navigate to API Settings via the sidebar. Generate your API key — you'll pass it in the Authorization header on every request.

Support: +256-775-508-171  |  info@mambosms.com

Authentication

All requests to the API must include your API key in the request header.

Header

Authorization: your_api_key

You can find and regenerate your API key from the API Settings page after logging in.

Send SMS

Send an SMS message to one or more recipients.

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

Request parameters

Parameter Type Description
messagerequired string The SMS message content to send.
recipientsrequired string Comma-separated list of recipient phone numbers.
message_categoryrequired string non_customised — from a random number.
info — prefixed with INFO sender ID.
customised — registered sender ID (MTN / Airtel / UTL).
sender_idrequired string Your SMS sender ID. Maximum 11 characters.

Code examples

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);
    curl_close($curl);

    return json_decode($result, true);
}

// Usage
$response = CallApi_func('POST', 'https://api-mongolia.mambosms.com/v1/send-sms', [
    'message'          => 'Hello from Mambo SMS',
    'recipients'       => '0756xxxxxx, 0772xxxxxx',
    'message_category' => 'non_customised',
    'sender_id'        => 'MamboSMS'
], 'json', 'your_api_key');
const axios = require('axios');

const url = 'https://api-mongolia.mambosms.com/v1/send-sms';
const data = {
    message: 'Hello from Mambo SMS',
    recipients: '0756xxxxxx, 0772xxxxxx',
    message_category: 'non_customised',
    sender_id: 'MamboSMS'
};

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

url = 'https://api-mongolia.mambosms.com/v1/send-sms'
data = {
    'message': 'Hello from Mambo SMS',
    'recipients': '0756xxxxxx, 0772xxxxxx',
    'message_category': 'non_customised',
    'sender_id': 'MamboSMS'
}
headers = {
    'Authorization': 'your_api_key',
    'Content-Type': 'application/json'
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class SendSms {
    public static void main(String[] args) throws Exception {
        URL url = new URL("https://api-mongolia.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 body = "{\"message\":\"Hello from Mambo SMS\","
                    + "\"recipients\":\"0756xxxxxx, 0772xxxxxx\","
                    + "\"message_category\":\"non_customised\","
                    + "\"sender_id\":\"MamboSMS\"}";

        try (OutputStream os = conn.getOutputStream()) {
            os.write(body.getBytes("utf-8"));
        }
        System.out.println("Response: " + conn.getResponseCode());
    }
}
package main

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

func main() {
    url  := "https://api-mongolia.mambosms.com/v1/send-sms"
    data := map[string]string{
        "message":          "Hello from Mambo SMS",
        "recipients":       "0756xxxxxx, 0772xxxxxx",
        "message_category": "non_customised",
        "sender_id":        "MamboSMS",
    }

    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("Status:", resp.Status)
}
require 'net/http'
require 'json'

url     = URI.parse('https://api-mongolia.mambosms.com/v1/send-sms')
http    = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url.request_uri)
request['Authorization'] = 'your_api_key'
request['Content-Type']  = 'application/json'
request.body = {
    message:          'Hello from Mambo SMS',
    recipients:       '0756xxxxxx, 0772xxxxxx',
    message_category: 'non_customised',
    sender_id:        'MamboSMS'
}.to_json

response = http.request(request)
puts response.body
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "your_api_key");

        var data = new {
            message          = "Hello from Mambo SMS",
            recipients       = "0756xxxxxx, 0772xxxxxx",
            message_category = "non_customised",
            sender_id        = "MamboSMS"
        };

        var content  = new StringContent(JsonConvert.SerializeObject(data), Encoding.UTF8, "application/json");
        var response = await client.PostAsync("https://api-mongolia.mambosms.com/v1/send-sms", content);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Successful response

200 OK
{
    "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": []
    }
}

Balance inquiry

Retrieve the current SMS credit balance for your account.

GET https://api-mongolia.mambosms.com/v1/accounts/balance

Request headers

Header Type Description
Authorizationrequired string Your API key. Passed as a plain value — no Bearer prefix needed.
This endpoint takes no request body — authentication is handled entirely via the Authorization header. No query parameters are required.

Code examples

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://api-mongolia.mambosms.com/v1/accounts/balance',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPGET        => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: your_api_key'
    ]
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo "Balance: " . $result['data']['balance'];
const axios = require('axios');

const url = 'https://api-mongolia.mambosms.com/v1/accounts/balance';

axios.get(url, {
    headers: {
        'Authorization': 'your_api_key'
    }
})
.then(response => {
    console.log('Balance:', response.data.data.balance);
})
.catch(error => console.error(error));
import requests

url     = 'https://api-mongolia.mambosms.com/v1/accounts/balance'
headers = {
    'Authorization': 'your_api_key'
}

response = requests.get(url, headers=headers)
result   = response.json()
print('Balance:', result['data']['balance'])
import java.net.HttpURLConnection;
import java.net.URL;

public class BalanceInquiry {
    public static void main(String[] args) throws Exception {
        URL url = new URL("https://api-mongolia.mambosms.com/v1/accounts/balance");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        conn.setRequestProperty("Authorization", "your_api_key");

        int status = conn.getResponseCode();
        System.out.println("Response: " + status);
    }
}
package main

import (
    "fmt"
    "net/http"
)

func main() {
    url := "https://api-mongolia.mambosms.com/v1/accounts/balance"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "your_api_key")

    client  := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    fmt.Println("Status:", resp.Status)
}
require 'net/http'
require 'json'

url     = URI.parse('https://api-mongolia.mambosms.com/v1/accounts/balance')
http    = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url.request_uri)
request['Authorization'] = 'your_api_key'

response = http.request(request)
result   = JSON.parse(response.body)
puts "Balance: #{result['data']['balance']}"
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "your_api_key");

        var response = await client.GetAsync(
            "https://api-mongolia.mambosms.com/v1/accounts/balance");

        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Successful response

200 OK
{
    "statusCode": 200,
    "success": true,
    "messages": ["Balance fetched successfully"],
    "data": {
        "name": "Robert Muhereza",
        "contact": "0756431579",
        "email": null,
        "balance": 2335
    }
}

Error responses

401 Unauthorized
// Missing or invalid API key
{
    "statusCode": 401,
    "success": false,
    "messages": ["Invalid session"],
    "data": []
}

// Account inactive or suspended
{
    "statusCode": 200,
    "success": false,
    "messages": ["Account is inactive or suspended. Contact support on +256 775 508171."],
    "data": []
}

Response format

All API responses follow a consistent JSON structure.

FieldTypeDescription
statusCode integer HTTP-style status code (200, 201, 400, 401, etc.).
success boolean true if the request succeeded, false otherwise.
messages array Human-readable status or error messages.
data object / array Response payload. Empty array [] on failure.

Error codes

Common status codes returned by the API.

CodeMeaning
200Request processed. Check success field for outcome.
201Resource created or action completed successfully.
400Bad request — missing or invalid parameters.
401Unauthorized — invalid or missing API key.
405Method not allowed — wrong HTTP method used.
500Server error — contact support if this persists.