Mambo SMS API Documentation

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 a client account.

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

Request parameters

Parameter	Type	Description
usernamerequired	string	Your registered phone number or email address.
passwordrequired	string	Your account password.

This endpoint does not require an API key — it authenticates using your account credentials directly.

Code examples

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://api-mongolia.mambosms.com/v1/accounts/balance',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'username' => '0756xxxxxx',   // phone number or email
        'password' => 'your_password'
    ])
]);

$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';
const data = {
    username: '0756xxxxxx',   // phone number or email
    password: 'your_password'
};

axios.post(url, data, {
    headers: { 'Content-Type': 'application/json' }
})
.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'
data = {
    'username': '0756xxxxxx',   # phone number or email
    'password': 'your_password'
}

response = requests.post(url, json=data)
result   = response.json()
print('Balance:', result['data']['balance'])

import java.io.OutputStream;
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("POST");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setDoOutput(true);

        String body = "{\"username\":\"0756xxxxxx\",\"password\":\"your_password\"}";

        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/accounts/balance"
    data := map[string]string{
        "username": "0756xxxxxx",
        "password": "your_password",
    }

    jsonData, _ := json.Marshal(data)
    req, _      := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    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/accounts/balance')
http    = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url.request_uri)
request['Content-Type'] = 'application/json'
request.body = {
    username: '0756xxxxxx',
    password: 'your_password'
}.to_json

response = http.request(request)
result   = JSON.parse(response.body)
puts "Balance: #{result['data']['balance']}"

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();
        var data   = new { username = "0756xxxxxx", password = "your_password" };

        var content  = new StringContent(JsonConvert.SerializeObject(data), Encoding.UTF8, "application/json");
        var response = await client.PostAsync(
            "https://api-mongolia.mambosms.com/v1/accounts/balance", content);

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

Successful response

200 OK

{
    "statusCode": 200,
    "success": true,
    "messages": ["Balance fetched successfully"],
    "data": {
        "client_id": 42,
        "name": "Jane Doe",
        "contact": "0756xxxxxx",
        "email": "jane@example.com",
        "balance": 12500
    }
}

Error responses

200 (failure)

// Invalid credentials
{
    "statusCode": 200,
    "success": false,
    "messages": ["Invalid credentials"],
    "data": []
}

// Account suspended
{
    "statusCode": 200,
    "success": false,
    "messages": ["Account suspended due to too many failed attempts. Contact support."],
    "data": []
}

// Account inactive
{
    "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.

Field	Type	Description
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.

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