Get started

API Keys

Create, list, and revoke API keys for your integration. Keys are account-scoped, support optional scopes, and can be set to expire.

API keys authenticate your server-to-server integration. They are scoped to your account — a key can only access your own sender IDs, messages, webhooks, domains, and balance, and can never touch internal platform data.

Keys look like MAIL_ followed by 64 hex characters. Only the SHA-256 hash and a short prefix are stored server-side, so a leaked database never exposes usable keys.

Create a key

bash

curl -X POST https://api.mailafrica.online/api/apikeys \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-webhook-server",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Body fields: name (required), scopes (optional array), expires_at (optional ISO timestamp).

json

{
  "success": true,
  "message": "api key created",
  "data": {
    "api_key": {
      "id": 3,
      "user_id": 7,
      "name": "production-webhook-server",
      "key_prefix": "MAIL_a1b2c3d4",
      "scopes": null,
      "last_used_at": null,
      "expires_at": "2027-01-01T00:00:00Z",
      "revoked_at": null,
      "created_at": "2026-08-15T00:00:00Z"
    },
    "key": "MAIL_a1b2c3d4..."
  },
  "request_id": "req_01",
  "timestamp": "2026-08-15T00:00:00Z"
}

The full key lives in data.key and is shown exactly once. Store it immediately in your secrets manager. If you lose it, revoke and create a new one.

List your keys

bash

curl https://api.mailafrica.online/api/apikeys \
  -H "Authorization: Bearer <your_jwt>"

Returns all active (non-revoked) keys with their metadata, including last_used_at so you can spot unused keys.

Revoke a key

Revocation is immediate — existing requests with that key stop working right away. Use either form:

curl -X DELETE https://api.mailafrica.online/api/apikeys/3 \
  -H "Authorization: Bearer <your_jwt>"

Good key hygiene

Give every key a descriptive name so you know which service it belongs to.
Set expires_at for short-lived or staging keys.
Revoke keys when a service is decommissioned or a developer leaves.
Never hardcode keys in client-side code — keys belong in server secrets.