Skip to content
Back to search

email-mcp

Email MCP server with full IMAP + SMTP support — read, search, send, manage, and organize email from any AI assistant via the Model Context Protocol

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/codefuturist/email-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/codefuturist/email-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/codefuturist--email-mcp/badge.svg)](/listings/codefuturist--email-mcp)

HTML

<a href="/listings/codefuturist--email-mcp"><img src="/api/listings/codefuturist--email-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node.js ≥ 22.

# Run directly (no install needed)
npx @codefuturist/email-mcp setup
# or
pnpm dlx @codefuturist/email-mcp setup

# Or install globally
npm install -g @codefuturist/email-mcp
# or
pnpm add -g @codefuturist/email-mcp

Docker

No Node.js required — just Docker.

# Latest stable release
docker pull ghcr.io/codefuturist/email-mcp:latest

# Pin to an exact version (immutable)
docker pull ghcr.io/codefuturist/email-mcp:0.2.3

# Auto-update patches within a minor version
docker pull ghcr.io/codefuturist/email-mcp:0.2

# Track a major version (won't cross breaking-change boundary)
docker pull ghcr.io/codefuturist/email-mcp:0

# Pin to an exact git commit (immutable, CI traceability)
docker pull ghcr.io/codefuturist/email-mcp:sha-abc1234

# Or build from source
docker build -t ghcr.io/codefuturist/email-mcp .

> **Tag convention:** Tags follow bare semver (no `v` prefix), matching Docker ecosystem standards (e.g. `node:24`, `nginx:1.25`). The `latest` tag is only updated on stable releases, never pre-releases.

