Bulkit
Register

Send SMS to Contacts

Send SMS to one or more recipients using your Bulkit sender ID and available account credit.

Last updated · Markdown version

It is suitable for:

  • transactional SMS
  • operational alerts
  • scheduled notifications
  • sending one message to multiple saved contact numbers

Endpoint title

Send SMS to Contacts

What this endpoint does

Queues an SMS message for one or more recipient numbers using a sender ID assigned to your account.

Endpoints

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

Authorization

Bulkit recommends authenticating requests using a single Bearer token in the Authorization HTTP header:

HTTP
Authorization: Bearer <your_api_key>

Legacy compatibility: Passing apikey and apisecret directly in the JSON body, or via legacy X-API-Key and X-API-Secret headers, remains supported for existing integrations.

HTTP method and path

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

Authorization requirements

  • Recommended: Authorization: Bearer <your_api_key> in the HTTP header.
  • Legacy: apikey and apisecret provided in the JSON body or custom headers.

Endpoint code block

HTTP
POST https://api.bulkitsms.com/api/v2/messages/sms/bulk
Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md
Content-Type: application/json

Authorization header example

HTTP
Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md

Error response

JSON
{
  "status": "error",
  "message": "Invalid number"
}

Suggested usage

Use this endpoint for both single-recipient and multi-recipient SMS sends when you want one consistent integration pattern.

Request 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 John, your order #BK-2041 has been dispatched.",
    "scheduled_at": "2026-03-10T09:15:00+03:00"
  }'

Parameters

ParameterRequiredTypeDescriptionValidation
senderYesstringSender ID name assigned to your account (e.g. BULK_IT)Must exist, be active, and belong to your account
mobilesYesarray of stringsOne or more recipient mobile numbersUse normalized Kenyan numbers such as 254700000001
messageYesstringSMS body to send to all recipients in the requestCannot be blank
scheduled_atNostringFuture send timeUse timezone-aware ISO 8601 such as 2026-03-10T09:15:00+03:00
sender_idLegacystring / intLegacy UUID or numeric Sender IDBackward-compatible alternative to sender
apikeyLegacystringLegacy body authentication keyOptional when using Authorization: Bearer
apisecretLegacystringLegacy secret paired with API keyOptional when using Authorization: Bearer

Success response example

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

Error response examples

Invalid credentials

JSON
{
  "status": "error",
  "message": "Invalid credentials"
}

Insufficient balance

JSON
{
  "status": "error",
  "message": "Insufficient balance"
}

Invalid number

JSON
{
  "status": "error",
  "message": "Invalid number"
}

Invalid sender ID

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

Invalid message

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

Restricted send time

JSON
{
  "status": "error",
  "message": "Restricted send time"
}

Partial bulk failure example

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

Notes and best practices

  • validate and normalize phone numbers before sending
  • keep sender IDs mapped to the right environment and use case
  • check balance before high-volume sends
  • use scheduled_at with timezone offsets to avoid ambiguity
  • if you use a promotional sender ID, avoid scheduling Safaricom traffic outside 8:00 AM to 6:00 PM Africa/Nairobi time

Single-recipient alternative

If you are sending to one recipient only, Bulkit also provides:

HTTP
POST /api/v2/messages/sms

Use the bulk endpoint when you want one consistent integration for both single and multi-recipient sends.

PreviousSend Bulk SMSNextSend Customized SMS