Get started

Authentication

MailAfrica supports JWT bearer tokens for account operations and API keys for programmatic integrations. Both are account-scoped — you only ever access your own data.

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:

Method	Header
API key header	`X-API-Key: MAIL_...`
Bearer	`Authorization: Bearer MAIL_...`
Raw	`Authorization: MAIL_...`

bash

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

Treat keys like passwords. The plaintext is shown once at creation. Rotate by revoking the old key and issuing a new one — see API Keys.

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

bash

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.

bash

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

Profile & verification

Once authenticated you can read your profile, update it, and verify a new email or phone. Phone verification is required before sending outbound email; email verification is optional but recommended.

bash

# Read profile
curl https://api.mailafrica.online/api/auth/me \
  -H "Authorization: Bearer <your_jwt>"

# Update name / company
curl -X PATCH https://api.mailafrica.online/api/auth/me \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "company_name": "Acme Ltd"}'

PATCH /api/auth/me accepts optional name and company_name — omit either to leave it unchanged.

bash

# Set a new email — sends a verification link
curl -X POST https://api.mailafrica.online/api/auth/email \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

# Re-send the verification link to the current email
curl -X POST https://api.mailafrica.online/api/auth/email/resend \
  -H "Authorization: Bearer <your_jwt>"

bash

# Set a new phone — triggers an OTP via SMS
curl -X POST https://api.mailafrica.online/api/auth/phone \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+255712345678"}'

# Verify the OTP
curl -X POST https://api.mailafrica.online/api/auth/phone/verify \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

# Re-send the OTP to the current phone
curl -X POST https://api.mailafrica.online/api/auth/phone/resend \
  -H "Authorization: Bearer <your_jwt>"

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

Status	Code	Why
401	`UNAUTHORIZED`	Missing, malformed, or expired credentials.
403	`ACCOUNT_DISABLED`	Your account was disabled; existing keys stop working immediately.
403	`FORBIDDEN`	Verified identity required (email or phone) for this operation.