# MailAfrica

> Email infrastructure for Africa. Create sender IDs (inbound addresses), receive inbound email via webhooks, send transactional email from the platform sender or your own verified domains, run AI auto-replies, and fund everything from a single TZS wallet — with one REST API.

MailAfrica is pay-per-message (no subscriptions): a flat **5 TZS** per message/recipient, inbound or outbound, on MailAfrica's domain or your own verified domain, debited before dispatch and refunded on provider failure. Minimum top-up is 2,000 TZS via mobile money or card.

## Facts an integration must know

- Base URL: https://api.mailafrica.online
- Auth: send `X-API-Key: MAIL_...` (64-hex key created in the dashboard or via `POST /api/apikeys/`). `Authorization: Bearer MAIL_...` and raw `Authorization: MAIL_...` also work. JWTs exist for dashboard flows; API keys are what integrations use. Read/patch your profile with `GET/PATCH /api/auth/me` (JWT required).
- Every response is wrapped in a fixed envelope: `{ success, message?, data?, errors?[], pagination?, request_id?, timestamp }`. Check `success` before touching `data`.
- `errors[]` entries carry optional `field`, a stable `code` (e.g. INSUFFICIENT_BALANCE, RATE_LIMITED), and a human `message`.
- Outbound email status is `sent | failed` only. `sent` means accepted by the upstream provider; delivery/bounce tracking is not available.
- Webhook deliveries carry an HMAC-SHA256 hex signature over the raw body in both `X-Signature` and `X-Webhook-Signature`; secrets start with `whsec_`. Retries: up to 3 attempts at 1s/3s/9s backoff.
- Rate limit: 2 emails/sec per user (burst 2). Batch sends chunk recipients into groups of 50.
- Attachments: max 10 per message, 10 MiB each, 20 MiB total, base64 in `data_base64`.
- Limits: 100 inbound addresses, 100 receiving domains, 5 sending domains, 100 from-addresses per account.
- Outbound From: without `from_domain_id`, mail goes out from the platform sender; pass `from_address` on the platform domain (e.g. `food@mailafrica.online`) to brand it with your own local part — anything off-domain is rejected with 403. With `from_domain_id`, `from_address` must be the domain default or a recorded sender.
- A free SMTP sandbox (`/api/sandbox/*`) captures test mail — 2,000 messages/month.
- Pricing details: https://docs.mailafrica.online/pricing. Full error catalog: https://docs.mailafrica.online/errors.

## Documentation

## Get started

