BulkSMS API

Quickstart

Your account needs approved KYC, an approved sender ID and credits. Then:

1. 1Create an API key in the portal: API keys.
2. 2Send a message. Examples use our default sender BULK SMS TZ — use your own approved sender ID.

curl -X POST https://bulksms.oasistech.co.tz/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp-48213-1" \
  -d '{"to": "+255712345678", "sender": "BULK SMS TZ", "message": "Your BulkSMS code is 482913."}'

import { randomUUID } from "node:crypto";

const res = await fetch("https://bulksms.oasistech.co.tz/v1/sms", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({ to: "+255712345678", sender: "BULK SMS TZ", message: "Your BulkSMS code is 482913." }),
});
console.log(res.status, await res.json());

<?php
$ch = curl_init("https://bulksms.oasistech.co.tz/v1/sms");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_TIMEOUT        => 180,
  CURLOPT_HTTPHEADER     => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json",
                             "Idempotency-Key: " . bin2hex(random_bytes(16))],
  CURLOPT_POSTFIELDS     => json_encode(["to" => "+255712345678", "sender" => "BULK SMS TZ",
                                         "message" => "Your BulkSMS code is 482913."]),
]);
echo curl_exec($ch);

import requests, uuid

r = requests.post("https://bulksms.oasistech.co.tz/v1/sms",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": str(uuid.uuid4())},
    json={"to": "+255712345678", "sender": "BULK SMS TZ", "message": "Your BulkSMS code is 482913."},
    timeout=180)
print(r.status_code, r.json())

Authentication

Send your key on every request: Authorization: Bearer YOUR_API_KEY. Keys are shown once, expire after 365 days by default, and can be limited to listed IP addresses.

/api/... works too and is the same endpoint as /v1/.... There is no /sms/send.

Send SMS

One request sends one message to one or many numbers.

Several recipients, personalised

{
  "to": [
    {"number": "0712345678", "params": {"name": "Amina"}},
    {"number": "0754901234", "params": {"name": "Juma"}}
  ],
  "sender": "BULK SMS TZ",
  "message": "Habari {name}, your order is ready."
}

Responses

One recipient — 200

{
  "number": "+255712345678",
  "status": "sent",
  "sms_log_id": 123456,
  "credits_used": 1,
  "sms_response": {"msg_id": "1880000001", "number": "255712345678", "str_response": "Send Successful"},
  "provider_ref": "1880000001",
  "credit_info": {"total_recipients": 1, "credits_charged": 1, "balance_after": 6, "sandbox": false}
}

Several recipients: {"status", "sms_log_id", "recipients": [ ...one object per number... ], "credit_info"}. A failed recipient has "status": "failed" and an error.

More than 10,000 recipients — 202

{
  "status": "processing",
  "background": true,
  "sms_log_id": 123460,
  "recipients_count": 12000,
  "background_notice": "Large send accepted: 12,000 recipients are going out now. ...",
  "credit_info": {"total_recipients": 12000, "credits_charged": 12000, "balance_after": 3000, "sandbox": false}
}

Answered at once; the list goes out right after. Follow sms_log_id in GET /v1/logs or with webhooks. Refused numbers are refunded.

Idempotency-Key

Send one with every message, so a retry can never send twice.

Timeout or network error? Retry with the same key. Allow up to 180 seconds for a send.

Errors

Errors return {"error": "..."}, sometimes with a hint. Nothing is sent or charged.

Balance

{"credits": 1234}

Messages

Your sent messages, newest first. Filters: page, limit (max 100), search, status, from, to (YYYY-MM-DD).

{
  "page": 1, "limit": 50, "total": 1, "total_pages": 1,
  "data": [
    {"id": 123456, "recipient": "+255712345678", "sender": "BULK SMS TZ", "message": "Your BulkSMS code is 482913.",
     "status": "sent", "credits_used": 1, "segments": 1, "source": "api", "created_at": "2026-10-08 09:15:02"}
  ]
}

id is the sms_log_id from the send. A send to several numbers is one row; its per-number results are in recipients_json.

Sender IDs

Your sender ID requests. Request new ones in the portal.

{"sender_ids": [{"id": 42, "sender": "BULK SMS TZ", "status": "approved", "live": 1, "created_at": "2026-10-01 10:00:00"}],
 "page": 1, "limit": 25, "total": 1, "total_pages": 1}

Webhooks

Get an HTTP POST on your server when a message is sent or fails.

POST /v1/webhooks?action=create
{"url": "https://example.com/bulksms-hook", "events": "sms.delivered,sms.pending,sms.failed,credits.low"}

→ 201 {"id": 7, "url": "https://example.com/bulksms-hook", "events": "...", "secret": "save-this-secret"}

Payload

{"id": "evt_3f9c1a2b7d4e5f6a7b8c9d0e", "type": "sms.delivered", "created_at": "2026-10-08T09:15:03+03:00", "tenant_id": 101,
 "data": {"sms_log_id": 123456, "recipient": "+255712345678", "sender": "BULK SMS TZ", "status": "sent",
          "credits_used": 1, "provider_ref": "1880000001", "error": null}}

Verify the signature

Header X-BulkSMS-Signature = HMAC-SHA256 (hex) of the raw body, keyed with your secret.

const crypto = require("crypto");
const sig = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.get("X-BulkSMS-Signature") || ""));

$raw = file_get_contents('php://input');
$ok  = hash_equals(hash_hmac('sha256', $raw, SECRET), $_SERVER['HTTP_X_BULKSMS_SIGNATURE'] ?? '');

import hmac, hashlib
ok = hmac.compare_digest(hmac.new(SECRET.encode(), raw_body, hashlib.sha256).hexdigest(),
                         request.headers.get("X-BulkSMS-Signature", ""))

Answer 2xx within 10 seconds. Otherwise we retry after 1 min, 5 min, 30 min, 2 h and 12 h. Use X-BulkSMS-Event-Id to skip duplicates.

Limits & cost

AI assistants

Give your coding assistant (Claude, ChatGPT, Copilot, Cursor) one of these files — they describe the whole API.

Changelog

• 2026-10-08 — Over 10,000 recipients: answered at once (202, background: true). Allow 180 s for a send (was 100). Webhooks now go out after the reply.
• 2026-10-08 — Same Idempotency-Key with a different request → 422. Keys 1–64 characters. Unconfirmed sends answer 202 pending and fire sms.pending. Sends to several numbers return sms_log_id.
• 2026-09 — A repeated Idempotency-Key returns the original response. Limit raised to 300 requests per minute.