API Keys
Create and manage API keys for the eSMS Mail REST API.
API keys authenticate requests to the eSMS Mail API. They are the recommended way to integrate eSMS Mail into your application.
Create an API key
- Go to send.esmsafrica.io → Settings → API Keys
- Click Create API Key
- Enter a name and select permissions
- Copy the key - it's only shown once
Via API
curl -X POST https://send.esmsafrica.io/v1/api-keys/ \
-H "Authorization: Bearer esms_k_your_existing_key" \
-H "Content-Type: application/json" \
-d '{"name": "Production key", "scope": "sending"}'scope is a preset: full (everything), sending (send + read) or read (read-only). Alternatively pass an explicit permissions list such as ["send", "read"]; if you pass neither, the key gets ["send"] only. Add "environment": "test" for a sandbox key. See API Keys, Scopes & Environments.
Using API keys
Include the key in the Authorization header:
Authorization: Bearer esms_k_your_api_keyKey format
Live API keys start with esms_k_ and test (sandbox) keys with esms_test_, followed by a random secret. Example:
esms_k_abc123def456...The first 8 characters after the esms_k_ / esms_test_ part are the key's key_prefix, shown in the dashboard for identification. The full key is only shown at creation time.
Revoking keys
Delete an API key to immediately revoke access:
curl -X DELETE https://send.esmsafrica.io/v1/api-keys/{key_id} \
-H "Authorization: Bearer esms_k_your_api_key"Best practices
- Create separate keys for each environment (development, staging, production)
- Use descriptive names so you know which key is which
- Rotate keys periodically
- Never commit API keys to version control
- Use environment variables to store keys