Developer Docs

Introduction

The Mesaj API is a RESTful HTTP API for sending Bulk SMS, Voice OTP, WhatsApp, and IVR messages across Nigerian networks. All requests are made over HTTPS to a single base host.

# Base URL
https://api.mesaj.cloud:25274

Authentication

Every request needs your API key in the request headers. Find your key on the dashboard under Settings → API Keys.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Send a Bulk SMS

Send to a single recipient or thousands at once using the same endpoint. All recipient-specific fields go inside the data object — a request without this wrapper key will be rejected.

POST /client/sms/send/bulk

// request body
{
  "data": {
    "sender_id": "MESAJ",
    "message": "Your OTP is 8421. Valid for 5 mins.",
    "type": "TRANSACTIONAL",
    "recipients": [
      "2348031234567",
      "2347051234567"
    ]
  }
}

Response

{
  "status": "success",
  "message_id": "msj_8f02ac91",
  "accepted": 2,
  "rejected": 0
}

info

A common integration error is sending to /client/sms/send/ without the bulk suffix — that path expects a single recipient, not an array, and will return a payload validation error.

Sender IDs

An alpha-numeric Sender ID (up to 11 characters, e.g. MESAJ) is registered per network — MTN, Globacom, Airtel, and 9mobile each approve independently. Registration typically requires a signed Letter of Authorization (LOA) and takes 24–72 hours per network.

Network	Typical approval time
MTN	24–48 hrs
Globacom	24–72 hrs
Airtel	24–48 hrs
9mobile	48–72 hrs

Message types & DND

The type field controls how a message is filtered against Nigeria's Do-Not-Disturb (DND) registry.

TRANSACTIONAL

OTPs, account alerts, and service notices. Bypasses DND filtering — required for time-sensitive delivery.

PROMOTIONAL

Marketing and offers. Subject to DND filtering — numbers registered against unsolicited marketing will not receive these.

Delivery webhooks

Configure a callback URL on your dashboard to receive delivery receipts as they happen, per recipient.

// POST to your callback URL
{
  "message_id": "msj_8f02ac91",
  "recipient": "2348031234567",
  "network": "MTN",
  "status": "DELIVERED",
  "timestamp": "2026-06-26T14:02:11Z"
}

Errors

Mesaj uses standard HTTP status codes. Error bodies always include a machine-readable code and a human-readable message.

Status	Meaning
400	Malformed payload — usually a missing data wrapper or invalid JSON syntax.
401	Missing or invalid API key.
404	Wrong endpoint path — check single vs. bulk send routes.
422	Sender ID not approved on one or more target networks.
429	Rate limit exceeded — back off and retry.