Developers

API Documentation

Send SMS from your own application over a plain JSON REST API. No SDK required — if your language can make an HTTPS request, it can send messages.

Introduction

The Bulk-sms.ng API lets you send bulk SMS and check your credit balance from your own systems. Every endpoint takes a POST with a JSON body and returns JSON.

There are two SMS routes, and the one you pick matters:

  • Promotional — marketing and campaign traffic. Subject to DND filtering and to the delivery window described below.
  • Transactional — OTPs, alerts and receipts. For messages a customer is waiting for.

Authentication

There is no separate API key. Every request carries the email address and password of your Bulk-sms.ng account in the JSON body.

Call the API from your server, never from a browser or mobile app. Because the credentials are your account password, anything that ships them to a client device exposes the whole account. Keep them in server-side configuration or a secrets manager.
Credentials, sent with every request 
{
  "email": "your_account_email",
  "password": "your_account_password"
}

Promotional SMS

Base URL https://account.bulk-sms.ng/api/promotional

POST /send

Send a promotional message to one or more recipients.

Body parameters

Field Required Description
email Yes Your account email address.
password Yes Your account password.
message Yes The message body.
recipient Yes Comma-separated MSISDNs in international format, e.g. 2348012345678,2348098765432. Maximum 100 per request.
senderid Yes An approved sender ID on your account.
smsgateway Yes Route selector, e.g. "1". Promotional only.

Request

cURL 
curl -X POST https://account.bulk-sms.ng/api/promotional/send \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your_account_email",
    "password": "your_account_password",
    "message": "Flash sale! 20% off everything until midnight.",
    "recipient": "2348012345678,2348098765432",
    "senderid": "MyBrand",
    "smsgateway": "1"
  }'

Response

200 OK 
{
  "status": "success",
  "statusCode": 600,
  "messageid": "SMS123456",
  "message": "Message has been processed"
}

POST /balance

Retrieve your current SMS credit balance.

Request

cURL 
curl -X POST https://account.bulk-sms.ng/api/promotional/balance \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your_account_email",
    "password": "your_account_password"
  }'

Response

200 OK 
{
  "balance": 3500.75
}

Transactional SMS

Base URL https://account.bulk-sms.ng/api/transactional/v2

POST /send

Send a transactional message — OTPs, alerts and receipts. Identical to the promotional body, except there is no smsgateway field.

Request

cURL 
curl -X POST https://account.bulk-sms.ng/api/transactional/v2/send \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your_account_email",
    "password": "your_account_password",
    "message": "Your verification code is 620381. It expires in 5 minutes.",
    "recipient": "2348012345678",
    "senderid": "MyBrand"
  }'

Response

200 OK 
{
  "status": "success",
  "statusCode": 600,
  "messageid": "SMS123456",
  "message": "Message sent successfully",
  "balance": 35.12
}

Email API

Coming soon. The email endpoints are not yet available. Talk to us if you would like early access.

Status Codes

Every response carries a statusCode. A send is only accepted on 600 or 609.

Code Meaning
600 Message sent successfully
601 Authentication failed
602 Invalid request
603 Unauthorised user
604 Insufficient balance
605 Error parameters — a required field is missing or empty
606 Internal error, try later
607 Invalid number format, invalid recipient count, or more than 100 recipients
608 Invalid authorisation for this route
609 Accepted but deferred — see Delivery windows below

Rate Limits & Delivery Windows

  • Maximum 100 recipients per request. Beyond that you get 607.
  • Abuse may result in API suspension.
Promotional traffic is held overnight. Nigerian telco policy blocks promotional delivery between 7:00pm and 8:00am. A promotional send in that window is still accepted and charged, but it is queued and released at 8:30am rather than dispatched immediately. You can detect this: the response returns statusCode 609 with "deferred": true and a scheduledfor timestamp. Transactional traffic is not affected.

Support

Stuck on an integration? Email developers@bulk-sms.ng or send us a message and we will get back to you.

Create a free account

WhatsApp Support
Need help? Chat with us live!