Phone numbers
- Store numbers in E.164 (
+254712345678). The API also accepts 0712345678, 712345678 and 254712345678 and converts them.
- One invalid number fails the whole request with
400 invalid_phone_number — validate numbers when you collect them, not when you send.
- Duplicates in a list are removed automatically; each number is sent once.
Message length and cost
- Each recipient uses one unit per part. A 161-character message costs twice as much as a 160-character one. See SMS units.
- Avoid emoji and special characters unless you need them; they can split messages into more parts.
- Put the important part first — some phones show only the beginning in notifications.
Sending
- Send lists, not loops. One request can carry up to 10,000 numbers. A loop of single sends is slower and hits rate limits.
- Always send an
Idempotency-Key for anything you might retry, so a timeout never becomes a duplicate SMS. See Idempotency.
- OTPs and alerts: send one number per request with a key per event (
otp-<id>), and read message_status from the response.
- Promotions: send one list per campaign and follow the batch.
Delivery reports
- Use webhooks instead of polling, and verify every signature.
- Reply
2xx quickly and do your processing afterwards.
- Treat each webhook as "latest status" — they can arrive more than once, and occasionally out of order.
Consent and opt-outs
- Only message people who agreed to hear from you. Kenya's Data Protection Act requires consent for marketing messages.
- Numbers that opt out of your organisation are skipped automatically and use no units. You'll see them as
optedout in responses and reports.
- Include who you are in every message — your sender ID helps, but say it in the text for marketing messages too.
Keys and security
- Keep keys on your server only. Use a test key everywhere except production.
- One key per system; roll keys regularly and immediately if one leaks. See Authentication.