Give your script or AI assistant access to your email.

• What your AI can do with it
• Installation
• Configuration
• Quick test
• CLI usage
• MCP server
• Scripting and automation
• Multi-account
• Connection handling
• Security
• License

Mailroom connects to your existing mailbox — Gmail, Outlook, Fastmail, or any IMAP provider. It does not create new email addresses or route mail through a third-party service.

Commandline users, script authors and AI assistants can search, read, download, reply to, and organize email. Two interfaces serve different environments: a CLI that outputs JSON (for terminal-based agents, scripts, and automation) and an MCP server (for web-based AI chats and MCP clients). Both expose the same operations.

• Find a booking confirmation buried in your inbox
• Download the PDF attachment from an invoice
• Check all the links in a suspicious email
• Draft a reply (with attachments) that lands in the right thread (CLI can also emit raw RFC 822 to stdout for piping into another tool)
• Move, flag, or archive messages
• Search across all folders at once
• Handle a meeting invite — check availability, draft a response

See INSTALLATION.md for Homebrew, Debian/Ubuntu (.deb), Fedora/RHEL (.rpm), and source installs.

Copy the sample and fill in your credentials:

cp examples/config.sample.toml ~/.config/mailroom/config.toml

For Gmail with OAuth2:

[imap]
host = "imap.gmail.com"
port = 993
username = "your-email@gmail.com"
use_ssl = true

[imap.oauth2]
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
refresh_token = "YOUR_REFRESH_TOKEN"

For other providers, use a password or app-specific password:

[imap]
host = "imap.your-provider.com"
port = 993
username = "your-email@provider.com"
use_ssl = true
password = "YOUR_APP_PASSWORD"

Gmail OAuth2 setup requires a Google Cloud project with the Gmail API enabled. See GMAIL_SETUP.md for the full walkthrough.

With uv (any platform):

uvx mailroom search "subject:invoice"

No installation step — uvx runs it directly. To install permanently:

uv tool install mailroom

On Ubuntu 25.04 or later, the CLI dependencies are in the standard repositories. Install them, then run directly from a clone:

sudo apt-get install python3-typer python3-dotenv python3-imapclient python3-requests

Then you can run it directly without uv

python3 -m mailroom search "subject:invoice"

Mailroom looks for a config file at ~/.config/mailroom/config.toml. Use --config /path/to/config.toml to point to a different location.

The MCP server (mailroom mcp) requires the mcp Python package, which is not in apt. Use uv or pip for that. Manuy people prefer to use cli instead of mcp as the latter loads 80+ tools into every conversation, in that case no need to install mcp package.

Every command outputs JSON to stdout. Errors go to stderr. This makes Mailroom composable with jq, shell scripts, and AI agent skill definitions.

# What's unread?
mailroom search "is:unread" --folder INBOX --limit 10

# Search by subject across all folders
mailroom search 'subject:"hotel booking"'

# Read an email
mailroom read -f INBOX -u 4523

# List and download attachments
mailroom attachments -f INBOX -u 4523
mailroom save -f INBOX -u 4523 -i itinerary.pdf -o /tmp/itinerary.pdf

# Export an HTML email as a standalone file (images embedded)
mailroom export -f INBOX -u 4523 -o /tmp/email.html
mailroom export -f INBOX -u 4523 -o /tmp/email.eml --raw  # raw RFC 822 bytes; use -o - to stream

# Extract all links from several emails (useful for phishing checks)
mailroom links -f INBOX -u 4523 -u 4524 -u 4525

# Draft a threaded reply
mailroom reply -f INBOX -u 4523 -b "Thanks, confirmed."
mailroom reply -f INBOX -u 4523 -b "Invoice attached." --attach /tmp/invoice.pdf

# Organize
mailroom move -f INBOX -u 4523 -t Archive
mailroom mark-read -f INBOX -u 4524
mailroom flag -f INBOX -u 4525

Run mailroom --help for the full command list.

For AI environments that cannot run shell commands (Claude web, Cursor, or any MCP client):

mailroom mcp

This starts an MCP server exposing the same operations as tools. The MCP package is only imported when this subcommand runs, so the CLI stays lightweight.

Because every command returns JSON and uses non-zero exit codes on failure, Mailroom works as a building block in pipelines and cron jobs. A few patterns:

# Forward all emails from a sender to another folder
mailroom search "from:sender@example.com" --folder INBOX \
  | jq -r '.[].uid' \
  | xargs -I{} mailroom move -f INBOX -u {} -t Forwarded

# Daily digest: save today's unread subjects to a file
mailroom search "is:unread" --folder INBOX \
  | jq -r '.[].subject' > ~/daily-digest.txt

AI agents with skill/hook systems can call Mailroom the same way — define a skill that runs a shell command and parses the JSON output.

A single config file can hold multiple accounts:

default_account = "personal"

[accounts.personal]
host = "imap.gmail.com"
username = "you@gmail.com"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
refresh_token = "YOUR_REFRESH_TOKEN"

[accounts.work]
host = "outlook.office365.com"
username = "you@company.com"
password = "YOUR_APP_PASSWORD"

Select an account with -a:

mailroom -a work search "is:unread"

IMAP servers drop idle connections after 10-30 minutes. AI assistants work in bursts — a flurry of operations, then thinking time. Mailroom tracks connection age and reconnects transparently before operations fail. The default idle timeout is 300 seconds; set idle_timeout in the config to adjust.

Mailroom accesses your email account. Store credentials outside your repository (environment variables, a secrets manager, or a config file in .gitignore). Use app-specific passwords or OAuth2 rather than your main account password. Restrict allowed_folders in the config to limit what the tool can see.

MIT. See LICENSE.