API Keys, Scopes & Environments

Every request to the eSMS Mail API is authenticated with an API key passed as a Bearer token:

curl https://send.esmsafrica.io/v1/emails \
  -H "Authorization: Bearer esms_k_your_api_key"

Create and manage keys on the API Keys page of your dashboard, or via the API. Keys are shown in full once at creation — store them securely.

Scopes

Give each key only the access it needs. A key used by your sending backend should not be able to manage other keys or account settings.

A key without the required scope receives 403 Forbidden. Sending keys cannot create or revoke API keys; read-only keys cannot send.

# Create a sending-only key
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"}'

Environments: 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_…) never send real email and are never billed — they drive the Sandbox for safe integration testing.

Test and live traffic are isolated: emails created with a test key appear only when you filter to the Test environment (in the dashboard's Email Logs, or with ?environment=test on the API), and fire webhooks with livemode: false.

# Create a test key for sandbox integration
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": "ci-tests", "scope": "sending", "environment": "test"}'

Rotating keys

Create the replacement key first, deploy it, then revoke the old one from the dashboard or:

curl -X DELETE https://send.esmsafrica.io/v1/api-keys/{key_id} \
  -H "Authorization: Bearer esms_k_full_access_key"

Revocation takes effect immediately. Deleting a key requires the manage scope (included in Full access).

Best practices

• One key per service, each with the narrowest scope that works.
• Use test keys in CI and local development; keep live keys on servers only.
• Never commit keys to source control or ship them in client-side/mobile apps.
• Rotate on staff changes or any suspected exposure.