Quickstart

Quickstart

Get MailAfrica Agent running and connected to your AI assistant in under 5 minutes.

Prerequisites

  • Python 3.11 or later
  • uv package manager (recommended) or pip
  • A MailAfrica account with an API key
  • A Ngamia API key (for auto-reply features)

Step 1: Clone and Install

git clone https://github.com/cameltech/MailAfrica-Agent.git
cd MailAfrica-Agent
cp .env.example .env
# Edit .env with your API keys
uv sync

Step 2: Configure Environment

Edit .env with your credentials:

MAILAFRICA_API_KEY=your_mailafrica_api_key
NGAMIA_API_KEY=your_ngamia_api_key
NGAMIA_MODEL=openai/gpt-4o-mini
AGENT_WEBHOOK_SECRET=your_webhook_secret

See Configuration for all available options.

Step 3: Verify Connectivity

uv run mailafrica-agent check

This pings both the MailAfrica API and Ngamia to confirm your keys work.

Step 4: Connect to Your AI Assistant

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mailafrica-agent": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/MailAfrica-Agent",
        "mailafrica-agent",
        "mcp"
      ]
    }
  }
}

Replace /path/to/MailAfrica-Agent with the actual path to your cloned repo.

Claude Code

Add to your MCP settings (usually ~/.config/claude-code/mcp.json or project-level):

{
  "mcpServers": {
    "mailafrica-agent": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/MailAfrica-Agent",
        "mailafrica-agent",
        "mcp"
      ]
    }
  }
}

Cursor

Go to Settings > MCP and add a new server:

{
  "mailafrica-agent": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/MailAfrica-Agent",
      "mailafrica-agent",
      "mcp"
    ]
  }
}

Any MCP Client (Generic)

The MCP server communicates over stdio. Any MCP client can connect by running:

uv run mailafrica-agent mcp

Step 5: Test It

Once connected, try these prompts in your AI assistant:

  • “List my inbound email addresses”
  • “Send a test email to myself”
  • “What’s my wallet balance?”
  • “Show me my sending domains”

Running the Webhook Server (Optional)

To enable the auto-reply agent and chat endpoints, run the webhook server:

uv run mailafrica-agent webhook

This starts a FastAPI server on port 8097. Point your MailAfrica webhook to:

https://agent.mailafrica.online/webhooks/mailafrica

See Webhook Setup for details.

What’s Next?

IntroductionConfiguration