AI & automation

Integrate with AI Assistants

Give Claude, ChatGPT, Cursor, or any LLM agent everything it needs to integrate MailAfrica: machine-readable docs, an OpenAPI spec, and copy-paste recipes.

MailAfrica is built agent-first: every page of these docs is also plain markdown, a full OpenAPI 3.1 spec describes the API, and the whole site compiles into two LLM-friendly text files. Point your assistant at any of them and it can integrate without browsing.

Machine-readable resources

Resource	URL	What it gives the model
llms.txt	`https://docs.mailafrica.online/llms.txt`	Fact-dense summary + linked page index (start here)
llms-full.txt	`https://docs.mailafrica.online/llms-full.txt`	The entire documentation in one file
Page markdown	`https://docs.mailafrica.online/<page>.md`	Any docs page as raw markdown, e.g. `/outbound.md`
OpenAPI spec	`https://docs.mailafrica.online/openapi.json`	Every endpoint, schema, and error code (OpenAPI 3.1)

Prefer MCP? The open-source MailAfrica Agent MCP server exposes the entire API as MCP tools for Claude Desktop, Claude Code, Cursor, and any MCP client — plus a webhook-driven auto-reply pipeline.

Environment setup

bash

# .env — one key, three auth styles
MAIL_API_KEY=MAIL_your_api_key_here
MAIL_BASE_URL=https://api.mailafrica.online

import os, requests

BASE = os.environ["MAIL_BASE_URL"]
KEY = os.environ["MAIL_API_KEY"]

def call(method, path, **kwargs):
    r = requests.request(method, f"{BASE}{path}",
                         headers={"X-API-Key": KEY}, timeout=15, **kwargs)
    r.raise_for_status()
    body = r.json()
    if not body.get("success"):
        raise RuntimeError(body)
    return body["data"]

balance = call("GET", "/api/billing/balance")["balance_tzs"]

Recipe: send email

bash

curl -X POST https://api.mailafrica.online/api/outbound/emails \
  -H "X-API-Key: $MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Your receipt",
    "text_body": "Thanks for your order #482."
  }'

Charged per recipient from your TZS wallet before dispatch; refunded on provider failure.
Flat 5 TZS/recipient from the platform sender or your own verified domain (from_domain_id + from_address), debited before dispatch and refunded on provider failure.
Status is sent | failed only — sent means accepted by the upstream provider; delivery/bounce tracking is not available.

Recipe: read inbound mail

bash

# Create a sender ID (address) first, then poll or use webhooks
curl -X POST https://api.mailafrica.online/api/inbound/addresses \
  -H "X-API-Key: $MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"local_part": "support"}'

curl "https://api.mailafrica.online/api/inbound/messages?unread=true" \
  -H "X-API-Key: $MAIL_API_KEY"

For real-time agents, register a webhook instead of polling. Verify every delivery by computing HMAC-SHA256 over the raw body with your whsec_... secret and comparing it to the X-Webhook-Signature header (also mirrored in X-Signature) using constant-time comparison.

Error handling rules

Status	Code	Meaning	How to fix
Client error401	`UNAUTHORIZED`	Missing or invalid credentials.	Check MAIL_API_KEY is set and starts with MAIL_.
Client error402	`INSUFFICIENT_BALANCE`	Wallet can't cover the operation.	POST /api/billing/topup, then retry the operation.
Client error400	`VALIDATION_ERROR`	Request failed validation.	Read errors[].field and correct that field.
Client error429	`RATE_LIMITED`	Too many requests.	Back off exponentially; sends are capped at 2/sec.
Server error502	`PROVIDER_ERROR`	Upstream provider failure.	Retry with backoff — balance is refunded on failure.

Agent checklist

Fetch llms.txt and read the OpenAPI spec before writing code.
Store the API key in an environment variable — never hard-code it.
Check success in every envelope before touching data.
Treat sent as provider-accepted, not delivered.
Verify webhook signatures over the raw body before trusting payloads.
Poll GET /api/billing/balance after top-ups to confirm credits landed.
Use /api/sandbox/* SMTP credentials to test end-to-end without real mail.