Every eSMS Mail request is authenticated with an API key sent as a Bearer token. Scoping your keys limits the blast radius if one ever leaks.
Scopes
| Scope | Can do | Use it for |
|---|---|---|
| Full access | Send, read, and manage keys/domains/webhooks | Admin scripts |
| Sending | Send email, read logs & analytics | Your app's mail service |
| Read only | Read logs, analytics, account info | Dashboards, monitoring |
A key without the required scope gets 403 Forbidden. Sending keys can't create or revoke keys; read-only keys can't send.
curl -X POST https://send.esmsafrica.io/v1/api-keys \
-H "Authorization: Bearer esms_k_full_access_key" \
-H "Content-Type: application/json" \
-d '{"name":"production-sender","scope":"sending"}'Live vs Test
Each key belongs to an environment. Live keys (esms_k_…) send real email and count against your plan. Test keys (esms_test_…) drive the Sandbox — never sent, never billed. Test and live logs are isolated, and test webhooks carry "livemode": false.
Rotating keys
Create the replacement first, deploy it, then revoke the old key. Revocation is immediate.
curl -X DELETE https://send.esmsafrica.io/v1/api-keys/{key_id} \
-H "Authorization: Bearer esms_k_full_access_key"Best practices
- One key per service, each with the narrowest scope that works.
- Test keys in CI and local dev; live keys on servers only.
- Never commit keys or ship them in mobile/client apps.
- Rotate on staff changes or any suspected exposure.