Sending SMS from your own system, rather than a dashboard, lets you send receipts, reminders and one-time passwords the moment something happens. This guide walks through a typical integration using the Ndovubase SMS API as the example. Most Kenyan SMS APIs follow the same pattern, so the steps apply whichever provider you choose.

1. Get an account, a sender ID and an API key

Create an account on the SMS platform and top up a small amount for testing. Register the sender ID your customers will see, usually your business name, because messages go out under a registered sender ID. Then generate an API key. Treat it like a password: keep it in an environment variable or secrets manager on your server, never in front-end code or a public repository.

2. Send your first message

A send request is an HTTPS POST with a JSON body. With Ndovubase it goes to https://bulk.ndovubase.com/sms/v3/sendsms and looks like this:

{
  "api_key": "YOUR_API_KEY",
  "shortcode": "YOURSENDERID",
  "mobile": "0712345678",
  "message": "Your order #1042 has been dispatched.",
  "service": 0,
  "response_type": "json"
}

Send it from your back end, not the browser, so your key stays private. The API documentation has the current field list and examples.

3. Read the response

Every request returns a result for each number: a status code, a message ID, the recipient’s network, the cost of the message and your remaining balance. Store the message ID against the record that triggered the SMS, such as the order or the login attempt. You’ll need it to match delivery reports later.

Handle the error codes explicitly. The common ones are an invalid mobile number, an invalid sender name and low credit. Low credit in particular should alert someone on your team, because every message after it will fail until you top up.

4. Receive delivery reports

A successful request means the message was accepted, not that it reached the phone. Delivery reports tell you that. The recommended approach is a callback: you give the platform a URL on your server, and each delivery report is posted there as it arrives, with the message ID, status, network and delivery time. Your endpoint should save the status and reply that it received the report, so the platform doesn’t retry.

You can also request the report for one message ID, but polling for every message wastes requests. Use it for spot checks.

5. Format numbers and messages properly

  • Numbers: normalise them before sending, for example to the 2547XXXXXXXX format, and validate them when customers first enter them.
  • Length: a standard SMS carries 160 characters. Longer messages are sent in parts and each part is billed, so keep templates short. Emoji and some special characters switch the message to a format with fewer characters per part.
  • Personalisation: build the text in your system, for example “Hi Wanjiru, your payment of KES 2,500 was received.”

6. Make it production-ready

  • Send from a background job or queue, so a slow network call never holds up your checkout or login page.
  • Retry only on temporary failures, and never resend an OTP automatically: let the user ask for a new code.
  • Log the request, response and delivery report for each message, without logging the API key.
  • Watch your balance and set an alert before it runs low.
  • For promotional messages, keep an opt-out list and check it before every send.

When to consider SMPP instead

An HTTP API suits almost every business. If you already run an SMPP-capable messaging platform or send high, continuous volumes, a direct SMPP connection may suit you better. Our guide to what SMPP is explains the difference.

Need a hand?

See our SMS API integration page and published rates, or ask our developers if you’d like help with the integration.