AI & automation

AI Auto-Reply Agent

Configure per-address AI auto-replies over the API: modes (off/draft/auto), persona prompts, reply-from identity, and one-off draft previews.

Every inbound address can carry an AI auto-reply configuration. When a message arrives and the config is enabled, MailAfrica's agent pipeline reads the conversation and writes a reply — sent automatically (auto), saved for review (draft), or disabled (off). The LLM is called server-side; you configure behavior, not models.

Config shape

json

{
  "address_id": 42,
  "user_id": 7,
  "mode": "auto",
  "persona": "You are support for Acme Tanzania. Be brief and warm.",
  "enabled": true,
  "reply_from_domain_id": null,
  "reply_from_address": null,
  "updated_at": "2026-08-15T00:00:00Z"
}

mode is one of off | draft | auto. persona is an optional system prompt — without one a sensible default is used that refuses to invent facts. reply_from_domain_id + reply_from_address optionally send replies from one of your verified sending domains instead of the platform sender.

List & read configs

bash

# All your configs
curl https://api.mailafrica.online/api/agent/configs \
  -H "X-API-Key: MAIL_<your_api_key_here>"

# One address's config (id = address id)
curl https://api.mailafrica.online/api/agent/configs/42 \
  -H "X-API-Key: MAIL_<your_api_key_here>"

Update a config

bash

curl -X PUT https://api.mailafrica.online/api/agent/configs/42 \
  -H "X-API-Key: MAIL_<your_api_key_here>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "auto",
    "enabled": true,
    "persona": "You handle billing questions for Acme. Answer in English or Swahili.",
    "reply_from_domain_id": 2,
    "reply_from_address": "support@yourcompany.co.tz"
  }'

The same configs power the dashboard's Inbox → AI Auto-reply toggle and the open-source MailAfrica Agent MCP server — one source of truth per address.

Preview a draft

bash

curl -X POST https://api.mailafrica.online/api/agent/configs/42/draft \
  -H "X-API-Key: MAIL_<your_api_key_here>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Where is my order?",
    "text_body": "I paid yesterday but have not heard anything."
  }'

json

{
  "success": true,
  "data": { "draft": "Hi! Thanks for reaching out — ..." },
  "message": "draft generated"
}

Drafts never send — they only preview what the agent would reply. Pass subject, text_body, or both.

Errors

Status	Code	Meaning	How to fix
Client error400	`VALIDATION_ERROR`	Invalid mode, empty subject/text_body on draft, or bad address id.	Use mode `off\|draft\|auto`; provide at least one of subject/text_body.
Client error403	`FORBIDDEN`	The address isn't yours.	Use an address id from your sender IDs.
Server error503	`NOT_CONFIGURED`	The LLM gateway isn't configured server-side yet.	Platform-side gap; retry later.