AIMX user guide
AIMX (AI Mail Exchange) is a self-hosted SMTP server that gives AI agents their own addresses on a domain you control. Mail is parsed into Markdown with TOML frontmatter and written to disk. Agents read and send through the built-in MCP server, the aimx CLI, or the filesystem directly. aimx serve is the daemon; every other subcommand is short-lived.
Join the AIMX Discord → Questions, hook recipes, and agent integrations.
How it works
- Single binary. Written in Rust. No runtime dependencies.
aimx serveis the daemon. Embedded SMTP listener for inbound mail. Every other command is short-lived.- No IMAP / POP3. Agents read
.mdfiles via MCP or the filesystem. - Markdown-first. Mail is stored as Markdown with TOML frontmatter, LLM- and RAG-friendly without a parser.
Quick start
curl -fsSL https://aimx.email/install.sh | sh
This launches a guided setup with the following steps:
- Preflight checks on port 25
- Set up domain and DNS
- Set up STARTTLS certificate
- Set up trust policy
- Install AIMX service
- Optionally, wire up MCP for agent(s)
See Installation for install flags, verification, and upgrades, and Getting Started for the full walkthrough.
Guide contents
| Page | What it covers |
|---|---|
| Getting Started | Requirements, installation, first setup |
| Installation | One-line installer, flags, verification, aimx upgrade, rollback |
| Setup | DNS, verification, DKIM key management, production hardening |
| Configuration | config.toml field reference, data / config directories, environment variables |
| Security | Threat model, trust boundaries, what AIMX defends and what it does not |
| Mailboxes & Email | Mailbox CRUD, email frontmatter, attachments, sending, threading |
| Markdown Email | How outbound --body is rendered to HTML, the inlined stylesheet, escape hatches |
| Hooks & Trust | on_receive / after_send events, ownership-as-authorization, trust gate |
| Hook Recipes | Copy-paste hook snippets per agent (Claude Code, Codex, OpenCode, Gemini, Goose, OpenClaw, Hermes, NanoClaw) |
| MCP Server | The 12 MCP tools: parameters, frontmatter contract, workflow examples |
| Agent Integration | aimx agents setup installer, per-agent configuration, manual MCP wiring |
| CLI Reference | Every aimx subcommand and flag |
| Troubleshooting | Diagnostics, common issues, useful commands |
| FAQ | Deployment, DNS, storage, MCP, and operations questions |
Ready to try AIMX?
One command, one box, one inbox.
Get started