API Reference

Reference documentation for the core Python modules in MailAfrica Agent.

MailAfricaClient

Module: mailafrica_agent.mailafrica

Async HTTP client for the MailAfrica REST API.

Constructor

MailAfricaClient(base_url: str, api_key: str, timeout: float = 20.0)

Methods

Outbound Email

Method	Signature	Returns
`send_email`	`(to, subject, text_body="", html_body="", cc=None, bcc=None, from_domain_id=None, from_address=None)`	Send result
`list_outbound`	`(limit=20)`	List of outbound emails
`get_outbound`	`(message_id)`	Outbound email details

Inbound Email

Method	Signature	Returns
`list_addresses`	`()`	List of inbound addresses
`create_address`	`(local_part, label="")`	New address details
`delete_address`	`(address_id)`	Confirmation
`list_messages`	`(address_id, unread=False, limit=20)`	List of messages
`get_message`	`(message_id)`	Full message with body
`mark_read`	`(message_id)`	Confirmation

Sending Domains

Method	Signature	Returns
`list_sending_domains`	`()`	List of domains
`add_sending_domain`	`(domain)`	DNS records
`verify_sending_domain`	`(domain_id)`	Verification result

Webhooks

Method	Signature	Returns
`list_webhooks`	`(address_id)`	List of webhooks
`create_webhook`	`(address_id, url, secret="")`	Webhook details
`delete_webhook`	`(webhook_id)`	Confirmation
`test_webhook`	`(webhook_id)`	Test result

Agent Config

Method	Signature	Returns
`get_agent_config`	`(address_id)`	Config object
`set_agent_config`	`(address_id, mode, persona=None, ...)`	Config object
`list_agent_configs`	`()`	List of configs
`draft_reply`	`(address_id, subject, text_body)`	Draft text

Billing

Method	Signature	Returns
`balance`	`()`	Wallet balance (TZS)

Error Handling

All methods raise MailAfricaError on API failure. The error includes the API’s error message.

from mailafrica_agent.mailafrica import MailAfricaClient, MailAfricaError
 
client = MailAfricaClient("https://api.mailafrica.online", "your_key")
 
try:
    result = await client.send_email(to=["test@example.com"], subject="Hi", text_body="Hello")
except MailAfricaError as e:
    print(f"API error: {e}")

NgamiaClient

Module: mailafrica_agent.ngamia

Async LLM client wrapping the OpenAI SDK, pointed at the Ngamia gateway.

Constructor

NgamiaClient(base_url: str, api_key: str, model: str, timeout: float = 60.0)

Methods

Method	Signature	Returns
`complete`	`(messages: list[dict])`	Reply text
`complete_with_tools`	`(messages: list[dict], tools: list[dict])`	Reply with tool calls
`list_models`	`()`	List of model IDs

Usage

from mailafrica_agent.ngamia import NgamiaClient
 
client = NgamiaClient(
    base_url="https://api.ngamia.cc/v1",
    api_key="ngm_xxx",
    model="openai/gpt-4o-mini"
)
 
# Simple completion
reply = await client.complete([
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
])
 
# Completion with tool use
reply = await client.complete_with_tools(
    messages=[{"role": "user", "content": "Send an email to alice@example.com"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "send_email",
            "description": "Send an email",
            "parameters": {
                "type": "object",
                "properties": {
                    "to": {"type": "array", "items": {"type": "string"}},
                    "subject": {"type": "string"},
                    "text_body": {"type": "string"}
                }
            }
        }
    }]
)

Store

Module: mailafrica_agent.store

SQLite-backed conversation memory store.

Constructor

Store(db_path: str)

Methods

Method	Signature	Returns
`connect`	`()`	None (initializes DB)
`close`	`()`	None
`add_message`	`(thread_key, role, content, message_id)`	None
`get_thread`	`(thread_key, limit=40)`	List of messages

Thread Key

The thread key uniquely identifies an email conversation:

import re
 
def make_thread_key(sender: str, subject: str) -> str:
    normalized = re.sub(r"^\s*(re|fw|fwd)\s*:\s*", "", subject, flags=re.IGNORECASE)
    return f"{sender.lower()}:::{normalized or '(no subject)'}"

Database Schema

CREATE TABLE IF NOT EXISTS conversations (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    thread_key  TEXT NOT NULL,
    role        TEXT NOT NULL,
    content     TEXT NOT NULL,
    message_id  INTEGER NOT NULL,
    created_at  TEXT NOT NULL
);

Agent

Module: mailafrica_agent.agent

Orchestrates the auto-reply pipeline and chat with tool-use.

Constructor

Agent(settings: Settings, mail: MailAfricaClient, ngamia: NgamiaClient, store: Store)

Methods

Method	Signature	Returns
`handle_message`	`(message_id: int, address_id: int)`	Reply text or None
`chat`	`(messages: list[dict])`	Response text

handle_message

The main auto-reply pipeline:

Fetches the inbound message
Runs safety checks
Loads address config
Appends to conversation thread
Calls LLM with persona + history
Records reply, sends or drafts

Returns the reply text if generated, None if skipped.

chat

HTTP-accessible chat endpoint with tool-use support. The LLM can call:

send_email — Send an outbound email
wallet_balance — Check wallet balance
list_inbound_addresses — List receiving addresses

Settings

Module: mailafrica_agent.config

Pydantic Settings class loaded from environment variables.

from mailafrica_agent.config import Settings
 
settings = Settings()
print(settings.mailafrica_api_key)
print(settings.ngamia_model)
print(settings.agent_db_path)

All fields have sensible defaults. Sensitive fields (API keys) default to empty strings and must be set via environment variables or .env.

Deployment Contributing