API Reference

All requests go to the base URL:

https://bulkiemsg.com/api/v1

Authentication

Every request must include your API key. Generate one from your dashboard under Settings → API Keys.

Authorization: Bearer bm_live_your_key_here

X-API-Key: bm_live_your_key_here

Keys look like bm_live_ followed by 64 characters. You can have up to 3 keys, each with its own name, access level and optional IP allowlist, so every app gets its own key and one leak never forces you to change them all.

Security

The API is built so that a mistake on one side does not become a loss on the other.

Checklist

• Keep the key in an environment variable or secret store, never in code you commit.
• Use one key per app and name it, so you know which one to revoke.
• Add your server's IP address to the allowlist.
• Use Read-only keys wherever sending is not needed.
• Always call the API over HTTPS, so your key is never sent in the clear.

Quick Start

curl -X POST https://bulkiemsg.com/api/v1/sms/send \
  -H "Authorization: Bearer bm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "YourBrand",
    "message":   "Hello from BulkieMsg!",
    "to":        ["233201234567"]
  }'

$ch = curl_init('https://bulkiemsg.com/api/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer bm_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'sender_id' => 'YourBrand',
        'message'   => 'Hello from BulkieMsg!',
        'to'        => ['233201234567'],
    ]),
]);
$result = json_decode(curl_exec($ch), true);

import requests

r = requests.post(
    "https://bulkiemsg.com/api/v1/sms/send",
    headers={"Authorization": "Bearer bm_live_YOUR_KEY"},
    json={
        "sender_id": "YourBrand",
        "message":   "Hello from BulkieMsg!",
        "to":        ["233201234567"],
    }
)
print(r.json())

const res = await fetch('https://bulkiemsg.com/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bm_live_YOUR_KEY',
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    sender_id: 'YourBrand',
    message:   'Hello from BulkieMsg!',
    to:        ['233201234567'],
  }),
});
console.log(await res.json());

Send SMS

curl -X POST https://bulkiemsg.com/api/v1/sms/send \
  -H "Authorization: Bearer bm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "MyBrand",
    "message":   "Your OTP is 482910. Valid 5 minutes.",
    "to":        ["233201234567", "233271234567"]
  }'

$ch = curl_init('https://bulkiemsg.com/api/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer bm_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'sender_id' => 'MyBrand',
        'message'   => 'Your OTP is 482910.',
        'to'        => ['233201234567', '233271234567'],
    ]),
]);
$res = json_decode(curl_exec($ch), true);

import requests

r = requests.post(
    "https://bulkiemsg.com/api/v1/sms/send",
    headers={"Authorization": "Bearer bm_live_YOUR_KEY"},
    json={
        "sender_id": "MyBrand",
        "message":   "Your OTP is 482910.",
        "to":        ["233201234567", "233271234567"],
    }
)
print(r.json())

const res = await fetch('https://bulkiemsg.com/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bm_live_YOUR_KEY',
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    sender_id: 'MyBrand',
    message:   'Your OTP is 482910.',
    to:        ['233201234567', '233271234567'],
  }),
});
console.log(await res.json());

{ "success": true, "message": "Queued 2 recipient(s) for delivery.", "campaign_id": 1042, "recipients": 2, "status": "queued" }

{ "success": false, "error": "Insufficient credits. Need 5, have 2." }

Check Balance

curl https://bulkiemsg.com/api/v1/sms/balance \
  -H "Authorization: Bearer bm_live_YOUR_KEY"

$ch = curl_init('https://bulkiemsg.com/api/v1/sms/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer bm_live_YOUR_KEY'],
]);
$res = json_decode(curl_exec($ch), true);

import requests
r = requests.get(
    "https://bulkiemsg.com/api/v1/sms/balance",
    headers={"Authorization": "Bearer bm_live_YOUR_KEY"}
)
print(r.json())

const res = await fetch('https://bulkiemsg.com/api/v1/sms/balance', {
  headers: { 'Authorization': 'Bearer bm_live_YOUR_KEY' }
});
console.log(await res.json());

{ "success": true, "sms_credits": 500 }

Sender IDs

All SMS must be sent with an approved Sender ID. Submit one for review — approval typically takes up to 48 hours.

curl -X POST https://bulkiemsg.com/api/v1/sms/sender_ids \
  -H "Authorization: Bearer bm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sender_id": "MyBrand" }'

{ "success": true, "message": "Sender ID submitted for review." }

curl https://bulkiemsg.com/api/v1/sms/sender_ids \
  -H "Authorization: Bearer bm_live_YOUR_KEY"

{
  "success": true,
  "sender_ids": [
    { "id": 42, "sender_id": "MyBrand", "status": "approved" }
  ]
}

WhatsApp — Send Message

curl -X POST https://bulkiemsg.com/api/v1/whatsapp/send \
  -H "Authorization: Bearer bm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to":      "233201234567",
    "message": "Your appointment is tomorrow at 10am."
  }'

{ "success": true, "message": "Message sent to 1 recipient(s)." }

WhatsApp — Link Device

curl -X POST https://bulkiemsg.com/api/v1/whatsapp/session \
  -H "Authorization: Bearer bm_live_YOUR_KEY"

{
  "success":    true,
  "qr_code":    "data:image/png;base64,...",
  "expires_in": 60
}

Safe Retries

If your request times out you cannot tell whether the messages were sent. Retrying blindly could send them twice. Add an Idempotency-Key header to POST /sms/send and a retry returns the first answer instead of sending again.

curl -X POST https://bulkiemsg.com/api/v1/sms/send \
  -H "Authorization: Bearer bm_live_your_key_here" \
  -H "Idempotency-Key: order-1001-confirmation" \
  -H "Content-Type: application/json" \
  -d '{"sender_id":"MyBrand","to":"233201234567","message":"Your order is confirmed"}'

• Use one new value per message you mean to send, such as an order number or a UUID. Letters, numbers and . _ : -, 8 to 80 characters.
• A repeat with the same key and the same body returns the original response with the header Idempotent-Replay: true. Nothing is sent or charged.
• The same key with a different body returns 422. A repeat while the first request is still running returns 409.
• A request that failed (for example 402 not enough credits) frees its key, so you can retry it after fixing the problem.
• Keys are remembered for 24 hours.

Rate Limits

Limits are counted per API key, per minute:

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. When you go over, you get 429 with a Retry-After header (seconds). Wait that long, then retry.

{ "success": false, "error": "Rate limit exceeded (30 requests per minute). Retry in 23s." }

Errors & Codes

All errors return "success": false and an error string. Use the HTTP status code to categorise the failure.

Common error messages

// Missing key
{ "success": false, "error": "API key is required." }

// Not enough credits
{ "success": false, "error": "Insufficient credits. Need 10, have 3." }

// Sender ID not approved
{ "success": false, "error": "Sender ID 'MyBrand' is not approved." }