Introduction

The scope of this Document is to illustrate the technical requirements required in order for clients to integrate with MAMBO SMS API to enable sending Single and Bulk SMS. All systems should be able to interface with MAMBO SMS API following instructions provided in this Document.

POST https://mambosms.co.tz/api/v1

Authentication

Mambo SMS Authentication is done using Token-based authentication. You need to include your Bearer Token in the Authorization header of your requests to access the API endpoints.

Authorization: Bearer YOUR_BEARER_TOKEN

Send Single SMS

Use this endpoint to send a single SMS message to one recipient.

Endpoint

POST {base_url}/sms/single

Headers

Authorization: Bearer BEARER_TOKEN
Content-Type: application/json

Request Body

{ "sender_id": "YOUR_SENDER_ID", "message": "Hello, this is a test message.", "mobile": "0713XXXXXX" }

Success Response

{ "status": "success", "message_id": "123456789" }

cURL Example

curl -X POST https://mambosms.co.tz/api/v1/sms/single \ -H "Authorization: Bearer BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "mobile": "0713268534", "message": "Hello World", "sender_id": "YOUR_SENDER_ID" }'

Send Bulk SMS

Send a message to multiple recipients in a single request. All Mobile Numbers has to be uploaded in a Mambo SMS Portal.

Endpoint

POST {base_url}/sms/bulk

Request Body

{ "sender_id": "YOUR_SENDER_ID", "message": "Hello, this is a test message.", }

Success Response

{ "status": "success", "message_id": "123456789" }

Notes

Maximum 1,000 recipients per request
All phone numbers must be in format 0713XXXXX
Messages are queued and processed instantly

Check Balance

Retrieve your current SMS credit balance.

Endpoint

GET {base_url}/sms/balance

Headers

Authorization: Bearer BEARER_TOKEN

Success Response

{ "success": true, "balance": { "id": 1, "company_id": "2", "initial_balance": 500, "available_balance": 495, "created_at": "2025-02-03T19:12:44.000000Z", "updated_at": "2025-02-04T07:32:12.000000Z" } }

cURL Example

curl -X GET https://mambosms.com/api/v1/sms/balance \ -H "Authorization: Bearer BEARER_TOKEN"

Errors

The API uses standard HTTP status codes and structured error responses.

Error Format

{ "success": false, "error": { "type": "validation_error", "code": "INVALID_PHONE_NUMBER", "message": "Phone number format is invalid", "param": "to", "request_id": "req_123456" } }

Common Error Codes

Code	Description
400	Bad Request
401	Unauthorized
422	Validation Error
429	Rate Limit Exceeded
500	Server Error

Common API Errors

INVALID_PHONE_NUMBER
INSUFFICIENT_BALANCE
MESSAGE_TOO_LONG
INVALID_API_KEY
RATE_LIMIT_EXCEEDED