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: 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 will continue to work without modification.

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
senderYesstringYour sender ID name (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"
      }
    ]
  }
}

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 or is not approved for 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