Configuration
MailAfrica Agent is configured via environment variables, loaded through Pydantic Settings. Create a .env file in the project root (see .env.example for a template).
Environment Variables
MailAfrica API
| Variable | Default | Required | Description |
|---|---|---|---|
MAILAFRICA_API_BASE | https://api.mailafrica.online | No | Base URL for the MailAfrica API |
MAILAFRICA_API_KEY | — | Yes | Your MailAfrica API key (X-API-Key header) |
Ngamia LLM
| Variable | Default | Required | Description |
|---|---|---|---|
NGAMIA_BASE_URL | https://api.ngamia.cc/v1 | No | Ngamia LLM gateway base URL |
NGAMIA_API_KEY | — | Yes | Your Ngamia API key |
NGAMIA_MODEL | openai/gpt-4o-mini | No | LLM model to use for completions |
Agent Settings
| Variable | Default | Required | Description |
|---|---|---|---|
AGENT_WEBHOOK_SECRET | — | Yes (webhook) | HMAC-SHA256 secret for verifying webhook deliveries |
AGENT_DB_PATH | agent.db | No | Path to SQLite database file |
AGENT_DEFAULT_PERSONA | (built-in) | No | Default system prompt for auto-reply agent |
AGENT_DEFAULT_MODE | off | No | Default auto-reply mode: auto, draft, or off |
Server Settings
| Variable | Default | Required | Description |
|---|---|---|---|
AGENT_HOST | 0.0.0.0 | No | Bind address for webhook server |
AGENT_PORT | 8000 | No | Port for webhook server (Docker uses 8097) |
Example .env File
# MailAfrica
MAILAFRICA_API_BASE=https://api.mailafrica.online
MAILAFRICA_API_KEY=ma_key_xxxxxxxxxxxxxxxx
# Ngamia LLM
NGAMIA_BASE_URL=https://api.ngamia.cc/v1
NGAMIA_API_KEY=ngm_xxxxxxxxxxxxxxxx
NGAMIA_MODEL=openai/gpt-4o-mini
# Agent
AGENT_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxx
AGENT_DB_PATH=agent.db
AGENT_DEFAULT_MODE=off
AGENT_HOST=0.0.0.0
AGENT_PORT=8000Authentication
MailAfrica Agent uses three separate credentials:
| Credential | Purpose | Where Used |
|---|---|---|
MAILAFRICA_API_KEY | Authenticate with MailAfrica API | MCP tools, webhook processing |
AGENT_WEBHOOK_SECRET | Verify webhook HMAC signatures | Webhook endpoint |
NGAMIA_API_KEY | Authenticate with Ngamia LLM | Auto-reply generation, chat |
Default Persona
The built-in default persona defines how the auto-reply agent behaves. You can override it per address using the agent_config MCP tool or set a global default with AGENT_DEFAULT_PERSONA.
The default persona is:
You are a helpful email assistant for MailAfrica. You respond professionally and concisely to emails on behalf of the user. You should be polite, clear, and solution-oriented. If you don’t know the answer to something, say so honestly rather than making things up.
Changing Settings
For MCP mode: Settings are read from the .env file in the project directory when the MCP server starts.
For webhook mode: Settings are read from the .env file or from environment variables set in your deployment (Docker, systemd, etc.).
Per-address agent config: The auto-reply mode and persona are stored in MailAfrica’s database (not locally) via the agent_config MCP tool. This means they persist across restarts and are shared with the MailAfrica dashboard.