Inbound email

Reading 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.

Messages are stored the moment they arrive (parsed MIME: multipart, attachments, text/html) and can be polled, or pushed to your webhook. Reading is always scoped to addresses you own.

List messages

address_id is required — you always scope reads to one of your sender IDs:

bash

curl "https://api.mailafrica.online/api/inbound/messages?address_id=42&unread=true&page=1&per_page=20" \
  -H "X-API-Key: MAIL_<your_api_key_here>"

Query params: address_id (required), unread (true filters to unread), page (default 1), per_page (default 20).

json

{
  "success": true,
  "data": [
    {
      "id": 9001,
      "address_id": 42,
      "from_addr": "sender@example.com",
      "to_addr": "support@mailafrica.online",
      "subject": "New customer request",
      "text_body": "Hi, I need help with...",
      "html_body": "<p>Hi, I need help with...</p>",
      "headers": {},
      "attachments": [],
      "is_read": false,
      "received_at": "2026-08-15T09:30:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
}

Results are ordered newest first. headers is the raw message header map; attachments includes filename and content so you can re-download or forward them.

Get a single message

bash

curl https://api.mailafrica.online/api/inbound/messages/9001 \
  -H "X-API-Key: MAIL_<your_api_key_here>"

Mark as read

bash

curl -X PATCH https://api.mailafrica.online/api/inbound/messages/9001/read \
  -H "X-API-Key: MAIL_<your_api_key_here>"

Polling vs webhooks: for real-time reactions, register a webhook. Use polling as a fallback or for backfill after downtime.

Best practice

Match webhook message_id to the stored message via GET /api/inbound/messages/{id} to fetch full bodies on demand.
Only the metadata you need is in the webhook event — keep payloads light and fetch details by id.
is_read lets you track which messages your workers already processed.