Key takeaways
- Keep API keys on the server, and use separate test and live keys.
- Send numbers in international format, give each message your own reference and retry only on temporary errors.
- Receive status by webhook, verify it and reconcile what is missing.
- Test in the countries and on the networks that matter, and set alerts before launch.
Credentials and environments
- Keep the API key on your server, never in a browser or mobile app
- Use the test key until the integration works, then switch to the live key
- Store keys in a secret manager and rotate them on a schedule
- Give each service its own key, so one can be revoked without affecting the others
The request
- Send numbers in E.164 format and validate them first
- Choose the sender per country, with the registration it requires
- Count segments and watch for characters that switch the encoding
- Add your own reference to each message and store the message ID returned
- Set a timeout, and retry with a growing delay on timeouts and server errors, not on validation errors
- Respect the documented rate limits and queue the rest
The result
- Receive status through a webhook, and verify its signature
- Make processing safe to repeat, since events can arrive twice or out of order
- Handle every status, including failed and expired, with a rule for what happens next
- Reconcile messages that have no final status after the normal delay
Rules around sending
- Check an opt-out list before every marketing send
- Respect timing rules for marketing messages
- Separate transactional and marketing senders
- Rate-limit code requests and set a daily spend cap
Operations
- Dashboards for send volume, error rate and delivery by country
- Alerts for error spikes, falling delivery and unusual spend
- Logs that keep personal data to what you need
- A runbook that says who acts when delivery drops, and how to reach support
The test plan
- Real phones in each priority country, on more than one network where you can
- An invalid number, a switched-off phone and a number that has opted out
- A webhook endpoint that is down for a few minutes
- A message long enough for several segments, and one with Unicode
How ZafeConnect fits
ZafeConnect’s API takes the key in the X-API-Key header, has live and test environments, documented rate limits and signed webhooks, and comes with an OpenAPI 3.1 description and a Postman collection. The developer documentation lists the fields and responses.