Auto-Reply Agent

The auto-reply agent reads inbound emails and generates contextual replies using an LLM. It can reply automatically, save drafts for review, or be turned off.

How It Works

When an inbound email arrives and a webhook is configured:

1. MailAfrica receives the email and sends a webhook to your agent
2. HMAC signature is verified using AGENT_WEBHOOK_SECRET
3. The agent processes the message in the background:
   • Fetches the full message from MailAfrica API
   • Runs safety checks (drops bounces, auto-responders, bulk mail)
   • Loads the per-address config (mode, persona)
   • Appends the message to the conversation thread in SQLite
   • Calls the LLM with the full thread history and persona
   • Records the reply and either sends it or saves it as a draft
4. Returns immediately with {"status": "queued"}

Safety Features

The agent has several built-in safety mechanisms:

Reply-Loop Protection

The agent never auto-replies to:

• Bounces — messages from MAILER-DAEMON or postmaster
• Auto-responders — messages with X-Auto-Reply, Auto-Submitted: auto, or Precedence: auto headers
• Bulk mail — messages with List-Unsubscribe headers

Off by Default

Auto-reply is off by default for all addresses. You must explicitly enable it per address.

Draft Mode

Set mode to draft to review replies before they’re sent. The agent generates the reply but doesn’t send it.

HMAC Verification

Webhook deliveries are verified using HMAC-SHA256 signatures. This prevents unauthorized message injection.

Configuration

Via MCP Tool

agent_config(
    address_id=1,
    mode="auto",
    persona="You are a support agent for Acme Corp. Be professional and helpful.",
    reply_from_domain_id=2,
    reply_from_address="support@acme.com"
)

Via MailAfrica Dashboard

Go to Inbox > Select Address > AI Auto-reply card in the MailAfrica web dashboard.

Configuration Fields

Personas

The persona is the system prompt that guides the LLM’s replies. Good personas are specific and contextual.

Example Personas

Customer Support:

You are a friendly and professional customer support agent for Acme Corp.
Respond to customer inquiries helpfully and concisely.
If you don't know the answer, say you'll look into it and follow up.
Always be polite and solution-oriented.

Sales:

You are a sales representative for TechCorp.
Answer product questions accurately and highlight benefits.
If someone requests a demo or quote, acknowledge it and note that a team member will follow up.
Never make up pricing — direct them to our pricing page or ask them to contact sales.

Internal Notifications:

You are an automated notification handler.
Acknowledge receipt of the message professionally.
Log the key details and confirm the appropriate team has been notified.

Conversation Memory

The agent maintains conversation threads in SQLite:

• Thread key = sender_email:::normalized_subject
• History = last 40 turns (messages + replies)
• Persistence = threads survive restarts

This means the agent remembers previous exchanges in the same email thread, enabling contextual multi-turn conversations.

Viewing Status

Check which addresses have auto-reply configured:

agent_status()

Returns a list of all configured addresses with their current mode and persona.

Manual Processing

Process a specific message manually:

agent_handle_message(message_id=789, address_id=1)

This runs the full auto-reply pipeline on-demand. Useful for:

• Testing your configuration
• Processing messages that arrived before auto-reply was set up
• Re-processing a message that failed

Draft Review

Generate a draft without sending:

agent_draft(
    address_id=1,
    subject="Re: Support request",
    text_body="I'm having trouble logging in to my account."
)

Returns the generated reply text. Nothing is sent or stored.

LLM Model

The agent uses the model configured in NGAMIA_MODEL (default: openai/gpt-4o-mini). You can change this in your .env file or use the list_models MCP tool to see available options.