Authentication

MailAfrica supports two authentication methods depending on what you're doing. Every protected request is scoped to your account — credentials can never reach another user's data or any internal platform surface.

API keys (recommended)

Use API keys for server-to-server integrations: sending email, reading messages, configuring sender IDs and webhooks, and checking balance. They are independent of your password and can be revoked per key.

Send a key in any of these formats — all are equivalent:

curl https://api.mailafrica.online/api/billing/balance \
  -H "X-API-Key: MAIL_abcd1234..."

JWT bearer tokens

JWTs are issued by register and login and are used for account management: updating your profile, verifying email/phone, and managing API keys themselves.

Authorization: Bearer <your_jwt_token>

Log in

curl -X POST https://api.mailafrica.online/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "developer@example.com",
    "password": "your-password"
  }'

identifier is your email if it contains @, otherwise your Tanzanian phone number (+255...). The response contains token, refresh_token, and user. Access tokens expire after 60 minutes; refresh tokens are single-use and rotated.

curl -X POST https://api.mailafrica.online/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<your_refresh_token>"}'

Unauthenticated endpoints

A small set of endpoints need no credentials because they are part of account onboarding:

• POST /api/auth/register, POST /api/auth/login, POST /api/auth/google.
• POST /api/auth/email/verify — verification links are signed and single-use.

When you'll be blocked