Get started

Quickstart

Get started with MailAfrica in under 10 minutes: register, create an API key, make a sender ID, wire a webhook, and send your first email.

1. Create your account

Register with an email or a Tanzanian phone number. At least one of email or phone_number is required; a password is always required.

bash

curl -X POST https://api.mailafrica.online/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "password": "a-strong-password-8-chars-min",
    "name": "Your Name",
    "company_name": "Your Company"
  }'

The response returns a JWT plus the account. You must verify your email or phone before you can create addresses or send mail — a verification link (email) or OTP (phone) is sent automatically.

2. Verify your identity

Open the emailed link, or verify a phone number by requesting a code and confirming it:

bash

# Add a phone number (sends a 6-digit OTP)
curl -X POST https://api.mailafrica.online/api/auth/phone \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+255712345678"}'

# Confirm 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"}'

3. Create an API key

Keys are the recommended auth for programmatic integrations. They are scoped to your account and can be revoked independently of your login. See API Keys for scopes.

bash

curl -X POST https://api.mailafrica.online/api/apikeys \
  -H "Authorization: Bearer <your_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-server-integration"}'

The plaintext key (MAIL_ + 64 hex characters) is returned once, in the key field. Store it in your secrets manager — it is never shown again.

4. Create a sender ID

A sender ID is an inbound address that receives real email. Addresses are lowercase [a-z0-9-], and you can create up to 100 per account.

bash

curl -X POST https://api.mailafrica.online/api/inbound/addresses \
  -H "X-API-Key: MAIL_<your_api_key_here>" \
  -H "Content-Type: application/json" \
  -d '{"local_part": "hello", "label": "Support inbox"}'

Mail to hello@mailafrica.online now lands on your account. See Sender IDs for custom receiving domains.

5. Wire an inbox webhook

bash

curl -X POST https://api.mailafrica.online/api/webhook/webhooks \
  -H "X-API-Key: MAIL_<your_api_key_here>" \
  -H "Content-Type: application/json" \
  -d '{
    "address_id": 1,
    "url": "https://your-app.example.com/hooks/mailafrica"
  }'

You'll get a whsec_ secret to verify signatures. Full details, including the verification code, are in Webhooks.

6. Send a test email

bash

curl -X POST https://api.mailafrica.online/api/outbound/emails \
  -H "X-API-Key: MAIL_<your_api_key_here>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["someone@example.com"],
    "subject": "Hello from MailAfrica",
    "text_body": "This is a transactional email sent via the MailAfrica API."
  }'

7. Check your balance

Every message debits your wallet. Check it and top up when low — see Balance & Top-up.

bash

curl https://api.mailafrica.online/api/billing/balance \
  -H "X-API-Key: MAIL_<your_api_key_here>"