agenticmail

AgenticMail is a self-hosted communication platform that gives AI agents their own real email addresses and phone numbers, with access to a REST API (75+ endpoints) and MFA-ready security guards. It runs a local Stalwart mail server inside a Docker container and integrates Google Voice for SMS and phone number access. The system is designed to work with any MCP-compatible AI client and OpenClaw via a plugin, enabling agent-to-agent email, RPC calls, and structured tool interactions. Once deployed, you can manage multi-agent mailboxes, send/receive email and SMS, and orchestrate tasks through the built-in RPC and tool integrations. The platform also supports toying with domain-based gateway modes, real-time notifications via SSE, and a 44-command interactive shell for debugging and management.

To use it, deploy the Docker image and expose the REST API for your MCP client to authenticate with a Bearer token. Create agents, assign them unique email addresses and phone numbers, and leverage the 75+ API endpoints to perform mail operations, gateway actions, and SMS interactions. OpenClaw integration allows you to extend capabilities with a broad set of tools, while the interactive CLI lets you explore the system locally with real-time previews and retries. The MCP layer ensures your AI clients can discover and call the available tools in a structured, secure manner.

Prerequisites:

• Docker installed and running on the host
• Optional: Docker Compose if you prefer a compose-based setup
• Basic familiarity with MCP clients and Bearer token authentication

Install and run with Docker:

1. Pull and run the AgenticMail image:

   docker pull agenticmail/agenticmail:latest docker run -i --rm -p 8080:80 agenticmail/agenticmail:latest

   Notes:

   • The container exposes the REST API on port 80 inside the container; map it to your host port as needed (example above maps to host 8080).
   • If the image requires environment variables (e.g., to configure Google Voice, SMTP relay, or domain gateway settings), pass them with -e VAR=value or via a Docker Compose file.

2. If you prefer natively running via Node.js (if provided as a package), install Node.js (v20+), then run the server as directed by the repository (example placeholder):

   npm install -g agenticmail agenticmail

3. Configure MCP:

   • Ensure your MCP client can reach the server's API endpoint (e.g., http://your-host:8080/api).
   • Provide a Bearer token for authentication when interfacing with the REST API.

4. Optional: Set up Google Voice integration and domain gateway options according to your environment and network topology. Refer to the Configuration section of the repository for details on DNS, DKIM, and Cloudflare-based gateway setup.

Tips and common issues:

• Ensure Docker has enough memory and CPU allocated; a full deployment with SMS relay and domain gateway can be resource-intensive.
• If you use the Gmail relay gateway, verify OAuth scopes and IMAP access for the relay account.
• When configuring Google Voice integration, ensure the GV account permissions and 2FA handling align with automated access.
• If you encounter API authentication errors, re-check the Bearer token generation flow and ensure the token has the required scopes for MCP endpoints.
• For domain gateway mode, you’ll need DNS management (MX, SPF, DKIM, DMARC) and a Cloudflare setup; double-check DNS propagation if you change records.
• The platform supports OpenClaw plugin usage; ensure compatible OpenClaw version alignment to avoid runtime enzyme mismatches.
• Use the interactive CLI for quick debugging: it provides 44 shell commands with previews, retries, and navigation to inspect statuses.
• Regular updates via agenticmail update or the /update endpoint help maintain compatibility with new MCP tools and OpenClaw changes.