- [Introduction](https://docs.mailafrica.online/): MailAfrica is a developer-first email infrastructure platform for Africa. Create sender IDs, receive inbound email via webhooks, send transactional email, and manage wallet balance and top-ups with a single API. [markdown](https://docs.mailafrica.online/introduction.md)
- [Quickstart](https://docs.mailafrica.online/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. [markdown](https://docs.mailafrica.online/quickstart.md)
- [Authentication](https://docs.mailafrica.online/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. [markdown](https://docs.mailafrica.online/authentication.md)
- [API Keys](https://docs.mailafrica.online/api-keys): Create, list, and revoke API keys for your integration. Keys are account-scoped, support optional scopes, and can be set to expire. [markdown](https://docs.mailafrica.online/api-keys.md)

## Inbound email

- [Sender IDs](https://docs.mailafrica.online/sender-ids): Create, list, and delete inbound addresses (sender IDs) programmatically. Each address receives real email on the platform domain or your own verified receiving domain. [markdown](https://docs.mailafrica.online/sender-ids.md)
- [Receiving Domains](https://docs.mailafrica.online/receiving-domains): Add and verify your own domain to receive email at addresses like hello@yourdomain.com, and route its traffic to your sender IDs. [markdown](https://docs.mailafrica.online/receiving-domains.md)
- [Reading Messages](https://docs.mailafrica.online/inbound-messages): Fetch inbound messages for your sender IDs over the API: list, read a single message with full MIME bodies and attachments, and mark messages as read. [markdown](https://docs.mailafrica.online/inbound-messages.md)
- [Webhooks](https://docs.mailafrica.online/webhooks): Get real-time inbound email events pushed to your endpoint. Register webhooks per sender ID, verify HMAC signatures, inspect deliveries, and handle retries. [markdown](https://docs.mailafrica.online/webhooks.md)
- [SMS Notifications](https://docs.mailafrica.online/sms-notifications): Forward inbound email summaries to a Tanzanian phone number via SMS. Configure per sender ID, inspect delivery status, and revoke when needed. [markdown](https://docs.mailafrica.online/sms-notifications.md)

## Outbound email

- [Sending Email](https://docs.mailafrica.online/outbound): Send transactional email programmatically — single messages, batches, attachments, and templates — from the platform sender or your own verified sending domain. [markdown](https://docs.mailafrica.online/outbound.md)
- [Sending Domains](https://docs.mailafrica.online/sending-domains): Add and verify your own domain for outbound email. MailAfrica generates DKIM, SPF, and DMARC records for self-hosted delivery — publish them, verify, and create from-addresses. [markdown](https://docs.mailafrica.online/sending-domains.md)
- [Templates](https://docs.mailafrica.online/templates): Create and manage reusable email templates with {{variable}} placeholders, then send with a template_id and variables. [markdown](https://docs.mailafrica.online/templates.md)

## Billing

- [Balance & Top-up](https://docs.mailafrica.online/balance): Read your wallet balance and start a top-up via mobile money or card — all programmatically. Every message debits this single TZS wallet. [markdown](https://docs.mailafrica.online/balance.md)
- [Pricing & Limits](https://docs.mailafrica.online/pricing): Pay-per-message pricing in Tanzanian Shillings, plus the platform limits every developer should know before integrating. [markdown](https://docs.mailafrica.online/pricing.md)

## Testing & compliance

- [Sandbox](https://docs.mailafrica.online/sandbox): Test the full integration without sending real mail: generate SMTP credentials that capture every message, inspect them, and reset when done. [markdown](https://docs.mailafrica.online/sandbox.md)
- [Compliance](https://docs.mailafrica.online/compliance): Manage your PDPC compliance profile, message retention period, and download an audit export — directly over the API. [markdown](https://docs.mailafrica.online/compliance.md)

## AI & automation

- [AI Auto-Reply Agent](https://docs.mailafrica.online/agent): Configure per-address AI auto-replies over the API: modes (off/draft/auto), persona prompts, reply-from identity, and one-off draft previews. [markdown](https://docs.mailafrica.online/agent.md)
- [MCP Server](https://docs.mailafrica.online/mcp): Connect Claude Desktop, Claude Code, Cursor, or any MCP client to MailAfrica. Run the open-source MailAfrica Agent MCP server locally (stdio, single-tenant) or use the hosted multi-tenant OAuth endpoint at mcp.mailafrica.online. [markdown](https://docs.mailafrica.online/mcp.md)
- [Integrate with AI Assistants](https://docs.mailafrica.online/ai): Give Claude, ChatGPT, Cursor, or any LLM agent everything it needs to integrate MailAfrica: machine-readable docs, an OpenAPI spec, and copy-paste recipes. [markdown](https://docs.mailafrica.online/ai.md)

## SDKs & CLI

- [SDKs & CLI](https://docs.mailafrica.online/sdks): Official MailAfrica interfaces in your language of choice: the Go SDK and the MailAfrica CLI are available today; the raw REST API and OpenAPI spec remain fully supported everywhere else. [markdown](https://docs.mailafrica.online/sdks.md)
- [Go SDK](https://docs.mailafrica.online/sdks-go): The official Go client for MailAfrica. Standard-library only, typed requests and responses, automatic JWT refresh, and observability hooks. [markdown](https://docs.mailafrica.online/sdks-go.md)
- [MailAfrica CLI](https://docs.mailafrica.online/cli): The official command-line client for MailAfrica. Manage inbound addresses, webhooks, and sending domains, and drive sandbox, wallet, SMS, compliance, and AI auto-reply — all from your terminal. [markdown](https://docs.mailafrica.online/cli.md)

## Reference

- [Errors & Response Envelope](https://docs.mailafrica.online/errors): Every MailAfrica endpoint wraps responses in a standard envelope. Understand success and error shapes, pagination, and the full error-code catalog. [markdown](https://docs.mailafrica.online/errors.md)

## Optional

- [OpenAPI spec](https://docs.mailafrica.online/openapi.json): machine-readable OpenAPI 3.1 for every endpoint
- [Full docs](https://docs.mailafrica.online/llms-full.txt): this entire site as one markdown file