Send SMS

One endpoint for a single OTP or a hundred thousand recipients.

POSThttps://bulksmsapi.selanim.com/v1/sms/send

Request body

Field	Type	Description
`senderId`required	string	An approved sender ID on your account.
`to`required	(string \| object)[]	Up to 1,000 recipients per request. For larger audiences, import them into a group and send from the portal.
`message`required	string	GSM-7 and UCS-2 are both supported; the segment count is worked out for you. A message longer than 10 segments is rejected.
`scheduleAt`	string (ISO 8601)	ISO 8601. Omit to send immediately.
`reference`	string	Your own identifier, echoed on every delivery webhook. Up to 120 characters.
`callbackUrl`	string (url)	Overrides the account webhook for this request only.

Headers

Header	Type	Description
`Idempotency-Key`	string	Replay protection. Send the same key with the same body within 24 hours and you get the original response instead of a second send - the safe way to retry after a timeout. The same key with a different body is a 409.

Example

bash

curl -X POST "https://bulksmsapi.selanim.com/v1/sms/send" \
  -H "Authorization: Bearer $SBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "SELANIM",
    "to": [
      "255712345678",
      "0754112233"
    ],
    "message": "Dear parent, Term 3 fees are due on 25th Aug.",
    "reference": "term3-fees"
  }'

Needs: curl, on every machine already.

json

{
  "requestId": "REQ-90022",
  "parts": 1,
  "cost": 30,
  "currency": "TZS",
  "reference": "term3-fees",
  "messages": [
    { "id": "SM-4a91c0", "to": "+255712345678", "network": "Vodacom", "status": "queued" },
    { "id": "SM-4a91c1", "to": "+255754112233", "network": "Vodacom", "status": "queued" }
  ]
}

Personalisation

To vary the body per recipient, send an array of objects instead of plain strings. Each entry is billed and reported separately.

json

{
  "senderId": "SELANIM",
  "message": "Hello {{name}}, your balance is {{amount}}.",
  "to": [
    { "phone": "255712345678", "variables": { "name": "Rehema", "amount": "TZS 45,000" } },
    { "phone": "255754112233", "variables": { "name": "Baraka", "amount": "TZS 12,500" } }
  ]
}

Message status

Status	Type	Description
`queued`	string	Accepted and waiting for the operator route.
`sent`	string	Handed to the operator, awaiting a delivery receipt.
`delivered`	string	Confirmed delivered to the handset.
`failed`	string	Operator rejected it — handset unreachable, barred, or invalid.
`expired`	string	Validity window passed before the handset came online.
`rejected`	string	Blocked before dispatch, usually a sender ID or content policy issue.

Fetch one message

GEThttps://bulksmsapi.selanim.com/v1/sms/{messageId}

bash

curl https://bulksmsapi.selanim.com/v1/sms/SM-4a91c0 \
  -H "Authorization: Bearer $SBS_API_KEY"

Batch size

Requests are capped at 1,000 recipients. For larger audiences, create a campaign — it handles chunking, throttling and retries for you.