Bulkit
Register

Send Bulk SMS

Send SMS messages to multiple recipients simultaneously using your approved sender name.

Last updated · Markdown version

Use the bulk SMS endpoint to deliver messages to multiple recipients in a single API call.

It is suitable for:

  • batch notifications
  • marketing campaigns and broadcasts
  • operational announcements
  • multiple recipient alerts

Endpoint

HTTP
POST /api/v2/messages/sms/bulk

Authorization

Authenticate using your API token in the Authorization HTTP header:

HTTP
Authorization: Bearer <your_api_token>
Content-Type: application/json

Backward Compatibility: Legacy X-API-Key and X-API-Secret headers, as well as credentials passed in the JSON body or query parameters, continue to be supported.

Request Format

Instead of remembering a long UUID sender_id, you can simply supply your sender ID name directly via "sender":

JSON
{
  "sender": "BULK_IT",
  "mobiles": [
    "254700000001",
    "254733000002"
  ],
  "message": "Hello, thank you for being a valued customer!"
}

Sender Flexibility & Strict Authorization: You can pass your alphanumeric sender name in "sender" (e.g. "BULK_IT" or "YOUR_BRAND"). If you have existing integrations using "sender_id" with a UUID or numeric ID, those continue to work.

Strict Authorization: Senders are strictly verified against your account. If you pass an unassigned, unapproved, inactive, or mistyped sender ID or name, the API returns 400 Bad Request (Invalid sender ID). The system never silently defaults to BULK_IT unless explicitly requested.

Scheduled Bulk SMS

To schedule a broadcast for future delivery, pass an ISO 8601 timestamp in scheduled_at:

JSON
{
  "sender": "BULK_IT",
  "mobiles": [
    "254700000001",
    "254733000002"
  ],
  "message": "Flash sale starts at 10:00 AM!",
  "scheduled_at": "2026-03-10T10:00:00+03:00"
}

Code Examples

cURL / Bash
curl -X POST "https://api.bulkitsms.com/api/v2/messages/sms/bulk" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "BULK_IT",
    "mobiles": [
      "254700000001",
      "254733000002"
    ],
    "message": "Hello! Your monthly statement is ready for viewing."
  }'

Parameters

ParameterRequiredTypeDescription
senderYesstringApproved sender ID name assigned to your account (e.g. BULK_IT or YOUR_BRAND).
mobilesYesarray of stringsList of recipient phone numbers in international or local format (e.g. ["254700000001", "0733000002"]).
messageYesstringSMS text to send. Long messages will automatically be divided into multiple units.
scheduled_atNostringOptional ISO 8601 timestamp for scheduled delivery (e.g. 2026-03-10T10:00:00+03:00).
sender_idLegacystring / numberLegacy UUID or numeric ID for backward compatibility with older integrations.

Responses

Success Response

JSON
{
  "status": "success",
  "message": "Bulk SMS processed",
  "data": {
    "requested": 2,
    "queued": 2,
    "failed": []
  }
}

Partial Bulk Failure

If one of the numbers is invalid, valid recipients are still queued and invalid ones are reported in failed:

JSON
{
  "status": "success",
  "message": "Bulk SMS processed",
  "data": {
    "requested": 2,
    "queued": 1,
    "failed": [
      {
        "mobile": "12345",
        "message": "Invalid number"
      }
    ]
  }
}

Smart Bundles Priority

When dispatching bulk broadcasts:

  • Bulkit consumes available Smart Bundles credits first using the First-Expiring, First-Out (FEFO) engine.
  • If your broadcast requires more credits than your active bundle has, the remaining units seamlessly overflow to your standard cash wallet balance.
  • If you have enough active bundle credits to cover the broadcast, the request will succeed even if your cash float balance is KSh 0.00.

Error Response

JSON
{
  "status": "error",
  "message": "Invalid sender ID"
}

Common Error Codes

  • Invalid credentials: Missing or invalid Bearer token / API key.
  • Insufficient balance: Account balance is insufficient for the requested message units.
  • Invalid number: None of the supplied numbers are valid phone numbers.
  • Invalid sender ID: Specified sender name or ID does not exist, is inactive, or is not authorized/assigned to your account.
  • Restricted send time: Safaricom promotional window restriction (promotional messages are permitted between 8:00 AM and 6:00 PM Africa/Nairobi time).
PreviousSend a Single SMSNextSend SMS to Contacts