> **Note:** The server uses stdio transport. Config must be created on the host first > (via `npx @codefuturist/email-mcp setup` or manually) and mounted into the container.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,516 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Email MCP Server
  2. [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
  3. [![license](https://img.shields.io/github/license/codefuturist/email-mcp.svg?style=flat-square)](LICENSE)
  4. [![npm version](https://img.shields.io/npm/v/@codefuturist/email-mcp.svg?style=flat-square)](https://www.npmjs.com/package/@codefuturist/email-mcp)
  5. [![npm downloads](https://img.shields.io/npm/dm/@codefuturist/email-mcp.svg?style=flat-square)](https://www.npmjs.com/package/@codefuturist/email-mcp)
  6. [![CI](https://img.shields.io/github/actions/workflow/status/codefuturist/email-mcp/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/codefuturist/email-mcp/actions/workflows/ci.yml)
  7. An MCP (Model Context Protocol) server providing comprehensive email capabilities via IMAP and SMTP.
  8. Enables AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts. Exposes 52 tools, 7 prompts, and 6 resources over the MCP protocol with OAuth2 support _(experimental)_, email scheduling, calendar extraction, analytics, provider-aware label management, real-time IMAP IDLE watcher with AI-powered triage, instant verification-code catching with clipboard copy, customizable presets and static rules, and a guided setup wizard.
  9. Built on the MCP TypeScript SDK v2 (spec revision 2026-07-28), it serves over **stdio** for local clients or **Streamable HTTP** for networked access — existing stdio configurations keep working unchanged.
  10. ## Highlights
  11. | Feature | email-mcp | Typical MCP email |
  12. |---------|:---------:|:-----------------:|
  13. | Multi-account | ✅ | ❌ |
  14. | Send / reply / forward | ✅ | ✅ |
  15. | Drafts & templates | ✅ | ❌ |
  16. | Labels & bulk ops | ✅ provider-aware | ❌ |
  17. | Schedule future emails | ✅ | ❌ |
  18. | Real-time IMAP IDLE watcher | ✅ | ❌ |
  19. | Verification codes → clipboard | ✅ concealed + auto-clear | ❌ |
  20. | AI triage with presets | ✅ | ❌ |
  21. | Desktop & webhook alerts | ✅ | ❌ |
  22. | Calendar (ICS) extraction | ✅ | ❌ |
  23. | Email analytics | ✅ | ❌ |
  24. | OAuth2 (Gmail / M365) | ✅ _experimental_ | ❌ |
  25. | Guided setup wizard | ✅ auto-detect | ❌ |
  26. | Streamable HTTP transport | ✅ | ❌ |
  27. ## Table of Contents
  28. - [Highlights](#highlights)
  29. - [Security](#security)
  30. - [Background](#background)
  31. - [Install](#install)
  32. - [Usage](#usage)
  33. - [API](#api)
  34. - [Roadmap](#roadmap)
  35. - [Maintainers](#maintainers)
  36. - [Contributing](#contributing)
  37. - [License](#license)
  38. ## Security
  39. - All connections use TLS/STARTTLS encryption
  40. - Passwords are never logged; audit trail records operations without credentials
  41. - Token-bucket rate limiter prevents abuse (one bucket per account, sharing a global `rate_limit`)
  42. - OAuth2 XOAUTH2 authentication for Gmail and Microsoft 365 _(experimental)_
  43. - Attachment downloads capped at 5 MB with base64 encoding
  44. ## Background
  45. Most MCP email implementations provide only basic read/send. This server aims to be a full-featured email client for AI assistants, covering the entire lifecycle: reading, composing, managing, scheduling, and analyzing email — all from a single MCP server.
  46. Key design decisions:
  47. - **XDG-compliant config** — TOML at `~/.config/email-mcp/config.toml`
  48. - **Multi-account** — Operate across multiple IMAP/SMTP accounts simultaneously
  49. - **Layered services** — Business logic is decoupled from MCP wiring for testability
  50. - **Provider auto-detection** — Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, Zoho, GMX
  51. ## Install
  52. Requires Node.js ≥ 24.
  53. ```bash
  54. # Run directly (no install needed)
  55. npx @codefuturist/email-mcp setup
  56. # or
  57. pnpm dlx @codefuturist/email-mcp setup
  58. # Or install globally
  59. npm install -g @codefuturist/email-mcp
  60. # or
  61. pnpm add -g @codefuturist/email-mcp
  62. ```
  63. `npm install -g` fails with `EACCES` when npm's global prefix is a root-owned
  64. directory (common on a system Node install) — the `npx`/`pnpm dlx` form above
  65. avoids this entirely by not installing anything globally. If you do want a
  66. permanent global install, fix npm's prefix instead of reaching for `sudo`
  67. (`npm config set prefix ~/.npm-global` and add that to `PATH`, or use a Node
  68. version manager like `nvm`/`fnm`/`volta`) — running `npm install -g` as root
  69. routinely leaves root-owned files mixed into a user-owned `node_modules` tree,
  70. which causes harder-to-diagnose permission errors on the *next* global install.
  71. ### Homebrew (native binary)
  72. The prebuilt, dependency-free binary — no Node.js at runtime — from the
  73. [codefuturist tap](https://github.com/codefuturist/homebrew-tap):
  74. ```bash
  75. brew install codefuturist/tap/email-mcp
  76. ```
  77. Published as a cask on every stable release; works on macOS (arm64 + x64) and
  78. on Linuxbrew ≥ 4.3 (binary-only casks).
  79. ### Native binary (Bun)
  80. A dependency-free single binary (minified + bytecode-precompiled, ~32 ms cold
  81. start, no Node.js at runtime) can be compiled with [Bun](https://bun.sh):
  82. ```bash
  83. bun run build:binary # native binary → build/email-mcp
  84. cp build/email-mcp ~/.local/bin/
  85. bun run build:binaries # release matrix: darwin-arm64/x64, linux-x64/arm64,
  86. # windows-x64 → build/release/*.{tar.gz,zip} + sha256 checksums
  87. ```
  88. Prebuilt binaries for every release are built by CI with GoReleaser Pro
  89. (`.goreleaser.yaml`) for all common platforms — Linux glibc + musl, macOS, and
  90. Windows, each x64 + arm64 where Bun supports it — provenance-attested (verify with
  91. `gh attestation verify <asset> --repo codefuturist/email-mcp`) and shipped with
  92. [GitHub releases](https://github.com/codefuturist/email-mcp/releases) —
  93. installable via mise: `mise use -g ubi:codefuturist/email-mcp`.
  94. The same binary can also be built locally from the published npm package (no
  95. checkout needed; ≥ 0.5.1, which carries the imapflow TLS fix at runtime —
  96. older versions need the repo's pnpm patch). Note that a plain `bun add -g`
  97. shim executes `dist/main.js` under node via its shebang, so the compile step
  98. is what buys the ~11 ms cold start:
  99. ```bash
  100. bun add -g @codefuturist/email-mcp
  101. bun build --compile --minify --bytecode \
  102. "${BUN_INSTALL:-$HOME/.bun}/install/global/node_modules/@codefuturist/email-mcp/dist/main.js" \
  103. --outfile ~/.local/bin/email-mcp
  104. ```
  105. An installed binary keeps itself current: `email-mcp update` checks the latest
  106. release and — after a confirmation, a sha256 check against the release's
  107. checksums file, and (when the `gh` CLI is present) a provenance-attestation
  108. check — atomically replaces itself. `--check` only reports (exit code 1 =
  109. update available), `--yes` skips the prompt for scripts. npm- and mise-managed
  110. installs are recognized and pointed at `npm install -g …@latest` /
  111. `mise upgrade` instead of being overwritten.
  112. `server install` from the binary points the launchd login item at it. Requires the
  113. bundled imapflow patch (`patches/`) — imapflow passes `servername: false` to
  114. tls.connect for IP hosts, which Bun's stricter node:tls rejects.
  115. ### Docker
  116. No Node.js required — just Docker.
  117. ```bash
  118. # Latest stable release
  119. docker pull ghcr.io/codefuturist/email-mcp:latest
  120. # Pin to an exact version (immutable)
  121. docker pull ghcr.io/codefuturist/email-mcp:0.2.3
  122. # Auto-update patches within a minor version
  123. docker pull ghcr.io/codefuturist/email-mcp:0.2
  124. # Track a major version (won't cross breaking-change boundary)
  125. docker pull ghcr.io/codefuturist/email-mcp:0
  126. # Pin to an exact git commit (immutable, CI traceability)
  127. docker pull ghcr.io/codefuturist/email-mcp:sha-abc1234
  128. # Or build from source
  129. docker build -t ghcr.io/codefuturist/email-mcp .
  130. ```
  131. > **Tag convention:** Tags follow bare semver (no `v` prefix), matching Docker ecosystem standards (e.g. `node:24`, `nginx:1.25`). The `latest` tag is only updated on stable releases, never pre-releases.
  132. > **Note:** By default, the server uses stdio transport. Config must be created on the host first
  133. > (via `npx @codefuturist/email-mcp setup` or manually) and mounted into the container.
  134. ## Usage
  135. ### Setup
  136. ```bash
  137. # Add an email account interactively (recommended)
  138. # On macOS and Linux this offers to store the password in the OS keychain,
  139. # so config.toml only carries a `keychain:<account>` reference.
  140. email-mcp account add
  141. # Or use the legacy alias
  142. email-mcp setup
  143. # Or create a template config manually
  144. email-mcp config init
  145. ```
  146. The setup wizard auto-detects server settings, tests connections, saves config, and outputs the MCP client config snippet.
  147. ### Test Connections
  148. ```bash
  149. email-mcp test # all accounts
  150. email-mcp test personal # specific account
  151. ```
  152. ### Configure Your MCP Client
  153. The snippets below use the default **stdio** transport, best for local desktop clients. For networked or remote access over **Streamable HTTP**, see [Streamable HTTP (networked)](#streamable-http-networked) below.
  154. **Recommended — use the guided installer** (auto-detects Claude Desktop, Cursor, Windsurf; for VS Code use the manual snippet below):
  155. ```bash
  156. email-mcp install
  157. ```
  158. Or add manually using the snippets below.
  159. <details>
  160. <summary><strong>Claude Desktop</strong></summary>
  161. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  162. ```json
  163. {
  164. "mcpServers": {
  165. "email": {
  166. "command": "npx",
  167. "args": ["-y", "@codefuturist/email-mcp", "stdio"]
  168. }
  169. }
  170. }
  171. ```
  172. </details>
  173. <details>
  174. <summary><strong>VS Code (GitHub Copilot)</strong></summary>
  175. **Option 1 — Extensions gallery (easiest):**
  176. 1. Open the Extensions view (<kbd>⇧⌘X</kbd> / <kbd>Ctrl+Shift+X</kbd>)
  177. 2. Search `@mcp email-mcp`
  178. 3. Click **Install** (user-wide) or right-click → **Install in Workspace**
  179. **Option 2 — Workspace config** (`.vscode/mcp.json`, committed to source control):
  180. ```json
  181. {
  182. "servers": {
  183. "email": {
  184. "type": "stdio",
  185. "command": "npx",
  186. "args": ["-y", "@codefuturist/email-mcp", "stdio"]
  187. }
  188. }
  189. }
  190. ```
  191. **Option 3 — User config** (`settings.json`, applies to all workspaces):
  192. Open the Command Palette → **Preferences: Open User Settings (JSON)** and add:
  193. ```json
  194. {
  195. "mcp": {
  196. "servers": {
  197. "email": {
  198. "type": "stdio",
  199. "command": "npx",
  200. "args": ["-y", "@codefuturist/email-mcp", "stdio"]
  201. }
  202. }
  203. }
  204. }
  205. ```
  206. </details>
  207. <details>
  208. <summary><strong>Cursor</strong></summary>
  209. Edit `~/.cursor/mcp.json`:
  210. ```json
  211. {
  212. "mcpServers": {
  213. "email": {
  214. "command": "npx",
  215. "args": ["-y", "@codefuturist/email-mcp", "stdio"]
  216. }
  217. }
  218. }
  219. ```
  220. </details>
  221. <details>
  222. <summary><strong>Windsurf</strong></summary>
  223. Edit `~/.codeium/windsurf/mcp_config.json`:
  224. ```json
  225. {
  226. "mcpServers": {
  227. "email": {
  228. "command": "npx",
  229. "args": ["-y", "@codefuturist/email-mcp", "stdio"]
  230. }
  231. }
  232. }
  233. ```
  234. </details>
  235. <details>
  236. <summary><strong>Zed</strong></summary>
  237. Edit `~/.config/zed/settings.json`:
  238. ```json
  239. {
  240. "context_servers": {
  241. "email": {
  242. "command": {
  243. "path": "npx",
  244. "args": ["-y", "@codefuturist/email-mcp", "stdio"]
  245. }
  246. }
  247. }
  248. }
  249. ```
  250. </details>
  251. <details>
  252. <summary><strong>Mistral Vibe</strong></summary>
  253. Add to `~/.vibe/config.toml`:
  254. ```toml
  255. [[mcp_servers]]
  256. name = "email-mcp"
  257. transport = "stdio"
  258. command = "npx"
  259. args = ["-y", "@codefuturist/email-mcp", "stdio"]
  260. ```
  261. To pass credentials directly instead of using a config file, use the `env` field:
  262. ```toml
  263. [[mcp_servers]]
  264. name = "email-mcp"
  265. transport = "stdio"
  266. command = "npx"
  267. args = ["-y", "@codefuturist/email-mcp", "stdio"]
  268. env = { "EMAIL_ACCOUNTS" = "<your-accounts-json>" }
  269. ```
  270. MCP tools are exposed as `email-mcp_<tool_name>` (e.g. `email-mcp_list_emails`). Restart Vibe after editing the config.
  271. </details>
  272. <details>
  273. <summary><strong>Docker (any MCP client)</strong></summary>
  274. Run the server in a container — mount your config directory read-only:
  275. ```bash
  276. docker run --rm -i \
  277. -v ~/.config/email-mcp:/home/node/.config/email-mcp:ro \
  278. -v email-mcp-state:/home/node/.local/state/email-mcp \
  279. -v email-mcp-cache:/home/node/.cache/email-mcp \
  280. ghcr.io/codefuturist/email-mcp
  281. ```
  282. The config mount can stay read-only, but **state and cache must be persisted**.
  283. The image declares both as volumes, so Docker keeps them in anonymous volumes
  284. if you omit the flags — naming them, as above, is what makes them survive a
  285. `docker run --rm`. State holds the scheduled-email queue: without it, a restart
  286. drops every email scheduled but not yet sent. Cache holds the local mirror,
  287. which is regenerable, so losing that only costs a re-sync.
  288. For MCP client configuration (e.g. Claude Desktop):
  289. ```json
  290. {
  291. "mcpServers": {
  292. "email": {
  293. "command": "docker",
  294. "args": [
  295. "run", "--rm", "-i",
  296. "-v", "~/.config/email-mcp:/home/node/.config/email-mcp:ro",
  297. "-v", "email-mcp-state:/home/node/.local/state/email-mcp",
  298. "-v", "email-mcp-cache:/home/node/.cache/email-mcp",
  299. "ghcr.io/codefuturist/email-mcp"
  300. ]
  301. }
  302. }
  303. }
  304. ```
  305. </details>
  306. <details>
  307. <summary><strong>Single-account via environment variables (no config file needed)</strong></summary>
  308. ```json
  309. {
  310. "mcpServers": {
  311. "email": {
  312. "command": "npx",
  313. "args": ["-y", "@codefuturist/email-mcp", "stdio"],
  314. "env": {
  315. "MCP_EMAIL_ADDRESS": "you@gmail.com",
  316. "MCP_EMAIL_PASSWORD": "your-app-password",
  317. "MCP_EMAIL_IMAP_HOST": "imap.gmail.com",
  318. "MCP_EMAIL_SMTP_HOST": "smtp.gmail.com"
  319. }
  320. }
  321. }
  322. }
  323. ```
  324. </details>
  325. ### Always-on server (detached)
  326. The stdio transport lives only as long as an MCP client keeps it open — which also
  327. means the IMAP watcher (and verification catching) stop with it. `email-mcp server`
  328. runs the Streamable HTTP server as a background service instead, iMCP-style:
  329. ```bash
  330. email-mcp server start # detached on http://127.0.0.1:8080/mcp
  331. email-mcp server start --port 3199 # any http flags pass through (--host, --token, …)
  332. email-mcp server start --attach # foreground instead (Ctrl-C stops)
  333. email-mcp server status # pid, address, /healthz, uptime
  334. email-mcp server logs -n 50 # tail the daemon log
  335. email-mcp server restart # reuses the previous flags
  336. email-mcp server stop # graceful SIGTERM (add --force for SIGKILL)
  337. ```
  338. The binding lives in the config file, so a plain `server start` is deterministic:
  339. ```toml
  340. [settings.server]
  341. host = "127.0.0.1"
  342. port = 8080
  343. path = "/mcp"
  344. token = "" # bearer token; empty = no auth (loopback only)
  345. allowed_hosts = [] # Host-header allowlist for reverse proxies
  346. ```
  347. Precedence: CLI flags → `EMAIL_MCP_HTTP_*` env → `[settings.server]` → defaults —
  348. for `email-mcp http`, `server start`, and the launchd login item alike. Edit it
  349. interactively with `config edit server` (the token renders masked). `--insecure`
  350. is deliberately flag-only and cannot be persisted.
  351. **Start at login (macOS):** `email-mcp server install` writes a launchd login item
  352. (`com.email-mcp.server`, RunAtLoad + KeepAlive) running `email-mcp http` with no
  353. flags — the config file is its single source of truth across reboots and crashes.
  354. `server status` recognizes the launchd mode; `server uninstall` removes it.
  355. State lives in `$XDG_STATE_HOME/email-mcp/daemon.json`, logs in `server.log` next to
  356. it (rotated at 5 MB). `stop` only ever signals a process whose command line is
  357. verifiably this server (PID-reuse safe). Point HTTP-capable MCP clients at
  358. `http://127.0.0.1:8080/mcp`; binding non-loopback hosts still requires a token.
  359. ### Streamable HTTP (networked)
  360. By default the server speaks MCP over **stdio**, ideal for local desktop clients (see the snippets above). For networked or remote access, run it as a **Streamable HTTP** server instead:
  361. ```bash
  362. email-mcp http --port 8080
  363. ```
  364. This serves MCP at `http://127.0.0.1:8080/mcp`, with a health probe at `GET /healthz`.
  365. #### Flags & environment variables
  366. | Flag | Environment variable | Default | Description |
  367. |------|----------------------|---------|-------------|
  368. | `--host <addr>` | `EMAIL_MCP_HTTP_HOST` | `127.0.0.1` | Address to bind |
  369. | `--port <n>` | `EMAIL_MCP_HTTP_PORT` | `8080` | Port to listen on |
  370. | `--path <path>` | `EMAIL_MCP_HTTP_PATH` | `/mcp` | HTTP path serving MCP |
  371. | `--token <secret>` | `EMAIL_MCP_HTTP_TOKEN` | — | Require `Authorization: Bearer <secret>` on every request |
  372. | `--allowed-hosts a,b,c` | `EMAIL_MCP_HTTP_ALLOWED_HOSTS` | _loopback names + bind host_ | Comma-separated `Host` header allowlist (DNS-rebinding protection); `*` disables the check |
  373. | `--insecure` | — | `false` | Allow binding a non-loopback host without a token |
  374. #### Security
  375. - **Token auth** — When a token is set, every request must send `Authorization: Bearer <token>`.
  376. - **Non-loopback bind guard** — Binding a non-loopback host (e.g. `0.0.0.0`) **without** a token is refused unless `--insecure` is passed. Use `--insecure` only when TLS and authentication are terminated by an upstream reverse proxy.
  377. - **DNS-rebinding protection** — The `Host` header is validated against an allowlist (loopback names plus the bind host by default). Set `EMAIL_MCP_HTTP_ALLOWED_HOSTS` to your public domain, or `*` to disable the check when a proxy already enforces it.
  378. #### Client configuration
  379. For clients that support the Streamable HTTP transport:
  380. ```json
  381. {
  382. "mcpServers": {
  383. "email": {
  384. "type": "streamable-http",
  385. "url": "http://127.0.0.1:8080/mcp"
  386. }
  387. }
  388. }
  389. ```
  390. When a token is configured, add an `Authorization: Bearer <token>` header if your client supports custom headers.
  391. #### Docker
  392. ```bash
  393. docker compose --profile http up
  394. ```
  395. Requires `EMAIL_MCP_HTTP_TOKEN` to be set; the image `EXPOSE`s port `8080`.
  396. ### CLI Commands
  397. ```
  398. email-mcp [command]
  399. Commands:
  400. stdio Run as MCP server over stdio (default)
  401. http Run as MCP server over Streamable HTTP (networked)
  402. server start [--attach] Start an always-on HTTP server (detached by default)
  403. server stop [--force] Stop the detached server
  404. server status Show pid, address, health, uptime (exit 1 if stopped)
  405. server restart Stop and start again (reuses previous flags)
  406. server logs [-n N] Show the last N daemon log lines
  407. server install Install as macOS login item (launchd, survives reboots)
  408. server uninstall Remove the login item and stop the server
  409. account list List all configured accounts
  410. account add Add a new email account interactively
  411. account edit [name] Edit an existing account
  412. account delete [name] Remove an account
  413. setup Alias for 'account add'
  414. test Test connections for all or a specific account
  415. open <id> [--print] Open an email in the native mail client via its message: link
  416. (macOS; --print or other platforms print the URL instead)
  417. install Register email-mcp with MCP clients interactively
  418. install status Show registration status for detected clients
  419. install remove Unregister email-mcp from MCP clients
  420. config show Show config (passwords masked)
  421. config edit [section] Interactive settings editor (general, server, send, attachments,
  422. scheduler, watcher, verification, cache, hooks, alerts)
  423. config validate Check syntax, schema, typo'd keys, and cross-setting consistency
  424. completion zsh|bash|fish Print shell completion script (accounts and sections complete dynamically)
  425. config path Print config file path
  426. config init Create template config
  427. scheduler check Process pending scheduled emails
  428. scheduler list Show all scheduled emails
  429. scheduler install Install OS-level scheduler (launchd/crontab)
  430. scheduler uninstall Remove OS-level scheduler
  431. scheduler status Show scheduler installation status
  432. cache status [--json] Show cache size, contents, coverage and freshness
  433. cache clear [--account N] Delete cached mail/attachments and free the disk space
  434. (--json supported by status, clear and verify)
  435. cache verify Check the cache for corruption and reclaim orphaned files
  436. update [--check|--yes] Self-update the binary to the latest GitHub release
  437. help Show help
  438. ```
  439. ### Shell completion
  440. ```bash
  441. # zsh (one line in ~/.zshrc)
  442. source <(email-mcp completion zsh)
  443. # bash
  444. source <(email-mcp completion bash)
  445. # fish
  446. email-mcp completion fish > ~/.config/fish/completions/email-mcp.fish
  447. ```
  448. Completions cover every command, subcommand, and flag — and complete **account
  449. names from your config** (`email-mcp test <TAB>`, `account edit <TAB>`) and
  450. **settings sections** (`config edit <TAB>`) dynamically.
  451. ### Checking logs
  452. The background daemon logs to `$XDG_STATE_HOME/email-mcp/server.log`. View it
  453. with a tail/follow/filter viewer — no need to find the file:
  454. ```bash
  455. email-mcp logs # last 40 lines (colored by level)
  456. email-mcp logs -n 200 # more lines
  457. email-mcp logs -f # live follow (Ctrl-C to stop)
  458. email-mcp logs --level warn # only WARN and ERROR (continuation lines kept)
  459. email-mcp logs --grep imap # only lines matching a substring
  460. email-mcp logs -f --level error # watch for errors as they happen
  461. ```
  462. `email-mcp server logs` is an alias with the same options. Color auto-disables
  463. when piped or under `NO_COLOR`; on a systemd host, `journalctl --user -u
  464. email-mcp` is also available.
  465. ### Reading and sending mail from the CLI
  466. Beyond running as an MCP server, `email-mcp` is a usable mail client in its own
  467. right — no MCP client and no coding required. Commands default to your first
  468. configured account (pass `--account <name>` to pick another), print clean,
  469. colored tables (color auto-disables when piped or under `NO_COLOR`), and tab
  470. complete (see [Shell completion](#shell-completion)).
  471. ```bash
  472. email-mcp list # recent INBOX messages (● unread, ★ flagged, 📎 attachment)
  473. email-mcp list --unread --limit 50 # filters
  474. email-mcp list --mailbox Archive --search invoice
  475. email-mcp read 42 # full message (headers, body, attachment names + sizes)
  476. email-mcp read 42 --mark-read
  477. email-mcp search "from bank" # IMAP search
  478. email-mcp mailboxes # folders with unread/total counts
  479. email-mcp flag 42 # flag / --off to unflag
  480. email-mcp attach 42 report.pdf ~/Downloads # save an attachment
  481. email-mcp delete 42 --yes # delete (asks to confirm without --yes)
  482. email-mcp reply 42 --body "on it" --all
  483. email-mcp send --to a@b.c,d@e.f --subject "Hi" --body "..." --attach ./file.pdf
  484. ```
  485. Every command accepts `--help`; the read commands (`list`, `read`, `search`,
  486. `mailboxes`) accept `--json` for machine-readable output you can pipe to `jq`:
  487. ```bash
  488. email-mcp list --json | jq '.items[] | {id, subject, from: .from.address}'
  489. email-mcp read 42 --json | jq .attachments
  490. ```
  491. Attachment sizes on send/reply are checked against the configured limit before
  492. anything leaves your machine (see [Storing account secrets](#storing-account-secrets)
  493. for keeping credentials out of plaintext).
  494. ### Configuration
  495. Located at `$XDG_CONFIG_HOME/email-mcp/config.toml` (default: `~/.config/email-mcp/config.toml`). Validate it with `email-mcp config validate` (TOML syntax, schema, typo'd keys with did-you-mean, cross-setting consistency; exit 1 on errors — CI-friendly) and edit it interactively with `email-mcp config edit [section]` — every save validates first and backs up the previous file to `config.toml.bak`. Note: programmatic saves rewrite the file without TOML comments (the backup keeps them).
  496. ```toml
  497. [settings]
  498. rate_limit = 10 # max emails per minute per account
  499. [settings.send]
  500. max_attachment_mb = 25 # global cap on the base64-encoded attachment total
  501. save_to_sent = false # file a copy of each sent message in the IMAP Sent folder
  502. [settings.attachments]
  503. auto_download = true # save attachments locally when calendar events are created from emails
  504. [settings.attachment_download]
  505. # dir = "/data/attachments" # unset (default) disables download_attachment's saveToDownloadDir
  506. allowed_extensions = ["pdf", "png", "jpg", "jpeg", "webp", "tiff", "txt", "md", "doc", "docx", "odt", "xls", "xlsx", "csv"]
  507. max_bytes = 26214400 # 25 MB
  508. [[accounts]]
  509. name = "personal"
  510. email = "you@gmail.com"
  511. full_name = "Your Name"
  512. password = "keychain:personal" # or "env:VAR", or a plaintext app password
  513. # max_attachment_mb = 25 # optional per-account override (beats global + provider limits)
  514. # sent_mailbox = "INBOX.Sent Messages" # optional, see "Sent-folder copies" below
  515. # save_to_sent = true # optional per-account override of the Gmail-skip guess
  516. [accounts.imap]
  517. host = "imap.gmail.com"
  518. port = 993
  519. tls = true
  520. [accounts.smtp]
  521. host = "smtp.gmail.com"
  522. port = 465
  523. tls = true
  524. starttls = false
  525. verify_ssl = true
  526. [accounts.smtp.pool]
  527. enabled = true
  528. max_connections = 1
  529. max_messages = 100
  530. ```
  531. #### Storing account secrets
  532. The `password` field (and OAuth2 `client_secret` / `refresh_token`) accepts an
  533. indirection so credentials need not sit in the file as plaintext:
  534. | Value | Resolved from |
  535. |---|---|
  536. | `keychain:<account>` | OS keychain — macOS Keychain (`security`) or Linux libsecret (`secret-tool`), service `email-mcp`, account `<account>` |
  537. | `keychain:<service>/<account>` | macOS Keychain with an explicit service name |
  538. | `env:<VAR>` | the environment variable `<VAR>` (use on Linux, or with an age/SOPS-sourced env) |
  539. | any other string | used literally (plaintext — backward compatible) |
  540. The config file itself is always written `0600` (owner-only), and so is its
  541. `.bak`.
  542. **macOS Keychain (multi-account):** store each account's secret once —
  543. ```bash
  544. email-mcp account set-secret personal # store a NEW secret (prompts; nothing echoed or in argv)
  545. email-mcp account migrate-secret personal # move an EXISTING plaintext password into the keychain
  546. ```
  547. `set-secret` prompts for the value and stores it; `migrate-secret` reads the
  548. account's current plaintext password from `config.toml`, stores it in the
  549. keychain, verifies it, then rewrites the line to `password = "keychain:personal"`.
  550. Either way you end up with `password = "keychain:personal"`. Each account is a separate Keychain
  551. item under the shared `email-mcp` service, so multiple accounts coexist.
  552. Secrets are read back at startup over the `security` CLI; only the service and
  553. account names are ever passed as arguments — the secret travels on stdout only.
  554. At rest the secret lives in your **login keychain**, encrypted and unlocked by
  555. your macOS login (Touch ID at the login level). A running `email-mcp` daemon
  556. reads it once at startup; it does **not** prompt for Touch ID on every IMAP
  557. reconnect — per-access biometric prompts are deliberately not used for an
  558. unattended background service. (True per-access Touch ID would require the
  559. data-protection keychain and a native helper.)
  560. #### OAuth2 _(experimental)_
  561. > **Note:** OAuth2 support is experimental. Token refresh and provider-specific flows may require additional testing in your environment.
  562. ```toml
  563. [[accounts]]
  564. name = "work"
  565. email = "you@company.com"
  566. full_name = "Your Name"
  567. [accounts.oauth2]
  568. provider = "google" # or "microsoft"
  569. client_id = "your-client-id"
  570. client_secret = "your-client-secret"
  571. refresh_token = "your-refresh-token"
  572. [accounts.imap]
  573. host = "imap.gmail.com"
  574. port = 993
  575. tls = true
  576. [accounts.smtp]
  577. host = "smtp.gmail.com"
  578. port = 465
  579. tls = true
  580. [accounts.smtp.pool]
  581. enabled = true
  582. max_connections = 1
  583. max_messages = 100
  584. ```
  585. #### Environment Variables
  586. For single-account setups (overrides config file):
  587. | Variable | Default | Description |
  588. |----------|---------|-------------|
  589. | `MCP_EMAIL_ADDRESS` | *required* | Email address |
  590. | `MCP_EMAIL_PASSWORD` | *required* | Password or app password |
  591. | `MCP_EMAIL_IMAP_HOST` | *required* | IMAP server hostname |
  592. | `MCP_EMAIL_SMTP_HOST` | *required* | SMTP server hostname |
  593. | `MCP_EMAIL_ACCOUNT_NAME` | `default` | Account name |
  594. | `MCP_EMAIL_FULL_NAME` | — | Display name |
  595. | `MCP_EMAIL_USERNAME` | *email* | Login username |
  596. | `MCP_EMAIL_IMAP_PORT` | `993` | IMAP port |
  597. | `MCP_EMAIL_IMAP_TLS` | `true` | IMAP TLS |
  598. | `MCP_EMAIL_SMTP_PORT` | `465` | SMTP port |
  599. | `MCP_EMAIL_SMTP_TLS` | `true` | SMTP TLS |
  600. | `MCP_EMAIL_SMTP_STARTTLS` | `false` | SMTP STARTTLS |
  601. | `MCP_EMAIL_SMTP_VERIFY_SSL` | `true` | Verify SSL certificates |
  602. | `MCP_EMAIL_SMTP_POOL_ENABLED` | `true` | Enable SMTP transport pooling |
  603. | `MCP_EMAIL_SMTP_POOL_MAX_CONNECTIONS` | `1` | Max pooled SMTP connections |
  604. | `MCP_EMAIL_SMTP_POOL_MAX_MESSAGES` | `100` | Max messages per pooled connection |
  605. | `MCP_EMAIL_RATE_LIMIT` | `10` | Max sends per minute |
  606. | `MCP_EMAIL_SEND_SAVE_TO_SENT` | `false` | `true` appends a copy of each sent message to the IMAP Sent folder |
  607. | `MCP_EMAIL_READ_ONLY` | `false` | `true` unregisters the mailbox-write tools (send, move, delete, labels, bulk). Calendar/Reminders writes, clipboard copy and config-writing tools stay available — it is a mailbox guard, not a global one. |
  608. | `MCP_EMAIL_SCHEDULER_SENT_RETENTION_DAYS` | `90` | Days of sent-email history to keep; `0` keeps everything |
  609. | `MCP_EMAIL_ATTACHMENT_DOWNLOAD_DIR` | — | Directory `download_attachment`'s `saveToDownloadDir` writes into; unset disables the option |
  610. | `MCP_EMAIL_ATTACHMENT_DOWNLOAD_ALLOWED_EXTENSIONS` | *(built-in list — see below)* | Comma-separated extension allowlist for saved attachments |
  611. | `MCP_EMAIL_ATTACHMENT_DOWNLOAD_MAX_BYTES` | `26214400` (25 MB) | Max attachment size `saveToDownloadDir` will write |
  612. ### Local Cache
  613. Reads are served from a local SQLite mirror of your mail (plus a
  614. content-addressed store for attachments) under
  615. `${XDG_CACHE_HOME:-~/.cache}/email-mcp/`. It makes listing, searching, and
  616. re-reading mail fast, and it keeps mail readable when the mail server is
  617. unreachable. It is on by default.
  618. **The cache is never authoritative.** Every row can be re-fetched from IMAP, so
  619. deleting it costs a resync and never loses mail — you can remove the directory
  620. at any time, as the XDG cache convention allows.
  621. #### Seeing and reclaiming what it holds
  622. ```bash
  623. email-mcp cache status # size vs budget, per-mailbox coverage, last sync
  624. email-mcp cache status --json # same, for scripts
  625. email-mcp cache clear # free the space (asks first; mail is re-fetched)
  626. email-mcp cache clear --account work --yes
  627. email-mcp cache verify # integrity check + reclaim orphaned files
  628. ```
  629. `cache status` reports the index size and attachment bytes separately, how many
  630. messages have full text cached, and how long ago each mailbox was reconciled.
  631. `check_health` exposes the same numbers to an AI client, plus the read hit ratio.
  632. #### How freshness is decided
  633. Correctness comes first: a stale answer to "any new mail?" is a wrong answer.
  634. Before serving a mailbox from the cache, the server either trusts a reconcile
  635. from the last 10 seconds, or spends one `STATUS` round trip comparing the
  636. server's `UIDVALIDITY`/`UIDNEXT`/`HIGHESTMODSEQ`/`MESSAGES` against what the
  637. mirror recorded — the IMAP equivalent of a conditional request. If anything
  638. moved, it resynchronises before answering (bounded; past the bound you get the
  639. cached answer marked `stale`). If the server is unreachable you get the cached
  640. answer marked `offline`.
  641. Message bodies and attachments are immutable for a given `UIDVALIDITY`/UID, so
  642. once stored they are served with no revalidation at all. Writes made through
  643. this server (flagging, moving, deleting) resynchronise the affected mailboxes
  644. immediately, which matters on servers without `CONDSTORE` where a flag change
  645. is otherwise invisible.
  646. #### Settings
  647. | Setting | Default | What it does |
  648. |---|---|---|
  649. | `enabled` | `true` | `false` reads live from IMAP every time |
  650. | `mailboxes` | `["INBOX"]` | Synced in the background. Others mirror lazily once read |
  651. | `window_days` | `0` (all) | How far back the first sync of a mailbox reaches |
  652. | `body_messages` | `500` | Bodies kept per mailbox. `0` keeps the cache metadata-only |
  653. | `max_size_mb` | `500` | Budget for index + attachments combined |
  654. | `sync_interval` | `300` | Seconds between background reconciles |
  655. Past the budget, eviction runs cheapest-to-rebuild-first: attachment files
  656. (least recently read first), then message bodies, then envelopes older than
  657. `window_days`. Envelopes are kept as long as possible, because they are what
  658. listings and search need.
  659. **Coverage, not just freshness.** The cache only answers a listing when it
  660. holds every message the server reports for that mailbox. Set `window_days` to
  661. something other than `0` and the mirror becomes a slice — it then cannot report
  662. a truthful `total` or know whether more pages exist, so reads fall back to the
  663. live path until it catches up. That is also why envelope eviction clears the
  664. mailbox's sync watermarks: the next sync rebuilds coverage instead of leaving a
  665. permanent, invisible hole.
  666. #### Data at rest
  667. Cached mail — including message bodies and attachment content — is stored
  668. **unencrypted**, in a directory and files readable only by your user
  669. (`0700`/`0600`). This matches what desktop mail clients do; the recommended
  670. protection is full-disk encryption (FileVault, LUKS). If you would rather not
  671. have bodies and attachments on disk at all, set `body_messages = 0`, which
  672. keeps the cache metadata-only.
  673. Gmail note: do not add `[Gmail]/All Mail` to `mailboxes`. Gmail presents the
  674. same message in every label folder, so mirroring All Mail alongside INBOX
  675. stores the same mail twice.
  676. ### Email Scheduling
  677. The scheduler enables future email delivery with a layered architecture:
  678. 1. **MCP auto-check** — Processes the queue on server startup and every 60 seconds while the MCP server is running
  679. 2. **CLI** — `email-mcp scheduler check` for manual or cron-based processing
  680. 3. **OS-level daemon** — `email-mcp scheduler install` sets up launchd (macOS) or crontab (Linux) to run every minute, independently of the MCP server
  681. > **Important — the daemon must be installed for reliable delivery.**
  682. > Without it, scheduled emails only fire while an AI client is actively connected.
  683. > Your machine also needs to be running at the scheduled time; if it's asleep or
  684. > off, the daemon will process overdue emails on next wake/startup. Failed sends
  685. > are retried up to **3 times** before being marked `failed`.
  686. #### Setting up the daemon
  687. ```bash
  688. # Install (macOS launchd / Linux crontab — runs every minute)
  689. email-mcp scheduler install
  690. # Verify it's running
  691. email-mcp scheduler status
  692. # View pending / sent / failed scheduled emails
  693. email-mcp scheduler list
  694. # Trigger a manual check immediately
  695. email-mcp scheduler check
  696. # Remove the daemon
  697. email-mcp scheduler uninstall
  698. ```
  699. Scheduled emails are stored as JSON files in `~/.local/state/email-mcp/scheduled/` with status-based locking. Each entry tracks attempts (max 3) and the last error, so you can inspect failures with `scheduler list`.
  700. ### Real-time Watcher & AI Hooks
  701. The IMAP IDLE watcher monitors configured mailboxes in real-time using persistent IDLE connections (separate from tool connections). When new emails arrive:
  702. 1. **Static rules** — Pattern-match on from/to/subject → apply labels, flag, or mark read instantly (no AI)
  703. 2. **AI triage** — Remaining emails are analyzed via MCP sampling with a customizable preset prompt
  704. 3. **Notify mode** — Falls back to logging if AI triage is disabled
  705. Configure in `config.toml`:
  706. ```toml
  707. [settings.watcher]
  708. enabled = true
  709. folders = ["INBOX"]
  710. idle_timeout = 1740 # 29 minutes (IMAP spec max is 30)
  711. [settings.hooks]
  712. on_new_email = "triage" # "triage" | "notify" | "none"
  713. preset = "inbox-zero" # "inbox-zero" | "gtd" | "priority-focus" | "notification-only" | "custom"
  714. auto_label = true # apply AI-suggested labels
  715. auto_flag = true # flag urgent emails
  716. batch_delay = 5 # seconds to batch before triage
  717. # User context — appended to preset's AI prompt
  718. custom_instructions = """
  719. I'm a software engineer. Emails from @mycompany.com are always high priority.
  720. Newsletters I read: TL;DR, Hacker Newsletter.
  721. """
  722. # Static rules — run BEFORE AI, skip AI if matched
  723. [[settings.hooks.rules]]
  724. name = "GitHub Notifications"
  725. match = { from = "*@github.com" }
  726. actions = { labels = ["Dev"], mark_read = true }
  727. [[settings.hooks.rules]]
  728. name = "Newsletter Archive"
  729. match = { from = "*@substack.com|*@buttondown.email" }
  730. actions = { labels = ["Newsletter"] }
  731. [[settings.hooks.rules]]
  732. name = "VIP Contacts"
  733. match = { from = "ceo@company.com|cto@company.com" }
  734. actions = { flag = true, labels = ["VIP"] }
  735. ```
  736. #### Presets
  737. | Preset | Focus | Suggested Labels |
  738. |--------|-------|------------------|
  739. | `inbox-zero` | Aggressive categorization + archiving | Newsletter, Notification, Updates, Finance, Social, Promo |
  740. | `gtd` | Getting Things Done contexts | @Action, @Waiting, @Reference, @Someday, @Delegated |
  741. | `priority-focus` | Simple priority classification (default) | _(none — just priority + flag)_ |
  742. | `notification-only` | No AI triage, just log | _(none)_ |
  743. | `custom` | User defines full system prompt | User-defined |
  744. #### Static Rules
  745. Static rules use glob-style patterns (`*@github.com`) with `|` as OR separator (`*@github.com|*@gitlab.com`). All conditions within a match are AND'd. First matching rule wins.
  746. Available actions: `labels` (string array), `flag` (boolean), `mark_read` (boolean), `alert` (boolean — forces desktop notification).
  747. #### Alerts
  748. Urgency-based multi-channel notification routing — grab attention for important emails even when you're not looking at the chat. All channels are **opt-in** and disabled by default.
  749. | Priority | Desktop | Sound | MCP Log Level | Webhook |
  750. |----------|---------|-------|---------------|---------|
  751. | `urgent` | ✅ Banner | 🔊 Alert | `alert` | ✅ |
  752. | `high` | ✅ Banner | 🔇 Silent | `warning` | ✅ |
  753. | `normal` | ❌ | ❌ | `info` | ❌ |
  754. | `low` | ❌ | ❌ | `debug` | ❌ |
  755. ```toml
  756. [settings.hooks.alerts]
  757. desktop = true # OS-level notifications (macOS/Linux/Windows)
  758. sound = true # play sound for urgent emails
  759. urgency_threshold = "high" # minimum priority to trigger desktop alert
  760. webhook_url = "https://ntfy.sh/my-email-alerts" # optional: Slack, Discord, ntfy.sh, etc.
  761. webhook_events = ["urgent", "high"]
  762. ```
  763. **Supported platforms:** macOS (Notification Center via `osascript`), Linux (`notify-send`), Windows (PowerShell toast). Zero npm dependencies — uses native OS commands.
  764. **Notification setup by platform:**
  765. <details>
  766. <summary>macOS</summary>
  767. Desktop notifications use `osascript` (built-in). The terminal app running the MCP server needs notification permission:
  768. 1. Open **System Settings → Notifications & Focus**
  769. 2. Find your terminal app (Terminal, iTerm2, VS Code, Cursor, etc.)
  770. 3. Enable **Allow Notifications** and choose **Banners** or **Alerts**
  771. 4. Ensure **Focus** / Do Not Disturb is not blocking notifications
  772. Use `check_notification_setup` to diagnose and `test_notification` to verify.
  773. </details>
  774. <details>
  775. <summary>Linux</summary>
  776. Requires `notify-send` from `libnotify`. For sound alerts, `paplay` is also needed:
  777. ```bash
  778. # Ubuntu / Debian
  779. sudo apt install libnotify-bin pulseaudio-utils
  780. # Fedora
  781. sudo dnf install libnotify pulseaudio-utils
  782. # Arch
  783. sudo pacman -S libnotify
  784. ```
  785. Desktop notifications require a running display server (X11/Wayland) — they will not work in headless/SSH sessions.
  786. </details>
  787. <details>
  788. <summary>Windows</summary>
  789. Uses PowerShell toast notifications (built-in):
  790. 1. Open **Settings → System → Notifications**
  791. 2. Ensure **Notifications** is turned on
  792. 3. Set **Focus Assist** to allow notifications
  793. 4. If using Windows Terminal, ensure its notifications are enabled
  794. </details>
  795. **AI-configurable:** The AI can check, test, and configure notifications at runtime:
  796. - `check_notification_setup` — diagnose platform support and show setup instructions
  797. - `test_notification` — send a test notification to verify everything works
  798. - `configure_alerts` — enable/disable desktop, sound, threshold, webhook (with optional persist to config file)
  799. **Webhook payload:**
  800. ```json
  801. {
  802. "event": "email.urgent",
  803. "account": "work",
  804. "sender": { "name": "John CEO", "address": "ceo@company.com" },
  805. "subject": "Q4 Review Due Today",
  806. "priority": "urgent",
  807. "labels": ["VIP"],
  808. "rule": "VIP Contacts",
  809. "timestamp": "2026-02-18T11:30:00Z"
  810. }
  811. ```
  812. Static rules can force desktop notifications with `alert = true`, regardless of urgency threshold:
  813. ```toml
  814. [[settings.hooks.rules]]
  815. name = "VIP Contacts"
  816. match = { from = "ceo@company.com" }
  817. actions = { flag = true, alert = true, labels = ["VIP"] }
  818. ```
  819. Features:
  820. - **Auto-reconnect** — Exponential backoff (1s → 60s) on connection failures
  821. - **Batching** — Groups arrivals within a configurable delay to reduce AI calls
  822. - **Rate limiting** — Max 10 sampling calls per minute
  823. - **Graceful degradation** — Falls back to notify mode if client doesn't support sampling
  824. - **Resource subscriptions** — Pushes `notifications/resources/updated` for unread counts
  825. #### Verification codes (instant OTP catch)
  826. When a mail carrying a verification code (OTP/2FA) or sign-in magic link arrives, email-mcp
  827. copies it to your clipboard within ~1–2 seconds and shows a notification —
  828. **“✅ Code 482913 from GitHub — Copied to clipboard, clears in 60s”**. Press ⌘V / Ctrl+V, done.
  829. Detection is scoring-based (English + German), not a bare digit regex: keyword proximity
  830. (`verification`, `Bestätigungscode`, `expires`, …) minus negative context (order numbers,
  831. invoices, tracking, Zoom passcodes, phone numbers, prices, dates). A miss beats a wrong
  832. code on your clipboard.
  833. ```toml
  834. [settings.watcher]
  835. enabled = true # REQUIRED for ambient catching (IMAP IDLE push)
  836. [settings.verification]
  837. enabled = true # on by default
  838. auto_copy = true # copy caught codes/links to the clipboard
  839. confirm_copy = false # ask (native dialog) before touching the clipboard
  840. notify = true # desktop notification on catch
  841. copy_links = true # also catch magic links (only when no code found)
  842. link_action = "open" # "open" = offer to open links in the browser, "copy" = clipboard
  843. clear_after_seconds = 60 # conditional auto-clear (0 = never)
  844. max_age_minutes = 10 # ignore stale messages (IDLE replays)
  845. accounts = [] # limit to specific accounts (empty = all)
  846. sender_allowlist = [] # e.g. ["*@github.com", "*@google.com"]
  847. sender_denylist = []
  848. ```
  849. **Ask-first mode:** with `confirm_copy = true`, a native macOS dialog ("Code 482913 from
  850. GitHub — Copy to clipboard?") appears before anything touches your clipboard. **Sign-in
  851. links** get a three-button dialog by default (`link_action = "open"`): **Open** launches
  852. the link in your default browser, **Copy** puts it on the clipboard, **Cancel** does
  853. nothing — opening is *always* confirmed, since auto-launching a browser from mail content
  854. would be a phishing hazard. Set `link_action = "copy"` for the silent clipboard behavior.
  855. Dialogs are macOS-only (same mechanism as the calendar confirmation); elsewhere these
  856. modes degrade to notification-only.
  857. **Clipboard hygiene (macOS):** codes are written via a JXA `osascript` with the
  858. `org.nspasteboard.ConcealedType` marker — the same convention 1Password/Bitwarden use — so
  859. well-behaved clipboard managers (Maccy, Paste, …) never record them. The auto-clear is
  860. conditional: the clipboard is only cleared if it still holds the caught value, so anything
  861. you copied in the meantime is never stomped. Linux uses `wl-copy`/`xclip`, Windows uses
  862. PowerShell `Set-Clipboard` (no concealment convention exists there). Zero npm dependencies.
  863. **For agents:** `get_verification_code` fetches the newest code on demand — during an
  864. automated signup, call it with `wait_seconds = 30` and it returns the code seconds after
  865. the mail lands (event-driven with the watcher, 5 s polling without). If nothing arrives in
  866. time, it returns `found: false` with a hint — just call it again.
  867. **Security notes:** the clipboard is shared OS state — any app can read it while the code
  868. is there (that window is bounded by `clear_after_seconds`). The code itself is never
  869. written to server logs or the audit log; it does appear in `get_verification_code` results,
  870. which is the point of that tool. Kill switches: `enabled = false` (feature off) or
  871. `auto_copy = false` (notification only). Environment overrides: `MCP_EMAIL_VERIFICATION_*`
  872. (`_ENABLED`, `_AUTO_COPY`, `_CONFIRM_COPY`, `_NOTIFY`, `_COPY_LINKS`, `_LINK_ACTION`,
  873. `_CLEAR_AFTER_SECONDS`, `_MAX_AGE_MINUTES`, `_ACCOUNTS`, `_SENDER_ALLOWLIST`,
  874. `_SENDER_DENYLIST`).
  875. Use `check_clipboard_setup` to diagnose the pipeline (add `test_write = true` for a
  876. harmless copy → read-back → clear round-trip).
  877. ## API
  878. ### Tools (52)
  879. > **Structured output:** `list_emails`, `search_emails`, `get_email_status`, `list_mailboxes`, and `get_verification_code` also return machine-readable results (`outputSchema` + `structuredContent`) alongside the human-readable text, for clients that consume typed tool output.
  880. #### Email bodies: HTML and other formats
  881. Nearly all real mail is HTML — in one sampled mailbox, 165 of 169 messages were
  882. single-part `text/html` — so the read tools convert it rather than handing back
  883. markup.
  884. `get_email`, `get_emails`, and `get_thread` take a `format`:
  885. | `format` | Body you get |
  886. |---|---|
  887. | `text` *(default)* | HTML converted to readable text: links become `[label](url)`, tables keep cell boundaries, lists are numbered or bulleted, quotes are `> `-prefixed, images become `[image: alt]` |
  888. | `stripped` | As `text`, minus quoted reply chains and signatures |
  889. | `full` | The raw body part, HTML included |
  890. Bodies are capped by default — 10 000 characters for `get_email`, 5 000 per
  891. message for `get_emails` and `get_thread` — and a hint reports how much was
  892. left out. Pass `maxLength: 0` for no cap. Each side of the body (text, HTML) is
  893. read up to 512 KB, shared across its parts.
  894. Other formats behave as follows:
  895. - **`multipart/alternative`** — both halves are fetched, so `bodyText` and
  896. `bodyHtml` are both available. A plain part too small to hold the same
  897. content as its HTML sibling is treated as a "view this in an HTML reader"
  898. placeholder and skipped.
  899. - **`multipart/mixed` with several text parts** — concatenated in order, so a
  900. note split either side of an inline image (Apple Mail) or a per-message
  901. digest section is not truncated to its first part.
  902. - **`text/plain; format=flowed`** (RFC 3676) — soft line wraps are undone, so
  903. paragraphs read as paragraphs rather than hard-wrapped at 72 columns;
  904. `DelSp` and space-stuffing are honoured.
  905. - **Inline (`cid:`) images** — listed as attachments with `partId`,
  906. `contentId`, and `inline`, and downloadable via `download_attachment`'s
  907. `partId`. To embed one when sending, pass
  908. `{path, cid, contentType}` in `attachments` and reference it as
  909. `<img src="cid:…">`.
  910. - **Bounces** (`multipart/report`) — the machine-readable
  911. `message/delivery-status` part is surfaced separately from the body.
  912. - **Calendar invites** — handled by `extract_calendar` / `add_to_calendar`,
  913. honouring the part's declared charset.
  914. - **Encrypted mail** (S/MIME, PGP/MIME) — not decrypted; the body says so
  915. plainly instead of appearing empty.
  916. - **Attached messages** (`message/rfc822`) — never mistaken for the body, but
  917. used as the body when the message carries no other text (forward-as-attachment,
  918. digests).
  919. **Attachment download directory.** `download_attachment` normally returns the
  920. file base64-encoded (≤5 MB). Set `[settings.attachment_download] dir` (or
  921. `MCP_EMAIL_ATTACHMENT_DOWNLOAD_DIR`) to a directory and pass
  922. `saveToDownloadDir: true` to instead write the file there and get back its
  923. path — useful for larger files, or when the caller just wants the attachment
  924. on disk rather than inlined into the conversation. The option is unavailable
  925. (the call fails) until `dir` is set — there is no default location. Only
  926. `allowed_extensions` are written (default: common document/image types; see
  927. the config example above); `max_bytes` caps the size, independent of the
  928. 5 MB base64 cap. Pass `saveAs` to choose the filename written there (a plain
  929. basename — no path separators); otherwise the attachment's own filename is
  930. sanitized and used. Running in Docker, point `dir` at a mounted volume shared
  931. with whatever reads the files back, e.g. in `docker-compose.yml`:
  932. ```yaml
  933. services:
  934. email-mcp:
  935. environment:
  936. MCP_EMAIL_ATTACHMENT_DOWNLOAD_DIR: /data/attachments
  937. volumes:
  938. - attachments:/data/attachments
  939. other-service:
  940. volumes:
  941. - attachments:/data/attachments:ro
  942. volumes:
  943. attachments:
  944. ```
  945. **Sent-folder copies.** SMTP delivers mail; it does not file it. `[settings.send]
  946. save_to_sent` defaults to **false**; turn it on for an IMAP host that does not
  947. capture sends itself. Gmail does capture sends server-side, so an account
  948. whose IMAP server advertises the `X-GM-EXT-1` capability is skipped
  949. automatically even with the setting on — filing a copy there would give you
  950. two of everything. Set the account's own `save_to_sent` to force the decision
  951. either way (`true` files anyway, `false` never files, regardless of the
  952. global setting or the Gmail guess).
  953. The copy carries the same `Message-ID` the server accepted, is flagged
  954. `\Seen`, and lands in the folder the server marks `\Sent` (or a folder named
  955. `Sent`, created if absent). On a mailbox that carries several sent-shaped
  956. folders — a leftover `Sent` beside the one actually in use — that guess can
  957. land on an empty one; set the account's `sent_mailbox` to the full path
  958. (as `list_mailboxes` reports it) to settle it. The copy omits `Bcc`, which the
  959. MIME composer strips unconditionally.
  960. A failure to file never fails the send — the mail has already left, and
  961. saying otherwise would invite a duplicate send — but `send_draft` keeps the
  962. draft in that case rather than deleting the only remaining copy of the
  963. message. `send_email`, `reply_email`, `forward_email` and `send_draft` all
  964. report the outcome in their result's `sentCopy` field: `{kind: "filed", path}`,
  965. `{kind: "skipped"}` (setting off, or Gmail's own capture), or
  966. `{kind: "failed", error}`.
  967. Outbound HTML (`html: true`) is sent as `multipart/alternative` with a
  968. generated plain-text alternative. Forwards quote the original as converted
  969. text; pass `html: true` to `forward_email` to also carry the original HTML.
  970. #### Read (14)
  971. | Tool | Description |
  972. |------|-------------|
  973. | `list_accounts` | List all configured email accounts |
  974. | `list_mailboxes` | List folders with unread counts and special-use flags |
  975. | `list_emails` | Paginated email listing with date, sender, subject, and flag filters; marks bulk mail; optional body preview |
  976. | `get_email` | Read full email content with attachment metadata and bulk-mail classification (HTML converted to readable text by default) |
  977. | `get_emails` | Fetch full content of multiple emails in a single call (max 20); same bulk markers |
  978. | `get_email_status` | Get read/flag/label state of an email without fetching the body |
  979. | `search_emails` | Search by keyword across subject, sender, and body; same bulk markers and optional preview as `list_emails` |
  980. | `download_attachment` | Download an email attachment by filename or MIME part id, base64-encoded or (if configured) saved to the server's attachment download directory |
  981. | `find_email_folder` | Discover the real folder(s) an email resides in (resolves virtual folders) |
  982. | `extract_contacts` | Extract unique contacts from recent email headers |
  983. | `get_thread` | Reconstruct a conversation thread via References/In-Reply-To; same bulk markers |
  984. | `list_templates` | List available email templates |
  985. | `get_email_stats` | Email analytics — volume, top senders, daily trends |
  986. | `check_health` | Connection health, latency, quota, and IMAP capabilities |
  987. #### Bulk-mail classification
  988. `list_emails`, `search_emails`, `get_email`, `get_emails` and `get_thread` mark
  989. list and machine-generated mail, so an inbox can be triaged without reading
  990. bodies:
  991. | Marker | Meaning | Derived from |
  992. |--------|---------|--------------|
  993. | 📰 `newsletter` | Mailing list or subscription | `List-Unsubscribe` (RFC 2369), `List-Id` (RFC 2919), `Precedence: list` |
  994. | 🤖 `automated` | Machine-generated notification | `Auto-Submitted` (RFC 3834), `Precedence: bulk`/`junk` |
  995. | _(none)_ | Ordinary person-to-person mail | no bulk headers present |
  996. A newsletter also reports its unsubscribe URI when the sender offers one, and
  997. flags `1-click` when RFC 8058 one-click unsubscribe is supported. The headers
  998. are requested as part of the listing fetch, so classifying a whole page costs no
  999. extra round trip.
  1000. Classification is header-derived and therefore deterministic — no model call and
  1001. no heuristics on subject text. A sender that omits the headers is reported as
  1002. personal mail rather than guessed at. These are sender-asserted headers, not
  1003. verified ones — treat the marker as a signal to weigh, not a fact to defer to.
  1004. #### Body previews
  1005. `list_emails` and `search_emails` accept `preview: true` to include roughly 200
  1006. characters of each message body. It is **off by default**: it fetches 1500 extra
  1007. bytes per message and lengthens the tool output, which is a cost the caller
  1008. should choose rather than inherit.
  1009. The preview is decoded from one body part rather than from message source —
  1010. IMAP section 1, or 1.1 when section 1 is itself a multipart. Because the fetch
  1011. stops at a byte count rather than at an encoding boundary, decoding tolerates
  1012. input cut mid-stream: base64 is truncated to a whole group, a half-written
  1013. quoted-printable escape is dropped, and the replacement character left by a
  1014. severed UTF-8 sequence is trimmed. Charsets beyond UTF-8 are handled — real mail
  1015. still ships `iso-8859-1`.
  1016. Markup is stripped whether or not the sender declared it, since bulk senders
  1017. routinely put HTML and stylesheets in a part labelled `text/plain`. Entities and
  1018. zero-width preheader padding are decoded, and a preview that reduces to markup
  1019. residue is omitted: **no preview beats a misleading one**.
  1020. #### Write (9)
  1021. | Tool | Description |
  1022. |------|-------------|
  1023. | `send_email` | Send a new email (plain text or HTML, CC/BCC) |
  1024. | `reply_email` | Reply with proper threading (In-Reply-To, References) |
  1025. | `forward_email` | Forward with original content quoted |
  1026. | `save_draft` | Save an email draft to the Drafts folder |
  1027. | `send_draft` | Send an existing draft and remove from Drafts |
  1028. | `apply_template` | Apply a template with variable substitution |
  1029. | `schedule_email` | Schedule an email for future delivery |
  1030. | `list_scheduled` | List scheduled emails by status |
  1031. | `cancel_scheduled` | Cancel a pending scheduled email |
  1032. #### Manage (7)
  1033. | Tool | Description |
  1034. |------|-------------|
  1035. | `move_email` | Move email between folders |
  1036. | `delete_email` | Move to Trash or permanently delete |
  1037. | `mark_email` | Mark as read/unread, flag/unflag |
  1038. | `bulk_action` | Batch operation on up to 100 emails |
  1039. | `create_mailbox` | Create a new mailbox folder |
  1040. | `rename_mailbox` | Rename an existing mailbox folder |
  1041. | `delete_mailbox` | Permanently delete a mailbox and contents |
  1042. #### Labels (5)
  1043. | Tool | Description |
  1044. |------|-------------|
  1045. | `list_labels` | Discover available labels (auto-detects provider strategy) |
  1046. | `add_label` | Add a label to an email (ProtonMail folders, Gmail X-GM-LABELS, or IMAP keywords) |
  1047. | `remove_label` | Remove a label from an email |
  1048. | `create_label` | Create a new label |
  1049. | `delete_label` | Delete a label |
  1050. #### Watcher & Alerts (6)
  1051. | Tool | Description |
  1052. |------|-------------|
  1053. | `get_watcher_status` | Show IMAP IDLE connections, folders being monitored, and last-seen UIDs |
  1054. | `list_presets` | List available AI triage presets with descriptions and suggested labels |
  1055. | `get_hooks_config` | Show current hooks configuration — preset, rules, and custom instructions |
  1056. | `configure_alerts` | Update alert/notification settings at runtime |
  1057. | `check_notification_setup` | Diagnose desktop notification support and provide setup instructions |
  1058. | `test_notification` | Send a test notification to verify OS permissions are configured |
  1059. #### Verification (3)
  1060. | Tool | Description |
  1061. |------|-------------|
  1062. | `get_verification_code` | Find (or wait up to 45 s for) the newest OTP/2FA code or sign-in magic link, with optional clipboard copy |
  1063. | `check_clipboard_setup` | Diagnose clipboard integration (platform tools, concealed-write support) with optional round-trip test |
  1064. | `configure_verification` | Update verification-catching settings at runtime (incl. starting/stopping the catcher), optional persist to config file |
  1065. #### Calendar & Reminders (8)
  1066. | Tool | Description |
  1067. |------|-------------|
  1068. | `extract_calendar` | Extract ICS/iCalendar events from an email |
  1069. | `analyze_email_for_scheduling` | Analyze an email to detect events and reminder-worthy content |
  1070. | `add_to_calendar` | Add an email event to the local calendar (macOS Calendar.app; on Linux hands the .ics to xdg-open); event notes link back to the source email |
  1071. | `create_reminder` | Create a reminder in macOS Reminders.app from an email; reminder notes link back to the source email |
  1072. | `list_calendars` | List all available local calendars (macOS Calendar.app; elsewhere a single placeholder) |
  1073. | `check_calendar_permissions` | Check whether the local calendar is accessible (macOS probes for real; elsewhere always reports accessible) |
  1074. | `list_events` | List events from the local calendar in a date range (macOS only; returns empty elsewhere) |
  1075. | `list_reminders` | List reminders from Reminders.app (macOS only) |
  1076. ### Prompts (7)
  1077. | Prompt | Description |
  1078. |--------|-------------|
  1079. | `triage_inbox` | Categorize and prioritize unread emails with suggested actions |
  1080. | `summarize_thread` | Summarize an email conversation thread |
  1081. | `compose_reply` | Draft a context-aware reply to an email |
  1082. | `draft_from_context` | Compose a new email from provided context and instructions |
  1083. | `extract_action_items` | Extract actionable tasks from email threads |
  1084. | `summarize_meetings` | Summarize upcoming calendar events from emails |
  1085. | `cleanup_inbox` | Suggest emails to archive, delete, or unsubscribe from |
  1086. ### Resources (6)
  1087. | Resource | URI | Description |
  1088. |----------|-----|-------------|
  1089. | Accounts | `email://accounts` | List of configured accounts |
  1090. | Mailboxes | `email://{account}/mailboxes` | Folder tree for an account |
  1091. | Unread | `email://{account}/unread` | Unread email summary |
  1092. | Templates | `email://templates/{name}` | One email template by name; the resource lists the available names |
  1093. | Stats | `email://{account}/stats` | Email statistics snapshot |
  1094. | Scheduled | `email://scheduled` | Pending scheduled emails |
  1095. ### Provider Auto-Detection
  1096. | Provider | Domains |
  1097. |----------|---------|
  1098. | Gmail | gmail.com, googlemail.com |
  1099. | Outlook / Hotmail | outlook.com, hotmail.com, live.com, outlook.de, outlook.co.uk |
  1100. | Yahoo Mail | yahoo.com, yahoo.co.uk, yahoo.de, ymail.com |
  1101. | iCloud | icloud.com, me.com, mac.com |
  1102. | Fastmail | fastmail.com, fastmail.fm |
  1103. | ProtonMail Bridge | proton.me, protonmail.com, protonmail.ch, pm.me |
  1104. | Zoho Mail | zoho.com, zohomail.com |
  1105. | GMX | gmx.com, gmx.de, gmx.net, gmx.at, gmx.ch |
  1106. ### Architecture
  1107. ```
  1108. src/
  1109. ├── main.ts — Entry point and subcommand routing
  1110. ├── server.ts — MCP server factory
  1111. ├── logging.ts — MCP protocol logging bridge
  1112. ├── cli/ — Interactive CLI commands
  1113. │ ├── account-commands.ts — Account CRUD (list, add, edit, delete)
  1114. │ ├── setup.ts — Legacy setup alias → account add
  1115. │ ├── test.ts — Connection tester
  1116. │ ├── config-commands.ts — Config management (show, edit, path, init)
  1117. │ ├── install-commands.ts — MCP client registration (install, status, remove)
  1118. │ ├── cache-commands.ts — Local-mirror CLI (status, clear, verify)
  1119. │ └── scheduler.ts — Scheduler CLI
  1120. ├── config/ — Configuration layer
  1121. │ ├── xdg.ts — XDG Base Directory paths
  1122. │ ├── schema.ts — Zod validation schemas
  1123. │ ├── providers.ts — Provider auto-detection + OAuth2 endpoints (experimental)
  1124. │ └── loader.ts — Config loader (TOML + env vars)
  1125. ├── cache/ — Local SQLite mirror
  1126. │ ├── schema.ts — Mirror schema + migrations
  1127. │ ├── store.ts — Read/write API over the mirror
  1128. │ └── sync-engine.ts — Background reconcile + body backfill
  1129. ├── connections/
  1130. │ └── manager.ts — Lazy persistent IMAP/SMTP with OAuth2 (experimental)
  1131. ├── services/ — Business logic
  1132. │ ├── imap.service.ts — IMAP operations
  1133. │ ├── label-strategy.ts — Provider-aware label strategy (ProtonMail/Gmail/IMAP keywords)
  1134. │ ├── smtp.service.ts — SMTP operations
  1135. │ ├── template.service.ts — Email template engine
  1136. │ ├── oauth.service.ts — OAuth2 token management (experimental)
  1137. │ ├── calendar.service.ts — ICS/iCalendar parsing
  1138. │ ├── scheduler.service.ts — Email scheduling queue
  1139. │ ├── watcher.service.ts — IMAP IDLE real-time watcher with auto-reconnect
  1140. │ ├── hooks.service.ts — AI triage via MCP sampling + static rules + auto-labeling/flagging
  1141. │ ├── notifier.service.ts — Multi-channel notification dispatcher (desktop/sound/webhook)
  1142. │ ├── clipboard.service.ts — Concealed clipboard writes for caught codes (zero deps)
  1143. │ ├── dialog.service.ts — Native confirm dialogs + browser hand-off (macOS)
  1144. │ ├── verification-catcher.service.ts — Instant OTP/magic-link catch on new mail
  1145. │ ├── presets.ts — Built-in hook presets (inbox-zero, gtd, priority-focus, etc.)
  1146. │ └── event-bus.ts — Typed EventEmitter for internal email events
  1147. ├── tools/ — MCP tool definitions (52)
  1148. ├── prompts/ — MCP prompt definitions (7)
  1149. ├── resources/ — MCP resource definitions (6)
  1150. ├── safety/ — Audit trail and rate limiter
  1151. └── types/ — Shared TypeScript types
  1152. ```
  1153. ## Roadmap
  1154. Ideas raised but deliberately not built yet, kept here so they aren't lost or
  1155. quietly re-proposed:
  1156. - **AgentMail as an alternative provider.** [AgentMail](https://agentmail.to)
  1157. offers API-key-only, programmatic `@agentmail.to` inboxes — no IMAP/SMTP
  1158. host/port/TLS/credential setup, useful for spinning up throwaway
  1159. agent-owned addresses. It would be additive (a second provider alongside
  1160. real IMAP/SMTP accounts, not a replacement), but is a product/architecture
  1161. decision — a new vendor dependency and tool surface — rather than a bug fix
  1162. or gap-fill, so it's parked here rather than auto-built. Revisit if there's
  1163. real demand for agent-provisioned inboxes rather than access to existing
  1164. mailboxes.
  1165. ## Maintainers
  1166. [@codefuturist](https://github.com/codefuturist)
  1167. ### Release prerequisites
  1168. `release.yml` checks these before publishing anything, so a missing one is a
  1169. fast red run rather than a half-published release:
  1170. | Secret | Needed for |
  1171. |---|---|
  1172. | `GORELEASER_KEY` | GoReleaser Pro license — `.goreleaser.yaml` uses Pro-only keys (`includes`, `variables`), and OSS rejects the whole config |
  1173. | `HOMEBREW_TAP_TOKEN` | PAT with `contents:write` on `codefuturist/homebrew-tap`; the default `GITHUB_TOKEN` cannot push to another repository |
  1174. | `NPM_TOKEN` | npm publish |
  1175. | `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN` | Docker Hub push (GHCR uses `GITHUB_TOKEN`) |
  1176. The Homebrew cask ships the unsigned Bun binary, so its `postflight` clears
  1177. the macOS quarantine bit — macOS only, since Linux has no `xattr(1)` and the
  1178. cask DSL's `system_command` raises on a non-zero exit. `brew uninstall --zap`
  1179. trashes the config, state, cache and data directories plus the two launch
  1180. agents.
  1181. ## Contributing
  1182. PRs accepted. Please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification when editing this README.
  1183. ```bash
  1184. # Development workflow
  1185. pnpm install
  1186. pnpm typecheck # type check
  1187. pnpm check # lint and format
  1188. pnpm build # build
  1189. pnpm start # run
  1190. ```
  1191. ### Testing
  1192. ```bash
  1193. pnpm test # unit tests
  1194. pnpm test:integration # against a throwaway GreenMail server (Docker required)
  1195. pnpm smoke # most MCP tools against a real configured account (see caveats below)
  1196. ```
  1197. The integration suite runs each tool against a throwaway GreenMail server
  1198. (spun up via Testcontainers). Attachment coverage
  1199. (`email-attachments.integration.test.ts`) drives the real MCP tool layer and
  1200. locks in the size-awareness contract: every send reports each file's size and
  1201. the raw≈base64 total, the cap is enforced on the **encoded** total (what the
  1202. wire carries), an over-cap send fails closed (nothing is delivered), and
  1203. forwards carry the original attachments unless `includeAttachments: false`.
  1204. The effective cap is resolved per account: an explicit per-account
  1205. `max_attachment_mb` wins outright; otherwise the stricter of the global
  1206. `[settings.send]` cap and the provider's documented limit applies (Gmail,
  1207. Yahoo, and Proton 25 MB; Outlook.com, iCloud, and GMX 20 MB; Fastmail 50 MB).
  1208. `pnpm smoke` drives all tools over stdio the way a client does, which reaches
  1209. what GreenMail cannot: provider quirks, real-world MIME, and the macOS
  1210. Calendar bridges. It needs a working account, so it is not part of CI. Writes
  1211. stay inside a scratch folder and a draft it creates itself; it does not touch
  1212. Calendar, Reminders, notifications, or `reply_email`, which would send mail to
  1213. a real correspondent. Pass `E2E_ACCOUNT=<name>` to choose an account, otherwise
  1214. it uses the first one configured.
  1215. ## License
  1216. [LGPL-3.0-or-later](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.