MegaSMS
Sign in Create account

MegaSMS Developer Platform ยท API v1

SMS integration without the guesswork.

Send transactional and bulk SMS, track each request, and monitor your balance through a small, predictable JSON API.

Base URLhttps://megasms.co.tz/api/v1
P Download Postman collection Local environment

Introduction

Overview

The MegaSMS API is a REST-style JSON API for sending SMS from your own systems. Every request is isolated to your vendor account, and only sender IDs approved for that account can be used.

API format: Send request bodies as application/json. All responses, including errors, are JSON.

Before you begin

  1. Create or sign in to an active MegaSMS vendor account.
  2. Request a sender ID and wait for it to be approved.
  3. Purchase SMS units.
  4. Open API Tokens in your vendor portal and create a token.

Security

Authentication

Authenticate every API request using an API token in the HTTP Authorization header.

HTTP header
Authorization: Bearer ms_live_your_token_here
Keep tokens secret. A complete token is displayed only once when it is created. Never place it in browser-side JavaScript, public repositories, URLs, or support messages.

Permissions

PermissionAllows
messages:sendSubmit new SMS requests.
messages:readRead message request and recipient statuses.
balance:readRead the vendor SMS balance and current rate.

First request

Quickstart

Replace the example token, phone number, and sender ID with values from your vendor account.

Using Postman? Download the preconfigured collection and local environment above, import both files, select MegaSMS Local, and add your token to the api_token environment variable. The send request automatically saves its request_id for the status request.
cURL
curl -X POST "https://megasms.co.tz/api/v1/messages" \
  -H "Authorization: Bearer ms_live_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "255712345678",
    "sender_id": "MEGASMS",
    "message": "Your verification code is 482913"
  }'

PHP

PHP 8+
$payload = json_encode([
    'to' => '255712345678',
    'sender_id' => 'MEGASMS',
    'message' => 'Your verification code is 482913',
]);

$curl = curl_init('https://megasms.co.tz/api/v1/messages');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('MEGASMS_API_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($curl);

Node.js

JavaScript
const response = await fetch('https://megasms.co.tz/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MEGASMS_API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '255712345678',
    sender_id: 'MEGASMS',
    message: 'Your verification code is 482913'
  })
});

const result = await response.json();

API reference

Send messages

POST/messages

Send the same message to one or as many as 100 unique recipients.

Request body

FieldTypeRequiredDescription
tostring | arrayYesOne Tanzanian number or an array of up to 100 numbers.
sender_idstringYesAn approved, active sender ID belonging to your account. Maximum 11 characters.
messagestringYesMessage content, up to 1,600 characters.
JSON request
{
  "to": ["255712345678", "0712345679"],
  "sender_id": "MEGASMS",
  "message": "Your order is ready for collection."
}

Success response

HTTP 200
{
  "success": true,
  "data": {
    "request_id": "4be7e780-f127-4da4-8d93-63d1c5bd0ea0",
    "status": "completed",
    "encoding": "gsm",
    "segments_per_message": 1,
    "total_recipients": 2,
    "successful": 2,
    "failed": 0,
    "units_charged": 2,
    "balance": 998,
    "messages": [
      {"id": "481", "to": "255712345678", "status": "delivered", "segments": 1}
    ]
  }
}

Save request_id. It is the stable identifier used to retrieve this request later.

API reference

Retrieve message status

GET/messages/{request_id}

Returns the request summary and the status of every recipient. Requests from other vendors are never visible.

cURL
curl "https://megasms.co.tz/api/v1/messages/4be7e780-f127-4da4-8d93-63d1c5bd0ea0" \
  -H "Authorization: Bearer ms_live_your_token_here"
Delivery webhooks are not currently available. Poll this endpoint when your application needs the latest stored status.

API reference

Retrieve balance

GET/balance

Returns available SMS units, the account rate per segment, and currency.

HTTP 200
{
  "success": true,
  "data": {
    "balance": 998,
    "rate_per_segment": 25,
    "currency": "TZS"
  }
}

Formatting

Phone numbers

MegaSMS accepts valid Tanzanian mobile numbers. International format is recommended:

  • Recommended: 255712345678
  • Also accepted: 0712345678 or +255 712 345 678
  • The normalized number must begin with 2556 or 2557.

Duplicate numbers in the same request are automatically removed.

Billing

Segments and SMS units

Billing is based on message segments per recipient. One successful segment consumes one SMS unit; failed sends are refunded automatically.

EncodingSingle segmentMultipart segment
GSM / basic LatinUp to 160 characters153 characters each
Unicode / UCS-2Up to 70 characters67 characters each

Example: a two-segment message sent successfully to 10 recipients consumes 20 SMS units.

Troubleshooting

Errors

Error responses use one consistent structure:

JSON error
{
  "success": false,
  "error": {
    "code": "invalid_sender_id",
    "message": "The sender ID is not approved and active for this vendor."
  }
}
HTTPCodeMeaning
400invalid_jsonThe request body is missing or is not valid JSON.
401unauthenticatedThe token is missing, invalid, expired, or revoked.
402insufficient_balanceThe vendor does not have enough SMS units.
403forbiddenThe token lacks the required permission.
403vendor_inactiveThe vendor account is not active.
404not_foundThe request ID does not exist for this vendor.
422validation_errorOne or more request fields are invalid.
422invalid_sender_idThe sender ID is not approved and active.
500internal_errorThe request could not be processed. Retry safely after checking status.

Production checklist

Security practices

  • Create separate tokens for development, staging, and production.
  • Grant only the permissions each integration needs.
  • Store tokens in environment variables or a secrets manager.
  • Set an expiry date and rotate tokens regularly.
  • Revoke a token immediately if it may have been exposed.
  • Use the production API over HTTPS only.