apple-mail-mcp
Apple Mail integration for Claude Code and Codex via MCP
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
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/sweetrb/apple-mail-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/sweetrb/apple-mail-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
Markdown
[](/listings/sweetrb--apple-mail-mcp)HTML
<a href="/listings/sweetrb--apple-mail-mcp"><img src="/api/listings/sweetrb--apple-mail-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Using Claude Code (Easiest)
If you're using [Claude Code](https://claude.com/product/claude-code) (in Terminal or VS Code), just ask Claude to install it:
Install the sweetrb/apple-mail-mcp MCP server so you can help me manage my Apple Mail
Claude will handle the installation and configuration automatically.
Or register it deterministically in one command:
claude mcp add apple-mail -s user -- npx -y apple-mail-mcp
Using the Plugin Marketplace
Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:
/plugin marketplace add sweetrb/apple-mail-mcp /plugin install apple-mail
This method also installs a **skill** that teaches Claude when and how to use Apple Mail effectively.
> **Configuring IMAP/SMTP for a plugin install:** a plugin install has no editable `env` block, > so supply settings via the config file at `~/Library/Application Support/apple-mail-mcp/config.json` > — Method B in the [IMAP / SMTP Setup Guide](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md). > Passwords stay in the macOS Keychain; run the `doctor` tool to verify.
Using the Codex Marketplace
See [Apple Mail in Codex](docs/CODEX-SETUP.md) for setup and diagnostics, and the [guided setup and OAuth proposal](docs/CODEX-PLUGIN-AUTH-PROPOSAL.md) for proposed future authorization support.
Install the same public marketplace in Codex:
codex plugin marketplace add sweetrb/apple-mail-mcp codex plugin add apple-mail@apple-mail-mcp
The Codex package includes a portable `codex/plugin.json`, typed stdio server configuration in `codex/mcp.json`, the Apple Mail skill, and the existing assets. It retains `codex/.codex-plugin/plugin.json` and `codex/.mcp.json` for compatible older hosts. Both layouts register the same `apple-mail` MCP identity through `npx -y apple-mail-mcp@<plugin version>`. Release synchronization updates both runtime pins and manifest metadata; tests and CI reject drift. An unreleased candidate can be discovered locally, but its exact npm version must be published before that pinned launcher can be installed from the registry.
For ongoing upstream updates, keep the Git marketplace configured. After a new release is published, refresh its catalog:
codex plugin marketplace upgrade apple-mail-mcp
Install the published plugin version from the refreshed marketplace, then start a new Codex session. The refresh does not replace the runtime pin with `@latest`; the plugin and its pinned npm runtime must refer to the same available release.
The standalone plugin archive bundles the server and requires only Node.js 20+ on the Mac; it does not fetch a runtime from npm. Download it from the release assets, or use the candidate artifact attached to a successful CI run. See [Standalone plugin archive](docs/CODEX-SETUP.md#standalone-plugin-archive) for the distribution format and local build command.
An imported archive or separately uploaded private account plugin is a snapshot, not a subscription to this repository's releases. Updating that copy requires a replacement package. When switching to the maintained marketplace distribution, preserve settings and approvals, verify Mail access and reply behavior, then remove the redundant installation. See [Updates and migration](docs/CODEX-SETUP.md#updates-and-migration).
For a personal build, you may explicitly supply a local PNG: `node scripts/package-codex-plugin.mjs /path/apple-mail.tar.gz --icon /path/icon.png`. The optional image must be square, noninterlaced, 48–2,048 pixels per side, and at most 4 MiB. It is bundled inside the skill's assets directory and used for the generated portable and compatibility manifests' light/dark logo and composer icons. Source manifests, the runtime, and default artwork remain unchanged; omitting `--icon` preserves the standard archive. No image is fetched automatically. Supply only artwork you have permission to use and distribute; this option does
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.
.claude-plugin/marketplace.json · Manifest · 36 lines
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "apple-mail-mcp",
- "version": "2.20.62",
- "description": "Apple Mail integration for Claude Code and Codex via MCP",
- "owner": {
- "name": "Rob Sweet",
- "email": "rob@superiortech.io"
- },
- "plugins": [
- {
- "name": "apple-mail",
- "displayName": "Apple Mail",
- "description": "Manage Apple Mail through natural language - read, search, send, and organize emails (macOS only)",
- "version": "2.20.62",
- "author": {
- "name": "Rob Sweet",
- "email": "rob@superiortech.io"
- },
- "homepage": "https://github.com/sweetrb/apple-mail-mcp#readme",
- "repository": "https://github.com/sweetrb/apple-mail-mcp",
- "license": "MIT",
- "keywords": [
- "mcp",
- "apple-mail",
- "mail",
- "email",
- "claude",
- "codex",
- "macos"
- ],
- "source": "./",
- "category": "productivity"
- }
- ]
- }
README.md · README · 2,609 lines
- # Apple Mail MCP Server
- A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like Claude to read, send, search, and manage emails in Apple Mail on macOS.
- [](https://www.npmjs.com/package/apple-mail-mcp)
- [](https://www.npmjs.com/package/apple-mail-mcp)
- [](https://www.npmjs.com/package/apple-mail-mcp)
- [](https://github.com/sweetrb/apple-mail-mcp/actions/workflows/ci.yml)
- [](https://scorecard.dev/viewer/?uri=github.com/sweetrb/apple-mail-mcp)
- [](https://www.apple.com/macos/)
- [](https://opensource.org/licenses/MIT)
- [](https://modelcontextprotocol.io)
- <p align="center">
- <img src="https://raw.githubusercontent.com/sweetrb/apple-mail-mcp/main/codex/assets/screenshot.png" alt="Apple Mail MCP — read, search, send, and organize Apple Mail from Codex, Claude, and other AI assistants" width="680">
- </p>
- > **Note:** This is the **npm/Node.js** package — install with `npx` or `npm`. There is an unrelated Python project of the same name on PyPI ([`imdinu/apple-mail-mcp`](https://github.com/imdinu/apple-mail-mcp)) installed via `pipx`/`uvx`. If you're using `uvx` and seeing a `cyclopts` dependency error, you're looking for that project, not this one.
- ## What is This?
- This server acts as a bridge between AI assistants and Apple Mail. Once configured, you can ask Claude (or any MCP-compatible AI) to:
- - "Check my inbox for unread messages"
- - "Find emails from john@example.com"
- - "Send an email to the team about the meeting"
- - "Create a draft email for me to review"
- - "Reply to that message"
- - "Forward this to my colleague"
- - "Move old newsletters to the Archive folder"
- The AI assistant communicates with this server, which then uses AppleScript to interact with the Mail app on your Mac. All data stays local on your machine.
- ## Quick Start
- ### Using Claude Code (Easiest)
- If you're using [Claude Code](https://claude.com/product/claude-code) (in Terminal or VS Code), just ask Claude to install it:
- ```
- Install the sweetrb/apple-mail-mcp MCP server so you can help me manage my Apple Mail
- ```
- Claude will handle the installation and configuration automatically.
- Or register it deterministically in one command:
- ```bash
- claude mcp add apple-mail -s user -- npx -y apple-mail-mcp
- ```
- ### Using the Plugin Marketplace
- Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:
- ```bash
- /plugin marketplace add sweetrb/apple-mail-mcp
- /plugin install apple-mail
- ```
- This method also installs a **skill** that teaches Claude when and how to use Apple Mail effectively.
- > **Configuring IMAP/SMTP for a plugin install:** a plugin install has no editable `env` block,
- > so supply settings via the config file at `~/Library/Application Support/apple-mail-mcp/config.json`
- > — Method B in the [IMAP / SMTP Setup Guide](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md).
- > Passwords stay in the macOS Keychain; run the `doctor` tool to verify.
- ### Using the Codex Marketplace
- See [Apple Mail in Codex](docs/CODEX-SETUP.md) for setup and diagnostics, and the
- [guided setup and OAuth proposal](docs/CODEX-PLUGIN-AUTH-PROPOSAL.md) for proposed
- future authorization support.
- Install the same public marketplace in Codex:
- ```bash
- codex plugin marketplace add sweetrb/apple-mail-mcp
- codex plugin add apple-mail@apple-mail-mcp
- ```
- The Codex package includes a portable `codex/plugin.json`, typed stdio server
- configuration in `codex/mcp.json`, the Apple Mail skill, and the existing assets.
- It retains `codex/.codex-plugin/plugin.json` and `codex/.mcp.json` for compatible
- older hosts. Both layouts register the same `apple-mail` MCP identity through
- `npx -y apple-mail-mcp@<plugin version>`. Release synchronization updates both
- runtime pins and manifest metadata; tests and CI reject drift. An unreleased
- candidate can be discovered locally, but its exact npm version must be
- published before that pinned launcher can be installed from the registry.
- For ongoing upstream updates, keep the Git marketplace configured. After a new
- release is published, refresh its catalog:
- ```bash
- codex plugin marketplace upgrade apple-mail-mcp
- ```
- Install the published plugin version from the refreshed marketplace, then start
- a new Codex session. The refresh does not replace the runtime pin with `@latest`;
- the plugin and its pinned npm runtime must refer to the same available release.
- The standalone plugin archive bundles the server and requires only Node.js 20+
- on the Mac; it does not fetch a runtime from npm. Download it from the release
- assets, or use the candidate artifact attached to a successful CI run. See
- [Standalone plugin archive](docs/CODEX-SETUP.md#standalone-plugin-archive) for the
- distribution format and local build command.
- An imported archive or separately uploaded private account plugin is a snapshot,
- not a subscription to this repository's releases. Updating that copy requires a
- replacement package. When switching to the maintained marketplace distribution,
- preserve settings and approvals, verify Mail access and reply behavior, then
- remove the redundant installation. See [Updates and migration](docs/CODEX-SETUP.md#updates-and-migration).
- For a personal build, you may explicitly supply a local PNG:
- `node scripts/package-codex-plugin.mjs /path/apple-mail.tar.gz --icon /path/icon.png`.
- The optional image must be square, noninterlaced, 48–2,048 pixels per side, and
- at most 4 MiB. It is bundled inside the skill's assets directory and used for
- the generated portable and compatibility manifests' light/dark logo and composer
- icons. Source manifests, the runtime, and default artwork remain unchanged;
- omitting `--icon` preserves the standard archive. No image is fetched automatically.
- Supply only artwork you have permission to use and distribute; this option does
- not grant rights to Apple or other third-party artwork, or guarantee that a host
- will refresh an existing listing's cached presentation.
- The compose tools accept `composition: "native-editor"` to insert new prose
- through Mail's visible editor, leaving its signature and reply history intact.
- This opt-in path uses existing macOS Accessibility and Automation permissions;
- it does not require a separate computer-control plugin. It verifies the composer
- and sender, preserves the clipboard, and stops without sending if insertion
- cannot be verified. See [native composition](docs/NATIVE-COMPOSITION.md) for
- setup, examples, and verification limits. Existing SMTP and AppleScript behavior
- is unchanged when the option is omitted.
- ### Other Hosts (Hermes, Antigravity)
- Two more hosts can run the same `apple-mail` MCP server (`npx -y apple-mail-mcp`):
- - **[Hermes Agent](https://hermes-agent.nousresearch.com/)** (NousResearch) — Hermes has no plugin/marketplace drop-in, so there is nothing in this repo to install from. Register the server with the CLI:
- ```bash
- hermes mcp add apple-mail --command npx --args -y apple-mail-mcp
- ```
- Or add it to `~/.hermes/config.yaml` by hand:
- ```yaml
- mcp_servers:
- apple-mail:
- command: npx
- args: ["-y", "apple-mail-mcp"]
- ```
- Restart your Hermes session afterward so the tools load.
- - **[Antigravity](https://antigravity.google/)** (Google) — add the server entry from [`.antigravity-plugin/mcp_config.json`](https://github.com/sweetrb/apple-mail-mcp/blob/main/.antigravity-plugin/mcp_config.json) to `~/.gemini/config/mcp_config.json` (or via Antigravity's MCP settings).
- ### Manual Installation
- **1. Install the server:**
- ```bash
- npm install -g apple-mail-mcp
- ```
- **2. Add to Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
- ```json
- {
- "mcpServers": {
- "apple-mail": {
- "command": "npx",
- "args": ["apple-mail-mcp"]
- }
- }
- }
- ```
- **3. Restart Claude Desktop** and start using natural language:
- ```
- "Show me my unread emails"
- ```
- On first use, macOS will ask for permission to automate Mail.app. Click "OK" to allow.
- ## Configuring email (IMAP & SMTP)
- The server works out of the box over AppleScript with **no configuration**. Two
- **opt-in** power features take a one-time setup:
- - **Fast IMAP reads** — server-side search, counts, and large-mailbox handling
- that AppleScript is too slow for (it times out on big Gmail mailboxes).
- - **Clean SMTP sending** — `send-email` submits clean MIME directly, avoiding the
- macOS 15+ Mail.app `<blockquote>` wrapping that otherwise makes sent mail look
- quoted/indented like a reply.
- Both are driven by non-secret `APPLE_MAIL_MCP_*` settings — supplied via an `env`
- block **or** a `config.json` file (for hosts like Claude Desktop that strip `env`)
- — with passwords kept in the macOS **Keychain**, never in config.
- 👉 **[IMAP / SMTP Setup Guide](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md)** — step-by-step: app passwords,
- Keychain, both config methods, multi-account, SMTP, verification with the `doctor`
- tool, and troubleshooting. Verify any time by running the **`doctor`** tool.
- ## Requirements
- - **macOS** - Apple Mail and AppleScript are macOS-only
- - **Node.js 20+** - Required for the MCP server
- - **Node.js 22.5+ and Full Disk Access** - Required by `search-contacts` only. It reads the Contacts database directly through Node's built-in `node:sqlite`, which does not exist before 22.5. On an older runtime, or without Full Disk Access for the Node binary, it logs one line to stderr and returns **an empty list rather than an error** — so "no contacts found" can mean "cannot read Contacts". Every other tool works on Node 20+. See [Node runtime & TCC permissions](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md).
- - **Apple Mail** - Must have at least one account configured (iCloud, Gmail, Exchange, etc.)
- ## Features
- ### Messages
- | Feature | Description |
- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
- | **List Messages** | List messages with pagination, sender filter, date display |
- | **Search Messages** | Search by sender, subject, content, date range, read/flagged status — across all accounts |
- | **Read Messages** | Get full email content (plain text or HTML) |
- | **Read Headers** | Get a message's raw RFC 5322 headers — the author's `Date:`, Message-ID, threading ids, `Received:` trace — without downloading the body |
- | **Send Email** | Compose and send new emails (attach by file path or inline base64 content; optional `inReplyTo`/`references` threading over SMTP) |
- | **Send Serial Email** | Mail merge — send personalized emails to a list of recipients with {{placeholder}} support |
- | **Create Draft** | Save emails to Drafts folder (attach by file path or inline base64 content; threaded drafts filed over IMAP) |
- | **Update Saved Draft** | Preview and partially edit a stored IMAP draft, retaining unchanged MIME and returning the new UID and revision |
- | **Reply** | Reply to messages (with reply-all support and attachments) |
- | **Forward** | Forward messages to new recipients (with extra attachments) |
- | **Get Thread** | Group a conversation by normalized subject (across AppleScript or IMAP) |
- | **Mark Read/Unread** | Change read status (single or batch) |
- | **Flag/Unflag** | Flag or unflag messages (single or batch) |
- | **Delete Messages** | Move messages to trash (single or batch) |
- | **Move Messages** | Organize into mailboxes (single or batch) |
- | **List Attachments** | View attachment metadata (name, type, size) |
- | **Save Attachment** | Save attachments to disk |
- | **Fetch Attachment** | Get an attachment's bytes as base64 (no disk write) |
- Read/list/get tools also return **structured JSON** (`structuredContent`) alongside the text, so agents can consume results without parsing prose.
- ### Mailbox & Account Management
- | Feature | Description |
- | -------------------------------- | ------------------------------------------- |
- | **List Mailboxes** | Show all folders with message/unread counts |
- | **Create/Delete/Rename Mailbox** | Full mailbox lifecycle management |
- | **List Accounts** | Show configured accounts |
- | **Unread Count** | Get unread counts per mailbox |
- ### Rules, Contacts & Templates
- | Feature | Description |
- | ------------------------ | ---------------------------------------------------------------------------------------- |
- | **List Rules** | View all mail rules and their enabled status |
- | **Enable/Disable Rules** | Toggle mail rules on or off |
- | **Create/Delete Rules** | Create rules with conditions + actions, or delete by name |
- | **Search Contacts** | Look up contacts from Contacts.app by name |
- | **Email Templates** | Save, list, use, and delete reusable email templates (persisted to disk across restarts) |
- ### Diagnostics
- | Feature | Description |
- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | **Health Check** | Verify Mail.app connectivity |
- | **Doctor** | Diagnose Mail permission, account state, and each IMAP/SMTP backend with actionable messages |
- | **Statistics** | Message and unread counts per account, recently received stats |
- | **Sync Status** | Check if Mail.app is actively syncing |
- | **Effect reconciliation** | Every delete/move reports what it actually did to the mailbox (`countDelta`), and warns when more messages left than were operated on — see [Auditing destructive operations](#auditing-destructive-operations) |
- ### MCP resources & prompts
- Resources expose read-only context the client can attach without a tool call:
- `mail://accounts`, `mail://templates`, and `mail://mailboxes/{account}`. Prompts
- package common workflows: `triage-inbox`, `compose-reply`, `weekly-summary`.
- ---
- ## Tool Reference
- This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.
- ### Message Operations
- #### `search-messages`
- Search for messages matching criteria. Searches all accounts by default.
- | Parameter | Type | Required | Description |
- | ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `query` | string | No | Text to search in subject/sender |
- | `body` | string | No | Text to search in the message body. IMAP backend only (server-side `BODY` search); AppleScript-only accounts are reported as not searched |
- | `from` | string | No | Filter by sender email address |
- | `subject` | string | No | Filter by subject line |
- | `mailbox` | string | No | Mailbox to search in (omit to search all mailboxes) |
- | `account` | string | No | Account to search in (omit to search all accounts) |
- | `isRead` | boolean | No | Filter by read status |
- | `isFlagged` | boolean | No | Filter by flagged status |
- | `flagColor` | string | No | Filter to messages flagged with exactly this color — see [`flag-message`](#flag-message--unflag-message) for the palette. Implies `isFlagged: true`; pairing this with `isFlagged: false` is rejected. See the flag-color note below. |
- | `dateFrom` | string | No | Start date filter (e.g., "January 1, 2026") |
- | `dateTo` | string | No | End date filter (e.g., "March 1, 2026") |
- | `limit` | number | No | Max results, 1–500 (default: 50) |
- | `offset` | number | No | Newest matches to skip, ≥ 0 (for pagination). IMAP accounts only; without a `mailbox`, `offset` + `limit` may not exceed 5,000 |
- **Returns:** List of matching messages with ID, date, subject, sender, read state,
- mailbox and account, and `flagColor` when flagged with an explicit color. When
- the results can come from more than one mailbox or account, each text line ends
- with where that message is, e.g. `| in "Deleted Items" (Exchange)`: a sent
- message and the earlier drafts of it that Exchange keeps in Deleted Items share
- a subject, and the ids alone don't tell them apart. A search of one mailbox of
- one account leaves the lines as they were.
- **Flag color as a label (#286).** Every row from both backends carries
- `flagColor` (the palette name — `red`, `orange`, `yellow`, `green`, `blue`,
- `purple`, `gray`) whenever the message is flagged with an explicit color;
- omitted for an unflagged message or one flagged with Mail's plain default (no
- color chosen). Combined with the `flagColor` filter above, a colored flag
- works as a label across mailboxes: flag a set of messages with
- `flag-message`/`batch-flag-messages`, then find exactly that set later with
- `search-messages`, without moving anything into a dedicated folder. **Known
- limitation, inherent to Apple's `$MailFlagBit0/1/2` IMAP wire encoding, not
- specific to this server:** `red` (palette index 0) sets no keyword bits, so
- over IMAP it is indistinguishable from a plain colorless flag, both when
- reading `flagColor` back and when filtering on it. AppleScript-backed
- accounts are unaffected (Mail's own `flag index` property is `0` for red, `-1`
- for none).
- ⚠️ **Row dates.** Since 2.19.7 every row — on both the IMAP and AppleScript
- backends — carries both `dateSent` (the message's `Date:` header) and
- `dateReceived` (mailbox arrival — IMAP `INTERNALDATE` or Mail's `date received`).
- They differ legitimately by transit time; when they differ by **years**, the
- mailbox was migrated or re-imported and the arrival timestamp was reset — trust
- `dateSent` for chronology ([#224](https://github.com/sweetrb/apple-mail-mcp/issues/224)).
- `dateSent` is omitted (not invented) when the message carries no parseable
- `Date:` header, or when it is more than 7 days later than `dateReceived` — Mail
- substitutes a timestamp of its own for a `Date:` header it cannot parse
- ([#234](https://github.com/sweetrb/apple-mail-mcp/issues/234)).
- **Large mailboxes & partial results.** Apple Mail's AppleScript bridge cannot
- search very large IMAP/Gmail mailboxes (tens of thousands of messages) before
- the Apple Event times out — empirically even reading the newest 20 messages of
- a 44k-message mailbox takes ~45s. To avoid burning minutes only to return a
- misleading empty result, an unscoped (all-mailboxes) search **skips** mailboxes
- whose message count exceeds a threshold (default **5000**), enforces a
- per-account time budget, and **reports** anything it skipped or that timed out
- rather than silently returning nothing. When coverage is incomplete the result
- includes an explicit warning, e.g.:
- ```
- ⚠️ Partial results — this is NOT a confirmed "no such mail":
- - skipped mailbox(es) too large to search via AppleScript: Gmail / All Mail (44287) — scope the search with `mailbox` + a `dateFrom`/`dateTo` window to target them
- ```
- To search inside a large mailbox, scope the call with `mailbox` (and ideally a
- `dateFrom`/`dateTo` window). Tune or disable the skip threshold with the
- `APPLE_MAIL_MAX_SEARCH_MAILBOX` environment variable (default `5000`; set to `0`
- to disable the guard and attempt every mailbox regardless of size).
- ([#24](https://github.com/sweetrb/apple-mail-mcp/issues/24))
- **Envelope Index search (opt-in, read-only).** For accounts with no IMAP config,
- set `APPLE_MAIL_MCP_ENVELOPE_INDEX=1` to answer header searches (`query`, `from`,
- `subject`, read/flagged state, dates, mailbox) from Mail's own on-disk Envelope Index
- instead of an AppleScript scan, so large mailboxes are searched completely rather than
- skipped. It needs Full Disk Access for the server's Node runtime and opens the database
- read-only. Text filters ignore case the way Mail does, accented and non-Latin letters
- included (`über` finds `Über`). Anything the index can't answer completely (a
- `flagColor` filter, an unknown mailbox, no Full Disk Access, an unrecognised schema, a
- corrupt or locked database, or Mail not running — opening the index then would create
- files in the mail store) falls back to the AppleScript scan. (Mail not running is judged
- by its `-wal`/`-shm` files being gone; after a Mail crash leaves them behind, a search can
- still update `-shm`, which SQLite rebuilds when Mail next opens the index.) The `backend`
- field below reports which one answered.
- ([#342](https://github.com/sweetrb/apple-mail-mcp/issues/342))
- **Body search for AppleScript-only accounts (opt-in local body index).** Without IMAP,
- `search-messages` can't search message bodies (AppleScript would have to pull every
- body through Mail), so a `body` query reports those accounts as not searched. Set
- `APPLE_MAIL_MCP_BODY_INDEX=1` **together with** `APPLE_MAIL_MCP_ENVELOPE_INDEX=1` to
- search them through a local full-text index of the `.emlx` files Mail already keeps
- on disk. ([#349](https://github.com/sweetrb/apple-mail-mcp/issues/349))
- - **What it reads, and what it needs.** Message files under `~/Library/Mail`, read
- only; the mail store is never written. Like the Envelope Index backend, it needs
- **Full Disk Access** for the app that runs the server (its Node runtime). `doctor`
- reports when it can't read the store, with the same wording.
- - **Where the index lives.** `~/Library/Application Support/apple-mail-mcp/body-index.db`
- (plus `-wal`, `-shm` and `.writer-lock` next to it); set
- `APPLE_MAIL_MCP_BODY_INDEX_FILE` to move it. The directory is created `0700` and the
- files `0600`. The index is _contentless_: it stores the search tokens, not a copy of
- any message, but the tokens still reveal a lot about your mail — treat the file as
- sensitive. Expect roughly 70 MB per 22,000 messages.
- - **Deleting it.** Turn the flag off (or stop the server), then delete the files:
- ```bash
- rm -f ~/Library/Application\ Support/apple-mail-mcp/body-index.db*
- ```
- It is only a cache; with the flag on it is rebuilt from scratch on the next start.
- - **First build and upkeep.** One server instance (the first to start) builds and
- updates the index in the background in small slices; other instances — one per
- conversation in some hosts — search it read-only and take over if that instance
- exits. The walking and parsing run in a short-lived child process (the same
- `build/index.js` on the same Node runtime, so the same Full Disk Access grant
- applies), which exits as soon as it has caught up: the server stays responsive during
- a build, and the memory parsing takes goes back to the system instead of staying with
- the server. If that process can't start or can't read the store, the server builds
- on its own main thread instead and `doctor` says why (and tries a build process again
- an hour later). A build process that stops responding for a minute is stopped and
- restarted. (A host that runs the server on Electron's Node gets the main-thread build:
- a forked process there would start the app.) A message file that can't be read or
- parsed is skipped, counted, and tried
- again on the next full check; it never holds up the rest. New mail is picked up through
- file-system events within seconds, with a full check every 10 minutes as a safety
- net. A build of ~22,000 messages took about 40 s on an Apple-silicon Mac.
- - **What it matches.** Words and word beginnings, ignoring case and accents: `invoice`
- finds `invoices` and `Invoice`, but not `reinvoice`, as the index stores words, not
- text. Text with no letters or digits (`@`), and Chinese, Japanese or Thai text (written
- without spaces between words), can't be matched that way, so a body search for it
- reports the account as not searched rather than as no match.
- - **Coverage is always reported.** A body search never presents an incomplete index as
- "no matches". Messages in the searched scope that it couldn't read in full are
- counted, and the result is `partial: true` with a `notSearchedMailboxes` entry such as
- `Google / * (1,234 messages not downloaded, 12 not indexed yet)`. _Not downloaded_
- means Mail has only the headers (common for older mail on IMAP/Exchange accounts set
- to download recent messages only); open those messages in Mail, or change the
- account's download setting, to make them searchable. Messages over 25 MB are not read.
- Until the first build has walked the whole store, messages it hasn't reached yet are
- counted as _not indexed yet_.
- - **Requirements.** Node 22.5 or later (for `node:sqlite`); on older runtimes the
- feature turns itself off and says why in the logs and `doctor`.
- **Coverage diagnostics (structured fields).** The warning above is prose for a
- human reader; the same information is also returned as structured fields on
- `search-messages` and `list-messages`, so a caller can tell _"nothing matched"_
- apart from _"I did not look everywhere"_ without parsing the text:
- | Field | Type | Meaning |
- | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `partial` | boolean | Coverage was incomplete — **the result is not a confirmed "no such mail"**. True whenever any field below is non-empty. |
- | `skippedLargeMailboxes` | string[] | Mailboxes never scanned because their message count exceeded `APPLE_MAIL_MAX_SEARCH_MAILBOX`, formatted `"Account / Mailbox (count)"` — e.g. `"iCloud / Archive (90694)"`. |
- | `notSearchedMailboxes` | string[] | Mailboxes that _were_ reached but timed out or errored mid-scan, formatted `"Account / Mailbox"`. Also carries the IMAP path's `failedMailboxes`. |
- | `timedOutAccounts` | string[] | Accounts whose whole-account AppleScript was killed by the per-account time budget — nothing from that account was searched. |
- | `failedMailboxes` | string[] | IMAP-backend mailboxes that errored. These are merged into `notSearchedMailboxes` as well; read that field unless you need to attribute the failure to the IMAP path specifically. |
- | `failedMailboxReasons` | object | The IMAP server's own error text for each entry in `failedMailboxes`, keyed the same way. |
- | `omittedMessages` | object[] | IMAP messages that belong on the page but whose `FETCH` response could not be read even with a reduced item set — `{ id, mailbox, uid, reason }`. The page is short by exactly these; the `id` still works with `get-message` / `get-message-headers`. ([#256](https://github.com/sweetrb/apple-mail-mcp/issues/256)) |
- | `timedOutMailboxes` | string[] | IMAP mailboxes the search did not finish because the call was **cancelled** (`notifications/cancelled`) or reached its **deadline** (`APPLE_MAIL_MCP_SEARCH_DEADLINE_MS`, default 45s), formatted `"Account / Mailbox"`; an account never reached is `"Account / *"`. Results from the mailboxes that did finish are still returned. ([#276](https://github.com/sweetrb/apple-mail-mcp/issues/276)) |
- | `stoppedBy` | string | `"deadline"` or `"cancelled"` — present only with `timedOutMailboxes`. |
- | `backend` | string | `search-messages` only: which backend answered the non-IMAP accounts — `"envelope-index"`, `"applescript"`, or `"mixed"` (see `backendByAccount`). Also shown on the summary line while `APPLE_MAIL_MCP_ENVELOPE_INDEX` is on. ([#342](https://github.com/sweetrb/apple-mail-mcp/issues/342)) |
- | `backendByAccount` | object | Present only when `backend` is `"mixed"`: account name → `"envelope-index"` or `"applescript"`. |
- **Deadline and cancellation ([#276](https://github.com/sweetrb/apple-mail-mcp/issues/276)).** Tool
- calls run one at a time (so they cannot race into Mail.app), which means a long search holds every
- later call behind it. An IMAP `search-messages` therefore stops at
- `APPLE_MAIL_MCP_SEARCH_DEADLINE_MS` (default `45000`, minimum `2000`, measured from when the request
- arrived — time queued behind other calls counts) and returns what it found plus `timedOutMailboxes`,
- and it stops the same way when the client cancels the request. The mailbox being searched at that
- moment is abandoned by closing its IMAP connection (the next call reconnects), so the queue is
- released promptly rather than after a server-side `SEARCH` that can take a minute and a half on a
- very large mailbox. A request cancelled while still queued is skipped. Keep the deadline below your
- client's own request timeout.
- Treat a non-empty `skippedLargeMailboxes` as actionable rather than
- informational: re-run scoped to the named mailbox with a `dateFrom`/`dateTo`
- window, or configure the [IMAP backend](#imap-backend--opt-in), which searches
- those mailboxes server-side. The list fields are optional and are omitted (or
- empty) when coverage was complete.
- A row the IMAP backend could only read with a reduced item set (its full
- `BODYSTRUCTURE`, or its whole `FETCH` response, was unparseable — e.g. a message
- forwarded as an attachment many levels deep) is still returned, with a
- `metadataIncomplete` note saying what was missing; its `hasAttachments` is then
- inferred from the top-level `Content-Type`.
- ---
- #### `get-message`
- Get the full content of a message.
- | Parameter | Type | Required | Description |
- | ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `id` | string | Yes | Message ID |
- | `preferHtml` | boolean | No | Return HTML source instead of plain text |
- | `mailbox` | string | No | Mailbox holding the message (e.g. `"Sent Items"`). With `account`, opens that mailbox directly instead of scanning every mailbox — this is the fix for timeouts on large folders. A miss there is reported as "not found in <account> / <mailbox>"; it never falls back to the cross-mailbox scan |
- | `account` | string | No | Account holding the message. Pair with `mailbox` to skip the cross-mailbox scan |
- **Returns:** Subject line and message body (plain text by default, HTML if `preferHtml` is true and HTML content is available). `structuredContent` also carries `rfcMessageId` and, since 2.19.0, two dates: `dateSent` (the message's `Date:` header — Mail's `date sent`) and `dateReceived` (arrival in the mailbox — Mail's `date received` / IMAP `INTERNALDATE`). They differ legitimately by transit time; when they differ by **years**, the mailbox was migrated or re-imported and the arrival timestamp was reset — trust `dateSent` for chronology ([#224](https://github.com/sweetrb/apple-mail-mcp/issues/224)). Since 2.19.6 `dateSent` is **omitted** when it is more than 7 days later than `dateReceived`: a message cannot be sent after it arrived, and Mail.app substitutes a timestamp of its own for a `Date:` header it cannot parse ([#234](https://github.com/sweetrb/apple-mail-mcp/issues/234)). `isHtml` reports what was actually returned — a message with no `text/plain` part returns its HTML part with `isHtml: true`. Bodies are decoded by each part's declared `charset`, falling back to windows-1252 for bytes that are not valid UTF-8.
- **Numeric ids — how the message is found ([#270](https://github.com/sweetrb/apple-mail-mcp/issues/270)):** with `account` + `mailbox` the read opens that one mailbox and stops there. Otherwise it opens the mailbox the id was last listed or searched from. A stale remembered location is forgotten before a bounded scan, but an ambiguous remembered account or mailbox stops without a scan. That cross-mailbox scan skips any mailbox holding more than `APPLE_MAIL_MAX_BYID_SCAN_MAILBOX` messages (default `50000`; `0` disables the guard) and stops after ~9s, because Mail's `whose id is` probe costs seconds per hundred thousand messages; a miss then names the mailboxes it skipped and, if it stopped early, the ones it never reached. A mailbox whose size count does not answer within 3s is remembered — on disk, for 7 days, across restarts (`APPLE_MAIL_MCP_STALLED_MAILBOXES_FILE`, default `~/Library/Application Support/apple-mail-mcp/stalled-mailboxes.json`; delete it to forget) — and never counted again, since Mail.app keeps working on an abandoned count and everything after it would queue; the scan stops the moment such a count times out rather than queue behind it. If Mail.app is not running these reads say so instead of launching it. Pass `account` + `mailbox` to read from one of those, or use the message's `imap:` id, which never scans. The same resolution backs `get-message-headers`, `get-thread`'s seed lookup, and the original-message read of `reply-to-message` / `forward-message` and the attachment tools.
- > **Large messages / attachments:** reading a full message routes through
- > `osascript`, whose captured output buffer defaults to **64 MB**. Override it
- > with the `APPLE_MAIL_MCP_MAX_BUFFER` environment variable (in **bytes**) if you
- > work with messages whose raw MIME (e.g. a large embedded attachment) exceeds
- > that — a value below the message size makes the read fail with a buffer-overflow
- > error rather than truncating ([#27](https://github.com/sweetrb/apple-mail-mcp/issues/27)).
- ---
- #### `get-message-headers`
- Return a message's raw RFC 5322 header block — without fetching the body or any attachment — plus the parsed fields chronological and threading work needs. Added in 2.19.0 for mailboxes whose arrival timestamps were reset by a migration ([#224](https://github.com/sweetrb/apple-mail-mcp/issues/224)): the `Date:` header is the author's send time and survives such moves; `INTERNALDATE` / `date received` does not.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
- | `id` | string | Yes | Message ID (numeric or `imap:…`) |
- | `mailbox` | string | No | Mailbox holding the message. With `account`, opens that mailbox directly instead of scanning every mailbox |
- | `account` | string | No | Account holding the message. Pair with `mailbox` to skip the cross-mailbox scan |
- **Returns:** The raw header block as text. `structuredContent` carries `raw`, every header as ordered `headers[]` (`{name, value}`, folded lines joined, duplicates such as `Received:` kept in wire order, values left RFC 2047-encoded), `headerCount`, and the decoded key fields: `date` (ISO 8601, from the `Date:` header), `dateHeader` (verbatim), `dateReceived` (mailbox arrival time — IMAP `INTERNALDATE` or Mail's `date received`), `messageId`, `subject`, `from`, `to`, `cc`, `replyTo`, `inReplyTo`, `references[]` and `received[]` (first entry = last hop). Fields the message does not carry are omitted. `backend` says which backend read the block (`"imap"` or `"applescript"`), and `warnings[]` appears when a malformed block was repaired ([#234](https://github.com/sweetrb/apple-mail-mcp/issues/234)).
- **Backends (`get-message-headers`):** an `imap:` id reads the first 64 KiB of `BODY.PEEK[]` over IMAP and cuts the header block out of it (cheap even for a 20 MB message). That is deliberate: iCloud rewrites 8-bit header bytes to `*` in ENVELOPE and `BODY[HEADER]`, and only `BODY[]` returns them as stored; each line is decoded as UTF-8, falling back to windows-1252, so a raw latin-1 display name survives. A header block larger than the window falls back to `BODY.PEEK[HEADER]`. A numeric id reads Mail's `all headers` property over AppleScript, with the same mailbox-scoped fast path as `get-message`. ⚠️ That property is Mail's own rendering, not the stored bytes: for a `Date:` value Mail cannot parse it drops the value and joins the next header onto the name (`Date: Subject: …`). The tool splits that back apart, reports the date as absent rather than as a Subject string, and says so in `warnings[]`; the `imap:` id for the same message has the real `Date:`.
- ---
- #### `get-message-rfc822`
- Acquire a message's **complete original RFC 822 bytes exactly as the IMAP server stores them**, together with the IMAP identity that links the copy back to its source ([#244](https://github.com/sweetrb/apple-mail-mcp/issues/244)). Built for archival, forensic review and evidence preservation: nothing is decoded, charset-converted, line-ending-normalized or MIME-re-serialized, and the SHA-256 is computed over exactly the bytes returned. **IMAP-only** — it needs an `imap:` id, i.e. an IMAP-configured account ([docs/IMAP-SETUP.md](docs/IMAP-SETUP.md)). There is no AppleScript path on purpose: Mail's bridge exposes its own rendering of a message, not the stored bytes.
- | Parameter | Type | Required | Description |
- | ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `id` | string | Yes | An `imap:` message id (numeric Mail.app ids are refused with an explanation) |
- | `savePath` | string | No | Directory inside the configured allowed roots. Writes the bytes to a **new** `.eml` there instead of returning them inline, and raises the size ceiling to 25 MiB |
- | `fileName` | string | No | File name to use with `savePath` (no path separators, no `..`). Default `<account>-<mailbox>-uidv<UIDVALIDITY>-uid<UID>.eml` |
- | `maxBytes` | number | No | Refuse — never truncate — a message larger than this many raw bytes. Default and inline maximum 6 MiB (`6291456`); with `savePath` up to 25 MiB (`26214400`) |
- **Returns:** a one-line summary as text. `structuredContent` carries the acquisition record: `account`, `mailbox`, `uid`, `uidValidity` (decimal string), `internalDate` (ISO 8601 `INTERNALDATE` — arrival, not the `Date:` header), `flags[]`, `size` (the server's `RFC822.SIZE`), `bytes` (the count actually acquired and hashed), `sha256` (hex, over exactly those bytes), `messageId` (from `ENVELOPE`, for convenience — the authoritative copy is in the bytes), `readMethod` (the IMAP commands issued), `backend: "imap"` and `warnings[]` — plus **`contentBase64`** in inline mode or **`savedPath`** in file mode. The base64 is carried **only** in `structuredContent`; the text block never repeats it.
- **Read-only by construction.** The mailbox is opened with `EXAMINE` and the body fetched with `BODY.PEEK[]`, so `\Seen` is not set and no `STORE`, `COPY`, `MOVE`, `APPEND` or `EXPUNGE` is issued. No Mail.app, AppleScript or osascript is involved. The only side effect is the optional file, created with `wx` (an existing file or symlink is refused, never overwritten) and mode `0600`, and only inside the allowed roots — the same policy as `save-attachment`.
- **Sizes.** The inline ceiling exists because the MCP stdio transport drops any single message over 10 MB with no error text: 6 MiB of raw bytes is 8 MiB of base64. `maxBytes` is a ceiling, not a cut — an oversize message is refused with its `RFC822.SIZE`, so you can choose between raising `maxBytes` (inline, up to 6 MiB) and `savePath` (up to 25 MiB). `warnings[]` reports an `RFC822.SIZE` that disagrees with the byte count actually received (the hash still covers what was received) and a server that reported no `UIDVALIDITY`.
- **Verifying a derivative.** `shasum -a 256 file.eml` must equal `sha256`. `account` + `mailbox` + `uidValidity` + `uid` is the durable pointer back to the source message — a UID on its own is meaningful only for one `UIDVALIDITY`, which the server may change (typically on a mailbox rebuild).
- ---
- #### `list-messages`
- List messages in a mailbox.
- | Parameter | Type | Required | Description |
- | ------------ | ------- | -------- | ------------------------------------------------ |
- | `mailbox` | string | No | Mailbox name (omit to list from all mailboxes) |
- | `account` | string | No | Account name |
- | `limit` | number | No | Max messages, 1–500 (default: 50) |
- | `offset` | number | No | Number of messages to skip, ≥ 0 (for pagination) |
- | `from` | string | No | Filter by sender email address or name |
- | `unreadOnly` | boolean | No | Only show unread messages |
- **Returns:** List of messages with ID, date, subject, sender, mailbox and
- account, and `flagColor` when flagged with an explicit color (see the flag-color
- note under [`search-messages`](#search-messages), which also supports filtering
- by it). As there, each text line names its mailbox and account when the listing
- can span more than one.
- ⚠️ **Row dates.** Since 2.19.7 every row — on both the **IMAP** and
- **AppleScript** backends — carries both `dateSent` (the message's `Date:`
- header) and `dateReceived` (mailbox arrival — IMAP `INTERNALDATE`, falling back
- to the header date if the server withholds it; Mail's `date received` on the
- AppleScript path). They differ legitimately by transit time; when they differ
- by **years**, the mailbox was migrated or re-imported and the arrival timestamp
- was reset — trust `dateSent` for chronology
- ([#224](https://github.com/sweetrb/apple-mail-mcp/issues/224)). Since 2.19.6 the
- IMAP `dateSent` is recovered even when the server's own parse of the `Date:`
- header failed (legacy locale dates such as `jue ago 30 13:55:12 2007`); both
- backends omit `dateSent` (rather than reporting it) when it is more than 7 days
- later than `dateReceived` ([#234](https://github.com/sweetrb/apple-mail-mcp/issues/234)).
- Before 2.19.7 the AppleScript path carried only `dateReceived`. Sort order keys
- on the header date on both backends, which is the stable one.
- ---
- #### `send-email`
- Send a new email immediately.
- **⚠️ Safety:** Sends real mail immediately and cannot be unsent. Confirm the recipients, subject, and body with the user before calling.
- | Parameter | Type | Required | Description |
- | ------------- | --------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `to` | string[] | Yes | Recipient addresses |
- | `subject` | string | Yes | Email subject |
- | `body` | string | Yes | Email body (plain text) |
- | `cc` | string[] | No | CC recipients |
- | `bcc` | string[] | No | BCC recipients |
- | `account` | string | No | Mail.app account name or exact sender address (AppleScript path: resolved to one address of an enabled account and verified against Mail's `sender` before sending — no match, or Mail would use another sender, is an error and nothing is sent; the sender used is returned as `from`), or an email-form SMTP From override. An SMTP override must match `APPLE_MAIL_MCP_SMTP_USER`, `APPLE_MAIL_MCP_SMTP_FROM`, or an address in `APPLE_MAIL_MCP_SMTP_ALLOWED_FROM` |
- | `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths inside the configured read roots (e.g., `"/Users/me/Documents/report.pdf"`) and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each |
- | `transport` | `"applescript"` \| `"smtp"` | No | Send transport. If omitted, **SMTP is used automatically when configured** (otherwise AppleScript), unless `account` is a Mail.app account label, which selects AppleScript. Pass `"smtp"` to require clean MIME (a bare account label is then rejected before sending rather than silently using the configured SMTP identity), or `"applescript"` to force the Mail.app path — see [SMTP transport](#smtp-transport) |
- | `replyTo` | string | No | SMTP only: `Reply-To` header, when replies should go somewhere other than the From address. Ignored on the AppleScript transport |
- | `inReplyTo` | string | No | SMTP only (2.20.0): thread the message as a reply — the parent's `Message-ID` token with angle brackets, e.g. `"<abc@mail.example.com>"`. Emitted verbatim, never RFC 2047-encoded. See [Threading headers](#threading-headers-inreplyto--references) |
- | `references` | string[] | No | SMTP only (2.20.0): the `References` chain, oldest first (the parent's own `References` + its `Message-ID`). Defaults to `[inReplyTo]` when omitted |
- **Example:**
- ```json
- {
- "to": ["colleague@company.com"],
- "subject": "Meeting Tomorrow",
- "body": "Hi, just confirming our meeting at 2pm tomorrow.",
- "account": "Work",
- "attachments": ["/Users/me/Documents/agenda.pdf"]
- }
- ```
- ##### Threading headers (`inReplyTo` / `references`)
- `send-email` and `create-draft` accept caller-built threading headers (2.20.0, #267) for
- callers that compose the recipients and quoted text themselves. **Prefer
- `reply-to-message`** — it derives recipients, `In-Reply-To`/`References` and the quote
- from the original, and (since 2.20.0) takes attachments too.
- - Each value must be a single RFC 5322 msg-id token **with** angle brackets
- (`<left@right>`, no whitespace); anything else is rejected by validation.
- - The headers are always emitted as plain `<id>` tokens — never RFC 2047-encoded, even
- for Outlook/Exchange IDs longer than 76 characters (a long header is folded at
- whitespace between tokens, which is legal and does not alter the id).
- - Mail.app's AppleScript cannot set these headers, so they are **never silently
- dropped**: `send-email` refuses them unless the SMTP transport is in use, and
- `create-draft` files a threaded draft over IMAP instead of through Mail.app (below).
- ##### SMTP transport
- On macOS 15+ (Sequoia/Tahoe), Mail.app wraps any AppleScript-injected body in
- `<blockquote type="cite">` under the `Apple-Mail-URLShareWrapperClass` template,
- so emails sent through the default `applescript` transport render to recipients
- as if they were quoted/forwarded (Apple radar **FB11734014**, open since
- Ventura). The SMTP transport bypasses Mail.app entirely and submits clean MIME
- directly. **Once SMTP is configured, `send-email` uses it automatically** (no
- need to pass `transport` per call); pass `transport: "applescript"` to force the
- Mail.app path.
- Two differences to know when SMTP is auto-preferred:
- - **Sent-folder copy is best-effort over IMAP.** SMTP submission itself never
- touches IMAP, so since 2.18.0 the server files the sent message into the Sent
- mailbox of whichever configured IMAP account's login matches the SMTP identity
- (`APPLE_MAIL_MCP_IMAP_*` mirroring `APPLE_MAIL_MCP_SMTP_*`), flagged `\Seen`.
- The copy carries the same `Message-ID` that was delivered, so replies thread
- against it correctly, and it keeps the `Bcc` header the recipients never see —
- your own archive is exactly where that belongs. Results report `sentCopy: true`
- or `sentCopy: false` with `sentCopyError`; the field is **absent** when no
- configured IMAP account matches the SMTP identity, which is a skip, not a
- failure. A copy that fails never fails the send — the mail has already gone.
- Before appending, the Sent mailbox is searched for that `Message-ID`; if the
- submission server already filed it (Gmail's SMTP always does — the server
- waits up to ~3 s for it there), nothing is appended and the result adds
- `sentCopyAlreadyFiled: true` alongside `sentCopy: true`.
- Use `transport: "applescript"` if you want Mail.app itself to file the copy.
- - **`account` is a From override, not account selection.** Over SMTP, `account`
- is used as the From address only when it is an email address; a Mail.app
- account _label_ (e.g. `"Work"`) can't select an account over SMTP, so a call
- that passes one is left on the AppleScript path automatically. To force
- account selection, pass `transport: "applescript"` explicitly. For sender
- safety, an email-form override must match the SMTP login user, the configured
- `APPLE_MAIL_MCP_SMTP_FROM`, or an address listed in the comma-separated
- `APPLE_MAIL_MCP_SMTP_ALLOWED_FROM`; any other From address is rejected before
- connecting.
- Both plain-text and HTML bodies are supported — over SMTP an HTML body (CLI
- `--html-body-file`) is sent as `multipart/alternative` with the plain-text
- fallback.
- ###### SMTP submission outcomes
- SMTP acceptance is not confirmation that a message reached an inbox. The
- `send-email`, `reply-to-message`, and `forward-message` tools preserve the
- server's `accepted` and `rejected` recipient lists when available:
- | Outcome | Result | Retry guidance |
- | ------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
- | All recipients accepted | `ok: true`, `sent: true` | The submission succeeded. |
- | Some recipients rejected | `ok: false`, `sent: true`, `partial: true` | Do not resend to accepted recipients; reconsider only the rejected addresses. |
- | Known refusal or failure before submission | Tool error, `ok: false`, `sent: false` | Correct the reported problem before retrying. |
- | Final acknowledgment lost | `ok: false`, `deliveryUnknown: true`; `sent` omitted | Verify the outcome before retrying; the server may already have accepted the message. |
- Partial and unknown outcomes are **non-error MCP responses** so callers do not
- automatically retry a submission that may have succeeded. Check `ok`, `partial`,
- and `deliveryUnknown`, not only `isError`. No automatic retry or transport fallback
- occurs. Serial sends retain recipient acceptance fields on each result and use
- numeric `sent`, `failed`, and optional `unknown` counts rather than a boolean
- `sent`. Unknown submissions are excluded from the other two counts. A best-effort
- Sent-folder copy remains a separate result, not proof of recipient delivery.
- Configure SMTP via environment variables on the MCP server. The password is
- read from the macOS **Keychain** by default, so no secret goes in config:
- Non-implicit-TLS SMTP connections fail closed if STARTTLS is unavailable.
- `APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT=1` is a deliberate escape hatch for a
- trusted isolated server or test fixture; it disables the upgrade requirement and
- can expose credentials and message content. The server emits a warning when it
- is used. Keep the default unset.
- | Variable | Required | Default | Description |
- | -------------------------------------- | -------- | --------------------------- | -------------------------------------------------------------------------------------------- |
- | `APPLE_MAIL_MCP_SMTP_HOST` | Yes | — | SMTP server hostname (e.g. `smtp.fastmail.com`) |
- | `APPLE_MAIL_MCP_SMTP_USER` | Yes | — | SMTP username |
- | `APPLE_MAIL_MCP_SMTP_PORT` | No | `465` if secure, else `587` | SMTP port |
- | `APPLE_MAIL_MCP_SMTP_SECURE` | No | `false` | `true` for implicit TLS (port 465); otherwise STARTTLS |
- | `APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT` | No | `0` | Set `1` only for an explicitly trusted plaintext test/server; otherwise STARTTLS is required |
- | `APPLE_MAIL_MCP_SMTP_FROM` | No | = user | From address |
- | `APPLE_MAIL_MCP_SMTP_ALLOWED_FROM` | No | — | Comma-separated sender aliases permitted as per-message From overrides |
- | `APPLE_MAIL_MCP_SMTP_PASSWORD` | No | — | Password (if set, used instead of the Keychain) |
- | `APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE` | No | = host | Keychain item service/server name |
- | `APPLE_MAIL_MCP_SMTP_KEYCHAIN_ACCOUNT` | No | = user | Keychain item account |
- Store the password in the Keychain once (an app-specific password for Gmail/
- iCloud). A generic-password item with an explicit service name keeps it from
- colliding with the system mail account password, and matches
- `APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE`:
- ```bash
- # Fastmail (Keychain service defaults to the host)
- security add-internet-password -s smtp.fastmail.com -a you@example.com -w
- # Gmail / Google Workspace, using a dedicated Keychain service name:
- # APPLE_MAIL_MCP_SMTP_HOST=smtp.gmail.com
- # APPLE_MAIL_MCP_SMTP_USER=you@gmail.com
- # APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE=apple-mail-mcp-smtp
- security add-generic-password -s apple-mail-mcp-smtp -a you@gmail.com -w
- ```
- Once the env vars are set, a plain `send-email` (no `transport`) already goes
- out clean:
- ```json
- {
- "to": ["colleague@company.com"],
- "subject": "Standings",
- "body": "Plain body — no blockquote wrapping."
- }
- ```
- ###### `apple-mail-send` CLI (no MCP server required)
- The package also installs an `apple-mail-send` binary — a standalone CLI over the
- same SMTP path, for cron jobs, scheduled tasks, and scripts that can't run an MCP
- session. It reads the identical `APPLE_MAIL_MCP_SMTP_*` env + Keychain config:
- ```bash
- apple-mail-send \
- --from you@example.com --to colleague@company.com \
- --subject "Standings" --body-file /tmp/body.txt \
- [--html-body-file /tmp/body.html] [--attach /tmp/report.pdf]
- ```
- Repeatable `--to`/`--cc`/`--bcc`/`--attach`; an `--html-body-file` is sent as a
- `multipart/alternative` alongside the plain `--body-file`. Exit codes follow
- `sysexits.h` for usage/configuration failures: `64` usage error, `66` unreadable
- body file, `78` SMTP not configured. Submission exits are `0` for full acceptance,
- `1` for a known failure, `2` for partial acceptance, and `3` for an unknown
- outcome. Do not retry the complete command after exit `2` or `3`; follow the
- recipient details and verification guidance in its output.
- ##### IMAP backend — opt-in
- > 📘 **For step-by-step setup (app passwords, Keychain, config methods, multi-account, upgrading, troubleshooting), see the [IMAP / SMTP Setup Guide](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md).** The summary below is the reference; the guide is the walkthrough.
- AppleScript runs `search`/`list` predicates client-side over the Apple Event
- bridge, which is slow and can time out (false-empty) on large Gmail/IMAP
- mailboxes (see [#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)), and
- its `delete`/`rename mailbox` and draft handlers don't work on server-side
- accounts at all (#42). When an account is configured for IMAP, the MCP routes to
- a server-side IMAP backend ([#43](https://github.com/sweetrb/apple-mail-mcp/issues/43))
- that is fast and correct on exactly those mailboxes. This is **opt-in and
- additive**: any account without IMAP configured behaves exactly as before
- (AppleScript).
- What routes to IMAP when an account is IMAP-configured:
- - **Read:** `search-messages`, `list-messages` (server-side `SEARCH`, typically sub-second), and `get-message`.
- - **Folder ops:** `create-mailbox`, `rename-mailbox`, `delete-mailbox` — IMAP's `CREATE`/`RENAME`/`DELETE` succeed on the iCloud/Gmail/Workspace/Exchange mailboxes Mail.app's AppleScript bridge can't touch (#42).
- - **Message mutations:** `mark-as-read`/`unread`, `flag-message`/`unflag-message`, `move-message`, `delete-message`.
- - **Batch mutations (2.1):** `batch-mark-as-read`/`unread`, `batch-flag`/`unflag-messages`, `batch-move-messages`, `batch-delete-messages` — `imap:` ids are grouped by mailbox and applied as a single `UID STORE`/`UID MOVE`; numeric ids in the same batch still use AppleScript.
- - **Counts & stats (2.1):** `get-unread-count` and `list-mailboxes` use `STATUS`; `get-mail-stats` uses `STATUS` + `SEARCH SINCE` — authoritative and fast even on huge mailboxes. As of v2.6.0 these prefer IMAP whenever it's configured (see _Read routing_ below), merging across accounts when no `account` is given.
- - **Attachments (2.1):** `list-attachments`, `save-attachment`, `fetch-attachment` use `BODYSTRUCTURE` + `FETCH BODY[part]` for `imap:` ids — faster and able to see MIME-embedded attachments AppleScript misses.
- - **Threading (2.1):** `get-thread` links a conversation via `References`/`Message-ID` (`HEADER SEARCH`) for an `imap:` seed, falling back to subject grouping otherwise.
- **Message ids are backend-tagged.** The IMAP read path emits self-describing ids
- of the form `imap:<token>` (the token encodes the account, mailbox path, and
- UID). Pass that id back to `get-message`, a message mutation, a batch op, or the
- attachment/thread tools and it routes to IMAP automatically; bare numeric ids
- continue to use AppleScript. So an agent never has to know which backend a
- message came from — the id carries it.
- **Read routing (v2.6.0): reads PREFER direct IMAP whenever IMAP is configured.**
- The read tools — `search-messages`, `get-thread`, `list-messages`,
- `list-mailboxes`, `get-unread-count`, `get-mail-stats` — now go to IMAP whenever
- any `APPLE_MAIL_MCP_IMAP_*` account is configured, not just when an explicit
- matching `account` is passed. There are three cases:
- - **Explicit IMAP account** — single-account IMAP (fast server-side path).
- - **Explicit non-IMAP account** — AppleScript (that account isn't on IMAP).
- - **No `account` given** — **merge across all accounts**: the query fans out over
- _every_ configured IMAP account, **and** AppleScript runs **only for the
- accounts no IMAP config covers** (the account list is partitioned — accounts
- already served by IMAP are _not_ re-scanned via AppleScript). If every Mail
- account is IMAP-configured, AppleScript is skipped entirely. The results are
- merged so no account is dropped. Message lists still de-duplicate as a safety
- net (preferring the IMAP copy, which carries the round-trippable `imap:` id) and
- sort newest-first; count tools (`get-unread-count`, `get-mail-stats`) count each
- account via exactly one backend so a coverage mismatch can never double- (or
- under-) count.
- - **An omitted mailbox on `search-messages` searches the account's entire
- store, not just one default folder** (v2.17.1, [#199](https://github.com/sweetrb/apple-mail-mcp/issues/199)).
- Per account, the fan-out uses the server-advertised RFC 6154 `\All`
- mailbox when one exists (Gmail/Workspace's `[Gmail]/All Mail`); otherwise
- it searches every selectable mailbox the server lists (iCloud, generic
- IMAP), merges the matches, de-duplicates by Message-ID, and sorts
- newest-first before applying `limit`/`offset`. A mailbox that can't be
- selected or searched is named in the result instead of silently dropping
- coverage. Scanning every mailbox on a large, deeply-nested account costs
- one `SEARCH` + a bounded `FETCH` per mailbox over the pooled IMAP
- connection — pin a `mailbox` to skip the fan-out when you already know
- where to look. `list-messages` (no query) still defaults an omitted
- mailbox to `INBOX` on every provider — only unscoped _search_ scans the
- whole account.
- If IMAP is **not** configured at all, every read behaves exactly as before
- (pure AppleScript). The three mailbox-**write** ops (`create-mailbox`,
- `delete-mailbox`, `rename-mailbox`) remain conservative — they route to IMAP only
- for an explicitly-named IMAP account, never on an omitted account.
- | Variable | Required | Default | Description |
- | -------------------------------------- | -------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `APPLE_MAIL_MCP_IMAP_USER` | Yes | — | Login address; setting it enables IMAP |
- | `APPLE_MAIL_MCP_IMAP_ACCOUNT` | No | = user | Mail account name to match for routing |
- | `APPLE_MAIL_MCP_IMAP_HOST` | No | `imap.gmail.com` | IMAP server hostname |
- | `APPLE_MAIL_MCP_IMAP_PORT` | No | `993` | IMAP port (993 = implicit TLS) |
- | `APPLE_MAIL_MCP_IMAP_ALLOW_PLAINTEXT` | No | `0` | Set `1` only for an explicitly trusted plaintext test/server; otherwise STARTTLS is required |
- | `APPLE_MAIL_MCP_IMAP_PASSWORD` | No | — | Password (if set, used instead of the Keychain) |
- | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE` | No | — | Keychain item service/server name |
- | `APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT` | No | = user | Keychain item account |
- | `APPLE_MAIL_MCP_IMAP_ACCOUNTS` | No | — | JSON array of **additional** IMAP accounts for multi-account setups (see below) |
- | `APPLE_MAIL_MCP_IMAP_IDLE` | No | `0` | Set `1` to enable IMAP IDLE push notifications (new-mail alerts) for every configured account |
- | `APPLE_MAIL_MCP_IMAP_IDLE_MS` | No | `30000` | Idle timeout (ms) before a pooled IMAP connection is closed (`0` = never close) |
- | `APPLE_MAIL_MCP_STATS_BUDGET_MS` | No | `25000` | Per-account wall-clock budget for `get-mail-stats` (minimum `1000`). Raise it for very large accounts |
- | `APPLE_MAIL_MCP_STATS_DEADLINE_MS` | No | `50000` | Overall wall-clock deadline for one `get-mail-stats` call (minimum `2000`), measured from when the request arrived and covering time queued behind other tool calls, account enumeration **and** every per-account read. Keep it below your client's request timeout |
- | `APPLE_MAIL_MCP_SEARCH_DEADLINE_MS` | No | `45000` | Overall wall-clock deadline for one IMAP `search-messages` call (minimum `2000`), measured from when the request arrived. On expiry the search returns partial results plus `timedOutMailboxes` instead of holding the tool-call queue. Keep it below your client's request timeout |
- **Multiple IMAP accounts (C2):** set `APPLE_MAIL_MCP_IMAP_ACCOUNTS` to a JSON array, e.g.
- `[{"account":"Work","user":"me@co.com","host":"imap.co.com","keychainService":"imap.co.com"}]`.
- Each entry accepts `account`, `user`, `host`, `port`, `password`, `keychainService`,
- `keychainAccount`. Calls route to the account matching their `account` argument (or the
- decoded `imap:` id), and each account keeps its own pooled connection.
- Non-implicit-TLS IMAP connections require STARTTLS and fail closed when the server
- does not offer a usable upgrade. `APPLE_MAIL_MCP_IMAP_ALLOW_PLAINTEXT=1` is a
- deliberate escape hatch for a trusted isolated server or test fixture; it disables
- the upgrade requirement and can expose credentials and message content. Keep the
- default unset.
- As with SMTP, the password is read from the macOS **Keychain** by default (use
- an app-specific password for Gmail/Workspace/iCloud), so no secret goes in
- config. Gmail label semantics: common names (`All Mail`, `Sent`, `Trash`,
- `Spam`, `Important`, …) map to their `[Gmail]/…` IMAP paths automatically.
- > Note: IMAP connections are pooled — one kept-alive connection per account is
- > reused across calls (verified with a NOOP, closed after `APPLE_MAIL_MCP_IMAP_IDLE_MS`
- > of inactivity), so there's no per-call connection overhead ([#50](https://github.com/sweetrb/apple-mail-mcp/issues/50)).
- >
- > **iCloud:** set `APPLE_MAIL_MCP_IMAP_HOST=imap.mail.me.com`, `APPLE_MAIL_MCP_IMAP_USER`
- > to your iCloud address, `APPLE_MAIL_MCP_IMAP_ACCOUNT` to the Mail account name
- > (e.g. `iCloud`), and use an **app-specific password** (from appleid.apple.com)
- > stored in the Keychain.
- ##### Connection footprint (playing nice with Gmail)
- IMAP connections are a shared, capped resource: **Gmail allows at most 15
- simultaneous IMAP connections per account**, and Apple Mail itself needs some of
- those slots. This server keeps its footprint small:
- - **One pooled connection per account**, reused across calls and **closed after
- ~30s idle** (tune with `APPLE_MAIL_MCP_IMAP_IDLE_MS`; `0` = never close). So a
- server that isn't actively serving IMAP calls holds **zero** connections.
- - **IMAP IDLE is opt-in** (`APPLE_MAIL_MCP_IMAP_IDLE=1`). When on, it adds **one
- persistent connection per account** (a long-lived watcher), on top of the
- pooled request connection — leave it off if you don't need push notifications.
- - **Connections are dropped on shutdown** — SIGINT/SIGTERM and stdin-EOF (the
- MCP client/parent going away). As of **v2.6.1** the server also **self-exits if
- it becomes orphaned** (parent force-quit/crashed → reparented to launchd),
- polling every 30s, so it can't linger holding sockets after its session is gone.
- The catch is **multiple concurrent instances**. A host like the Claude desktop
- app spawns a _separate_ set of MCP servers per open conversation (and respawns
- them after a crash), so the footprint is **per instance × accounts**. With IDLE
- off, an idle instance trends to 0 connections; with many _active_ conversations
- or IDLE on, the per-account total climbs toward Gmail's 15-connection cap and can
- starve Apple Mail of slots (→ intermittent "cannot connect"). If you hit that,
- close idle Claude conversations, keep `APPLE_MAIL_MCP_IMAP_IDLE` off unless you
- need push, and/or lower `APPLE_MAIL_MCP_IMAP_IDLE_MS`.
- ##### Configuration file (when the host strips `env`)
- Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed
- environment and ignore the `env` block in their server config, so there's no way
- to pass `APPLE_MAIL_MCP_*` settings through it. In that case, put them in a JSON
- file the host doesn't manage — `APPLE_MAIL_MCP_CONFIG_FILE`, or by default
- `~/Library/Application Support/apple-mail-mcp/config.json`:
- ```json
- {
- "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
- "APPLE_MAIL_MCP_IMAP_HOST": "imap.gmail.com",
- "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
- "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT": "you@gmail.com",
- "APPLE_MAIL_MCP_IMAP_IDLE": "1"
- }
- ```
- The server reads it at startup and merges values into the environment **without
- overriding** anything already set there (so an explicit `env` still wins). Store
- only non-secret config here — **passwords belong in the Keychain**, never in this
- file.
- ##### Push notifications (IMAP IDLE) — opt-in
- When `APPLE_MAIL_MCP_IMAP_IDLE=1`, the server opens a dedicated, long-lived
- connection to **each configured IMAP account** and watches its INBOX for new
- mail. On arrival it pushes two MCP notifications to the client (no polling by the
- client required):
- 1. **`notifications/message`** (logging) — a human-readable line, e.g.
- `New mail in "Work": 2 new message(s) (INBOX now 1843).`
- 2. **`notifications/resources/updated`** — for the affected account's resource
- `mail://mailboxes/{account}`, so a client subscribed to that resource knows to
- re-read it.
- This requires an IMAP account to be configured (single-account env or
- `APPLE_MAIL_MCP_IMAP_ACCOUNTS`); accounts that only use AppleScript aren't
- watched. Detection is **real-time** via the IMAP IDLE `EXISTS` event where the
- server pushes it, with an automatic **polling fallback** for servers that don't.
- Dropped connections reconnect with backoff, and the watchers shut down cleanly on
- `SIGINT`/`SIGTERM`.
- Enable it in your MCP client config alongside the IMAP settings:
- ```json
- {
- "mcpServers": {
- "apple-mail": {
- "command": "node",
- "args": ["/path/to/apple-mail-mcp/build/index.js"],
- "env": {
- "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
- "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
- "APPLE_MAIL_MCP_IMAP_IDLE": "1"
- }
- }
- }
- }
- ```
- > Note: this is most useful with clients that surface MCP logging messages or
- > subscribe to resource-update notifications. Clients that ignore notifications
- > are unaffected — the feature is opt-in and adds no behavior unless enabled.
- ---
- #### `send-serial-email`
- Send individual personalized emails to a list of recipients (mail merge). Each recipient receives their own email — recipients don't see each other. Supports `{{placeholder}}` tokens in both subject and body.
- | Parameter | Type | Required | Description |
- | ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
- | `recipients` | object[] | Yes | List of recipients, max 100 (see below) |
- | `subject` | string | Yes | Email subject — use `{{Key}}` for placeholders |
- | `body` | string | Yes | Email body — use `{{Key}}` for placeholders |
- | `account` | string | No | Mail.app account label (AppleScript), or an allowed email-form SMTP From override |
- | `transport` | string | No | `smtp` or `applescript` for the whole batch. If omitted, configured SMTP is used unless `account` is a Mail.app label. Explicit SMTP rejects a bare label, and a missing SMTP credential or unapproved sender stops the batch before anything is sent — never a fallback to Mail.app |
- | `delayMs` | number | No | Delay between sends in ms (default: 500, max 10000) |
- Each recipient object:
- | Field | Type | Required | Description |
- | ----------- | ------ | -------- | ------------------------------------------- |
- | `email` | string | Yes | Recipient email address |
- | `variables` | object | Yes | Key-value pairs for placeholder replacement |
- **Example:**
- ```json
- {
- "recipients": [
- { "email": "alice@example.com", "variables": { "Name": "Alice", "Company": "Acme" } },
- { "email": "bob@example.com", "variables": { "Name": "Bob", "Company": "Globex" } }
- ],
- "subject": "Hello {{Name}}!",
- "body": "Dear {{Name}},\n\nGreat to connect about {{Company}}.\n\nBest regards"
- }
- ```
- **Returns:** Per-recipient success/failure results with a summary count, plus the `transport` used for the batch.
- **⚠️ Safety:** Sends real mail immediately to every recipient and cannot be unsent. Confirm the recipient list, subject, and body with the user before calling.
- ---
- #### `create-draft`
- Save an email to Drafts without sending.
- | Parameter | Type | Required | Description |
- | ------------- | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
- | `to` | string[] | Yes | Recipient addresses |
- | `subject` | string | Yes | Email subject |
- | `body` | string | Yes | Email body (plain text) |
- | `cc` | string[] | No | CC recipients |
- | `bcc` | string[] | No | BCC recipients |
- | `account` | string | No | Account for draft. With `inReplyTo`/`references` it must name a configured IMAP account (label or login) |
- | `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments: absolute file paths inside the configured read roots and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each |
- | `inReplyTo` | string | No | (2.20.0) Parent `Message-ID` token, e.g. `"<abc@mail.example.com>"` — makes this a **threaded draft** (see below) |
- | `references` | string[] | No | (2.20.0) `References` chain, oldest first; defaults to `[inReplyTo]` |
- **Returns:** Confirmation that draft was created, with `transport` (`applescript`, or `imap` for a threaded draft).
- **Threaded drafts (2.20.0, #267):** Mail.app's `outgoing message` has no header property,
- so a draft with `inReplyTo`/`references` cannot go through AppleScript. Instead the
- server composes it with the same MIME builder as the SMTP send (attachments included) and
- files it over IMAP into the account's Drafts mailbox (SPECIAL-USE `\Drafts`), flagged
- `\Draft`. The account is `account` when given (it must be a configured IMAP account —
- pass the exact `accountLabel` or login from `list-accounts`/your `APPLE_MAIL_MCP_IMAP_*`
- config, e.g. `"user@icloud.com"`; a generic provider name like `"iCloud"` is not a
- recognized alias and is refused);
- otherwise the IMAP account whose login is the SMTP identity, else the only configured
- IMAP account. When none qualifies — IMAP unconfigured, an unknown `account`, or several
- accounts and no way to choose — the call **fails and files nothing**; it never falls back
- to an unthreaded Mail.app draft. The result names the Drafts `mailbox`, the `account` and
- the draft's `messageId`. Without threading headers, `create-draft` is unchanged
- (AppleScript).
- #### `update-saved-draft`
- Preview or edit an existing **stored** draft (#372). Requires a configured IMAP
- account and exactly one selectable SPECIAL-USE `\Drafts` mailbox; there is no
- AppleScript or SMTP fallback. The message itself must carry `\Draft` and must
- not be marked `\Deleted`. Editing requires UIDPLUS, so removal uses **UID
- EXPUNGE**, never a global EXPUNGE that could remove unrelated messages.
- | Parameter | Type | Required | Description |
- | --------------------- | ------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- |
- | `draftId` | string | Yes | Fresh `imap:` ID from `list-messages` on Drafts. Numeric IDs are refused. |
- | `dryRun` | boolean | No | Defaults to `true`: only read and preview, including proposed changes when supplied. |
- | `approvedSha256` | string | For an update | `preview.sha256` of the current stored source. |
- | `approvedUidValidity` | string | For an update | `preview.uidValidity` of the current source mailbox. The UID is encoded in `draftId` and also returned in the preview. |
- | `changes` | object | For an update | Partial patch; omitted fields remain unchanged. |
- `changes` accepts `subject`, `to`, `cc`, `bcc`, `body`, `htmlBody`,
- `addAttachments` and `removeAttachments`. An explicit `[]` clears a recipient
- field. `body` replaces an existing text/plain part and `htmlBody` an existing
- text/html part. When both alternatives exist, **supply both** to avoid leaving
- a stale rendering. Missing or ambiguous body alternatives, signed/encrypted
- content, malformed MIME and unreadable bodies are refused before writing.
- Unchanged envelope/threading headers, native signatures and encoded MIME parts
- are retained. A changed body is the complete replacement for that body,
- including any signature it contains. `addAttachments` uses the same allowlisted
- file paths / inline `{filename, contentBase64}` inputs as `create-draft` (up to
- 20 additions). `removeAttachments` takes the current preview's **partId** values,
- so duplicate filenames are not ambiguous; embedded CID images cannot be removed.
- The source and resulting stored MIME are each capped at 25 MiB, and each body
- representation in the preview at 100,000 characters.
- **Workflow:** list Drafts, call with `dryRun: true`, review `preview` and any
- `proposed` changes with the user, then call with `dryRun: false`, the same
- `draftId`, the current preview's approval tokens and the approved `changes`.
- The tokens identify the **source**; a proposed preview is not yet a stored
- revision. A changed UIDVALIDITY or source SHA-256 refuses the edit. The format
- matches the UIDVALIDITY/UID/MIME-SHA-256 revision used in the proposed
- [`send-saved-draft` work (#241)](https://github.com/sweetrb/apple-mail-mcp/pull/241).
- That send feature is separate and is not introduced here.
- **Returns:** `status: preview`, `updated` or `unchanged`, `sourceDraftId`,
- `draftId`, the stored `preview` (From, To/Cc/Bcc, subject, bodies, attachment
- metadata and revision), and optionally `proposed`. On update, the replacement
- is APPENDed and its UID and stored bytes verified **before** the old UID is
- removed. Use the **new** `draftId` and revision afterwards.
- Failures are separate outcomes: `append_failed` leaves the source untouched;
- `append_unknown` preserves it and reports any known replacement ID;
- `cleanup_failed` reports the saved replacement preview and both IDs. Inspect
- Drafts before retrying: neither APPEND nor cleanup is retried automatically.
- `sourceRemoved` is true only after confirmation; it is omitted when a cleanup
- connection failure leaves the outcome uncertain.
- IMAP does not provide an atomic cross-client compare-and-replace. The source is
- checked again before APPEND and cleanup; a concurrently created UID is never
- deleted, but a racing edit or connection failure may leave multiple versions.
- **⚠️ Safety:** This overwrites a draft only and never sends mail. Confirm the
- patch with the user before `dryRun: false`. A successful edit removes the old
- revision after confirming its replacement; a cleanup failure is not a reason
- to repeat the already saved edit.
- #### `get-thread`
- Group a conversation by normalized subject (across the AppleScript or IMAP backend).
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ------------------------------------------------------ |
- | `id` | string | Yes | A message ID in the conversation (numeric or `imap:…`) |
- | `account` | string | No | Account to search (omit to search all) |
- | `mailbox` | string | No | Mailbox to search (omit to search all) |
- | `limit` | number | No | Max messages in the thread (default 50) |
- **Returns:** The conversation's messages, oldest-first. A thread usually spans
- mailboxes (INBOX and Sent), so each text line ends with where that message is,
- unless the call named one mailbox of one account.
- #### `fetch-attachment`
- Return an attachment's bytes as base64 (the read counterpart to inline-base64 send).
- | Parameter | Type | Required | Description |
- | ---------------- | ------ | -------- | --------------------------------------------- |
- | `id` | string | Yes | Message ID (numeric or `imap:…`) |
- | `attachmentName` | string | Yes | Attachment filename (from `list-attachments`) |
- **Returns:** The attachment bytes, base64-encoded (also in `structuredContent.contentBase64`).
- **Inline limit:** 3 MiB of decoded bytes on either backend. The result keeps
- both base64 representations; its total serialized size is also bounded to
- leave room under the MCP SDK's default 10 MiB stdio read buffer. Larger or
- unverifiable inline results return an error directing you to `save-attachment`.
- IMAP saves retain their separate 25 MiB limit and the existing allowed roots.
- ---
- #### `resolve-message-id`
- Map `imap:` message IDs to their numeric Mail.app IDs, via each message's RFC 5322 `Message-ID` (the join key both backends share). Needed for the AppleScript reply/forward path; direct SMTP replies and forwards read `imap:` IDs without numeric conversion. Numeric IDs pass through unchanged.
- | Parameter | Type | Required | Description |
- | --------- | -------- | -------- | ------------------------------------------- |
- | `ids` | string[] | Yes | 1–100 message IDs, each numeric or `imap:…` |
- **Returns:** For each input ID, its `numericId` (or `null` when it can't be resolved) and the `messageId` used, plus `count` and `resolvedCount`. The lookup scopes to the message's account and checks its INBOX first, to avoid scanning a large All Mail/Archive mailbox.
- > **You do not need this for flag colors (v2.10.0+).** Colors used to require the numeric-ID path, and older docs and tool descriptions said so. `flag-message` and `batch-flag-messages` now write the color over IMAP directly, as Mail.app's `$MailFlagBit0/1/2` keywords, so a smart mailbox keyed on flag color matches an IMAP-flagged message. Resolving IDs just to apply a color reintroduces the AppleScript/TCC dependency 2.10.0 removed. Flag, move, mark, and delete all accept `imap:` IDs as-is.
- ---
- #### `reply-to-message`
- Reply to an existing message.
- | Parameter | Type | Required | Description |
- | ------------- | --------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `id` | string | Yes | Message ID to reply to |
- | `account` | string | No | Source account for a numeric ID; provide together with `mailbox` |
- | `mailbox` | string | No | Source mailbox path for a numeric ID; provide together with `account` |
- | `body` | string | Yes | Reply body (plain text; HTML tags such as `<br>` are not rendered) |
- | `replyAll` | boolean | No | Reply to all recipients (default: false) |
- | `send` | boolean | No | Send immediately (default: true, false = save as draft) |
- | `transport` | string | No | `smtp` or `applescript`; omitted prefers configured SMTP when sending. Drafts use AppleScript. |
- | `composition` | string | No | `native-editor` uses Mail's visible editor and preserves its native reply history |
- | `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 attachments, same rules as `send-email`: absolute file paths inside the configured read roots and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each |
- **Example - Reply to sender only:**
- ```json
- {
- "id": "12345",
- "body": "Thanks for the update!"
- }
- ```
- **Example - Reply all, save as draft:**
- ```json
- {
- "id": "12345",
- "account": "Work",
- "mailbox": "INBOX",
- "body": "I'll review this and get back to everyone.",
- "replyAll": true,
- "send": false
- }
- ```
- **Example - Reply all with an attachment (2.20.0):**
- ```json
- {
- "id": "imap:eyJhIjoiV29yayIsInAiOiJJTkJPWCIsInUiOjQyfQ",
- "body": "Here is the PDF you asked for.",
- "replyAll": true,
- "attachments": [
- "/Users/me/Documents/quote.pdf",
- { "filename": "notes.txt", "contentBase64": "SGVsbG8K" }
- ]
- }
- ```
- **Attachments (2.20.0, #267):** same schema, limits (20 items, 25 MiB each) and read
- roots as `send-email`, validated before the original is fetched — an out-of-roots path
- fails with exactly `send-email`'s error. Recipients, threading headers and the quote are
- identical to the same call without attachments. Over SMTP the files ride the same
- nodemailer path `send-email` uses, so the Sent-folder copy (`sentCopy`) carries them too.
- On the AppleScript transport they are added with `make new attachment` **after** the
- reply content is set and before `save`/`send` (inline items are written to `0600` temp
- files and removed afterwards), so a `send: false` draft contains both the attachments and
- the quoted original. `make new attachment` returns before Mail has loaded the file, so the
- script waits until Mail counts every file (bounded at 15 s) before saving or sending
- (2.20.16, #293; the same wait applies to `send-email` and `create-draft`). Results report
- `attachmentCount`.
- **Delivery:** `imap:` IDs are read directly from their encoded account, mailbox, and UID. Numeric IDs are read through Mail.app. With SMTP configured, replies use clean MIME with the original `Message-ID` in `In-Reply-To` and the full `References` chain. Only the original plain-text body is quoted; the new text is not. Pass `transport: "smtp"` to require this path, or `transport: "applescript"` to use Mail.app explicitly.
- **Numeric source scope:** Pass `account` and `mailbox` together using the account
- and full mailbox path from the original search or listing. Both the original read
- and the Mail reply target use that scope; a missing or ambiguous account, mailbox,
- or message stops the operation instead of scanning elsewhere. For Mail.app
- composition, the original must have a usable `Message-ID`, which is checked again
- against the selected message before the composer is created. An `imap:` ID already
- encodes its source: omit both fields for that form. Supplying only one field, or
- supplying either with an `imap:` ID, returns an error. Without explicit scope,
- numeric IDs retain the remembered-location and bounded-scan strategy described
- under [numeric IDs](#get-message), but an ambiguous remembered account or mailbox
- now stops instead of falling back to a scan. For numeric SMTP replies and forwards,
- the configured From mailbox must belong to the source's enabled Mail account,
- whether the scope was supplied or resolved. A matching SMTP login or an entry in
- `APPLE_MAIL_MCP_SMTP_ALLOWED_FROM` does not authorize a different configured From.
- A display name around one valid From mailbox is supported. A local "On My Mac"
- source has no Mail account whose SMTP From can be verified, so SMTP stops rather
- than selecting an identity.
- Unscoped numeric SMTP requests read the MIME source and location together. The
- quotation comes from that same MIME source, not a second plaintext lookup. If a
- bounded scan cannot establish a unique source because it skipped or could not
- reach a mailbox, provide the original account and full mailbox path explicitly.
- An unreadable MIME body stops the request; no alternative sender or transport
- is chosen.
- **AppleScript transport quoting (v2.19.12):** every draft (`send: false`) and any send that falls back to AppleScript (SMTP not configured) also gets the original quoted — an "On \<date\>, \<sender\> wrote:" attribution line followed by the `> `-prefixed original body, built the same way as the SMTP path. Mail's own `reply`/`forward` AppleScript commands generate this quote internally but expose no way to read it back, so it's built here instead of relying on Mail's (unreadable) copy. Unlike SMTP, this path has no sending-identity restriction — it's read-only source lookup, not sending.
- **Sender on the AppleScript transport (2.20.15, #294):** Mail's `reply`/`forward` commands set no sender, so Mail would answer from its default sending account. The reply or forward is now sent from the account the original sits in: the original's to/cc address that belongs to that account — or, for a message you sent, its own From address. When none of its to/cc addresses belongs to that account (a message another account forwarded in), the to/cc address that belongs to any other enabled account is used; otherwise the account's first address. The sender is read back before saving or sending; a mismatch deletes the compose and returns an error. A message in an "On My Mac" mailbox has no account, so its recipients are matched against every enabled account and, with no match, the sender is left to Mail. The same applies to `forward-message`.
- **Failure behavior:** SMTP and AppleScript-content replies stop if the original source or plain-text body cannot be read, rather than silently dropping the quote. Numeric-message replies can recover text from raw MIME when Mail.app's decoded content is unavailable. A genuinely empty original body is allowed; an unreadable body is not. Native-editor mode preserves Mail's own reply history and requires the original source to be readable, but does not reconstruct its plain-text quote. Once SMTP is selected, a missing password, unreadable source, missing reply address or `Message-ID`, or known SMTP refusal returns an error. Partial acceptance and uncertain submission use the [structured SMTP outcomes](#smtp-submission-outcomes) above instead of implying that nothing was sent. The tool does not silently switch to AppleScript or create an unthreaded new message. With SMTP unconfigured and transport omitted, AppleScript remains available. `send: false` saves a Mail.app draft; combining it with `transport: "smtp"` is rejected before composing.
- The direct IMAP source read is bounded to 25 MiB, including MIME attachments. Its account login must match the SMTP login, configured From, or an explicitly configured `APPLE_MAIL_MCP_SMTP_ALLOWED_FROM` identity; otherwise the call fails rather than sending from an unrelated account. The SMTP configuration still represents a single sending identity, not a per-account SMTP registry.
- Success includes `transport`, `attachmentCount` and, for SMTP when returned by the server, the new `messageId`. Over SMTP a best-effort Sent-folder copy is filed over IMAP exactly as for `send-email` (`sentCopy` / `sentCopyError`, see [SMTP transport](#smtp-transport)). `send-email` is for **new conversations**: adding `Re:` to its subject does not add threading headers. Use this reply tool with the original id instead.
- **⚠️ Safety:** With the default `send: true`, sends real mail immediately and cannot be unsent. Confirm the recipients, subject, and body with the user before calling (or pass `send: false` to save a draft for review).
- ---
- #### `forward-message`
- Forward a message to new recipients.
- | Parameter | Type | Required | Description |
- | ------------- | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `id` | string | Yes | Message ID to forward |
- | `account` | string | No | Source account for a numeric ID; provide together with `mailbox` |
- | `mailbox` | string | No | Source mailbox path for a numeric ID; provide together with `account` |
- | `to` | string[] | Yes | Recipients to forward to |
- | `body` | string | No | Message to prepend (plain text) |
- | `send` | boolean | No | Send immediately (default: true, false = save as draft) |
- | `transport` | string | No | `smtp` or `applescript`; omitted prefers configured SMTP when sending. Drafts use AppleScript. |
- | `composition` | string | No | `native-editor` uses Mail's visible editor and preserves its native forward history |
- | `attachments` | (string \| {filename, contentBase64})[] | No | Up to 20 additional attachments, same rules as `send-email`: absolute file paths inside the configured read roots and/or inline `{filename, contentBase64}` objects up to 25 MiB decoded each |
- **Delivery:** uses the same source lookup, transport selection, 25 MiB source limit, account-identity check, and failure behavior as `reply-to-message`. A forward deliberately starts a new conversation, so it has no `In-Reply-To` or `References` headers. The existing plain-text forwarding behavior is unchanged: original attachments are not reattached. See [SMTP transport](#smtp-transport). On the AppleScript transport, a `body` is merged with the forwarded-message header block and original text the same way the SMTP path builds it (see `reply-to-message`'s AppleScript transport quoting note); with no `body`, Mail's own forward content is left untouched — unless `attachments` are given, in which case the forwarded-message block is built the same way so Mail has a paragraph to anchor the new files after.
- **Attachments (2.20.0, #267):** `attachments` adds new files to the forward, with or without a prepended `body`, under the same rules, validation and per-transport mechanics as `reply-to-message`'s attachments. They are independent of the original's attachments (which the SMTP path still does not reattach).
- SMTP forwarding requires a readable plain-text original. Scoped AppleScript-content forwards that add a body or attachments also stop if the original text is unreadable; without added content, Mail retains its own forward history. Native-editor mode preserves Mail's native history. An intentionally empty plain-text message is still valid.
- **⚠️ Safety:** With the default `send: true`, sends real mail immediately and cannot be unsent. Confirm the recipients, subject, and body with the user before calling (or pass `send: false` to save a draft for review).
- ---
- #### `mark-as-read` / `mark-as-unread`
- Change read status of a message.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------- |
- | `id` | string | Yes | Message ID |
- ---
- #### `flag-message` / `unflag-message`
- Flag or unflag a message. `flag-message` optionally takes a flag **color**; `unflag-message` removes the flag entirely (which also clears any color).
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
- | `id` | string | Yes | Message ID |
- | `color` | string | No | (`flag-message` only) Flag color: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `gray` (`grey` accepted). Omit for Mail's default flag. |
- **Flag colors** are an Apple Mail feature — the message's `flag index` (0 red, 1 orange, 2 yellow, 3 green, 4 blue, 5 purple, 6 gray), which is the property a Mail smart mailbox can match on. **The color is applied on both routes** (since 2.10.0): AppleScript sets the flag index directly, and for an **IMAP-routed** id (`imap:…`) the color is written as Mail.app's `$MailFlagBit0/1/2` keywords — a 3-bit field holding the same palette index. `\Flagged` on its own really is colorless, but those keywords ride alongside it in an ordinary `UID STORE`, so a smart mailbox keyed on flag color matches an IMAP-flagged message too. You do **not** need to resolve to a numeric id just to color a flag.
- To **read** a color back, or **find** messages by color, use
- [`search-messages`](#search-messages) (or [`list-messages`](#list-messages) for
- read-back only) — both routes now return `flagColor` (the palette name) on
- every flagged-with-a-color row, and `search-messages` takes a `flagColor`
- filter using this same palette (#286). The IMAP route additionally still
- carries the raw 0-6 `flagColorIndex` for back-compat.
- ---
- #### `delete-message`
- Delete a message (move to trash).
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------- |
- | `id` | string | Yes | Message ID |
- `structuredContent` carries `countDelta` — what the delete actually did to the
- source mailbox. See [Auditing destructive operations](#auditing-destructive-operations).
- **⚠️ Safety:** Destructive. Requires explicit user confirmation; search/list first to confirm the message id.
- ---
- #### `move-message`
- Move a message to a different mailbox.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
- | `id` | string | Yes | Message ID |
- | `mailbox` | string | Yes | Destination mailbox — full path (`Work/Archive`) or a leaf name that is unique on the account |
- | `account` | string | No | Account containing mailbox |
- A destination is matched first as a full path, then as a leaf name. If a leaf
- name matches **more than one** mailbox (e.g. `Archive` under both `Work` and
- `Thornlands`), the move is refused with an error naming every candidate — pass
- the full path. The same applies to `batch-move-messages`, `delete-mailbox` and
- `rename-mailbox`.
- `structuredContent` carries `countDelta` — what the move actually did to the
- **source** mailbox. See [Auditing destructive operations](#auditing-destructive-operations).
- ---
- #### `list-attachments`
- List attachments on a message.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------- |
- | `id` | string | Yes | Message ID |
- **Returns:** List of attachments with name, MIME type, and `size` — the **decoded** byte count,
- i.e. what `fetch-attachment` returns.
- **A numeric `id` resolves the same way the read tools resolve one** (2.20.21): the mailbox the id
- was listed from when that is known, else a bounded cross-mailbox scan that skips very large
- mailboxes and stops at its time budget. An id that several mailboxes hold is **refused**, with the
- candidates named, rather than answered for whichever copy came first — so list or search the
- mailbox you mean immediately before calling this. `imap:…` ids are never ambiguous.
- **Sizes over IMAP.** `BODYSTRUCTURE` reports a part's size in its transfer encoding, so a
- base64 attachment's raw figure is ~4/3 of the file. `list-attachments` converts it: a
- `Content-Disposition` `size=` parameter wins when present; 7bit/8bit/binary parts are exact
- as reported; base64 parts are measured exactly from a short tail of each part (padding and
- line wrap), fetched in one batched `FETCH` for the whole message; quoted-printable parts up
- to 64 KiB are fetched and counted exactly. If a part can't be measured (the probe fails, the
- wrap is irregular, or a quoted-printable part is larger), the size is an estimate within a
- few bytes for base64 — an upper bound for quoted-printable — and the entry carries
- `sizeApproximate: true`. `fetch-attachment` always reports the exact `bytes`.
- ---
- #### `save-attachment`
- Save a message attachment to disk.
- The destination must not already exist: `save-attachment` fails closed instead
- of overwriting an existing file. AppleScript and MIME fallback paths stage the
- bytes privately, commit with an exclusive create, and leave the saved file
- owner-readable/writable (`0600`).
- **A numeric `id` resolves the same way the read tools resolve one** (2.20.21): the mailbox the id
- was listed from when that is known, else the bounded cross-mailbox scan. An id that several
- mailboxes hold **saves nothing** rather than writing some other message's attachment under the
- name you asked for.
- | Parameter | Type | Required | Description |
- | ---------------- | ------ | -------- | -------------------------- |
- | `id` | string | Yes | Message ID |
- | `attachmentName` | string | Yes | Filename of the attachment |
- | `savePath` | string | Yes | Directory to save to |
- ---
- ### Batch Operations
- All batch operations accept an array of message IDs (max 100 per batch) and return per-item success/failure results.
- **Numeric IDs are scoped to the mailbox you listed them from.** Mail.app numbers messages per
- mailbox, so on a label store (Gmail, iCloud) one message answers to the same id in `INBOX`,
- `Important` and `All Mail` at once — and deleting the `All Mail` copy is not the same operation as
- deleting the `INBOX` copy. Each id is therefore bound to the mailbox it was listed/searched from and
- the operation is applied only there, so **list or search the mailbox immediately before acting on
- it**. An id the server hasn't seen listed is accepted only when exactly one mailbox holds it;
- if several do, that id fails with the candidate mailboxes named instead of being applied to an
- arbitrary copy. `imap:…` ids carry their own account + mailbox + UID and are never ambiguous.
- **Say which mailbox with `sourceMailbox` / `sourceAccount`.** The binding above is remembered
- per running server, so a client that reconnects, restarts, or replays a saved list of ids has
- nothing recorded and every id takes the slower whole-tree path — where, on a label store, it is
- likely to be refused as ambiguous. Passing the source mailbox explicitly is the reliable way to
- stay scoped, and it overrides the remembered location. These parameters name where the ids **came
- from**; for `batch-move-messages` that is distinct from `mailbox`, the destination.
- `sourceMailbox` and `sourceAccount` are an atomic scope pair: provide **both** for numeric ids.
- The server never fills in a missing account from mutable default-send state, because the same
- mailbox name can exist in more than one account and numeric ids are only unique within an account
- and mailbox. A whitespace-only source field is rejected. `sourceAccount` by itself pins nothing,
- since the mailbox is what an id is scoped to; `imap:…` ids ignore both fields because they carry
- their own account, mailbox, and UID identity.
- **A repeated id is one message.** `ids` is treated as a set: a duplicate names the same message,
- so it is operated on once, and the batch returns **one result per distinct id**. `success` is
- therefore a count of messages, not of list positions.
- #### `batch-delete-messages`
- | Parameter | Type | Required | Description |
- | --------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
- | `ids` | string[] | Yes | Message IDs to delete (max 100) |
- | `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
- | `sourceAccount` | string | No | Account the numeric ids were listed from. Required when `sourceMailbox` is supplied; on its own it pins nothing. |
- `structuredContent` carries `countDelta` — what the batch actually did to each
- source mailbox. See [Auditing destructive operations](#auditing-destructive-operations).
- **⚠️ Safety:** Destructive. Requires explicit user confirmation; search/list first to confirm the message ids.
- #### `batch-move-messages`
- | Parameter | Type | Required | Description |
- | --------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
- | `ids` | string[] | Yes | Message IDs to move (max 100) |
- | `mailbox` | string | Yes | Destination mailbox |
- | `account` | string | No | Account containing mailbox |
- | `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
- | `sourceAccount` | string | No | Account the numeric ids were listed from. Required when `sourceMailbox` is supplied; on its own it pins nothing. |
- `structuredContent` carries `countDelta` — what the batch actually did to each
- **source** mailbox. See [Auditing destructive operations](#auditing-destructive-operations).
- #### `batch-mark-as-read` / `batch-mark-as-unread`
- | Parameter | Type | Required | Description |
- | --------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
- | `ids` | string[] | Yes | Message IDs (max 100) |
- | `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
- | `sourceAccount` | string | No | Account the numeric ids were listed from. Required when `sourceMailbox` is supplied; on its own it pins nothing. |
- #### `batch-flag-messages` / `batch-unflag-messages`
- | Parameter | Type | Required | Description |
- | --------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `ids` | string[] | Yes | Message IDs (max 100) |
- | `color` | string | No | (`batch-flag-messages` only) Flag color — see [`flag-message`](#flag-message--unflag-message). Applied on both routes, so a mixed batch of numeric and `imap:` ids all end up colored. |
- | `sourceMailbox` | string | No | Mailbox the **numeric** ids were listed from — pins them to it. Ignored for `imap:` ids. |
- | `sourceAccount` | string | No | Account the numeric ids were listed from. Required when `sourceMailbox` is supplied; on its own it pins nothing. |
- ---
- ### Mailbox Operations
- #### `list-mailboxes`
- List all mailboxes for an account.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ---------------------------------------------------------- |
- | `account` | string | No | Account to list from, or `"On My Mac"` for the local store |
- **Returns:** List of mailbox **paths** (account-relative, e.g. `Archive/Inbox` for
- a nested mailbox — a top-level `Inbox` stays `Inbox`) with message and unread
- counts. A source that could not be read is **named** (`partial: true` +
- `failedAccounts`) rather than dropped, and a listing Mail refused outright
- returns an error naming the accounts that do exist — never an empty list.
- **Nested mailboxes and Gmail labels.** Every `mailbox` parameter across this
- server (search-messages, list-messages, get-unread-count, move-message,
- delete-mailbox, rename-mailbox, create-rule's `moveTo`) accepts either the full
- path or a leaf name that is unique across the account — the same rule
- move-message has always used. A leaf name that matches more than one mailbox
- (e.g. a top-level `Inbox` and an `Archive/Inbox` on an Exchange account) is
- refused rather than guessed; pass the full path to disambiguate. This also
- means Gmail's nested special mailboxes now report their real path, e.g.
- `[Gmail]/All Mail` rather than `All Mail` — a visible change from before 2.17.0.
- Matching ignores letter case **and Unicode normalization form**: a typed
- precomposed `México` (NFC) finds a mailbox the server stores decomposed (NFD —
- common for folders created on a Mac, and what iCloud keeps), and the server's
- own stored spelling is what gets selected. Two mailboxes whose names differ
- _only_ in case or normalization look identical in any listing, so a name that
- matches both is refused with an error saying so — rename one of them. For the
- same reason `create-mailbox` treats a normalization-equivalent existing name as
- already existing, and `rename-mailbox` refuses to create such a twin.
- **Messages awaiting expunge are not listed.** On IMAP accounts, search,
- list, thread and mail-stats queries only match messages _not_ flagged
- `\Deleted` (IMAP `UNDELETED`). iCloud keeps flagged-but-never-expunged
- messages out of its message counts yet still returns them from `UID SEARCH`,
- which made a filter-less `list-messages` fail on such a mailbox before 2.19.16.
- **Very large IMAP mailboxes are read newest-first in bounded windows**
- ([#256](https://github.com/sweetrb/apple-mail-mcp/issues/256)). Above 10,000
- messages, a filter-less `list-messages`/`search-messages` pages by message
- sequence number: page `offset` of `limit` is sequence numbers
- `N-offset-limit+1 .. N-offset`, so it fetches UIDs and flags for that range
- alone (plus a small margin; `\Deleted` ones are skipped and the page topped up
- from below) and full rows for the page. The cost is the page, not the offset:
- `limit: 1` at offset 790,000 of a 793,614-message mailbox is one ~33-message
- `FETCH`, not a whole-mailbox `SEARCH` or a walk over every skipped message.
- Offsets count sequence positions. iCloud keeps messages awaiting expunge out of
- the sequence space, so there they are exact; on a server that keeps them in it,
- a page shifts by the number of such messages above it (they are never
- returned).
- A filtered search there runs the same criteria over newest-first sequence
- windows (5,000 messages, growing to 50,000) and stops once the page is full;
- the reported total then reads `at least N` unless the walk reached the bottom
- of the mailbox. A filtered search's deep `offset` has no such shortcut — which
- messages match is only known by searching the skipped windows — so its cost
- still grows with the offset (in 50,000-message `SEARCH` windows); narrow it
- with `dateTo` instead. A `SEARCH` or `FETCH` that fails names the mailbox, its size and
- the server's own reason (or a likely timeout) instead of reporting "no
- messages".
- **Mail's local "On My Mac" mailboxes** are not children of any account — they
- hang off the application — so they are reported under the synthetic account label
- **`On My Mac`**. An unscoped call includes them (listed last); `account="On My
- Mac"` lists only them. `on my computer`, `local` and `local folders` are accepted
- as aliases.
- They deliberately do **not** appear in `list-accounts`, which reports real
- accounts only: the local store is a store, not an account. Nothing selects it
- implicitly — omitting `account` still resolves to a real account for every other
- tool.
- The mail inside them is reachable too: `list-messages` and `search-messages`
- accept `account="On My Mac"`, and `get-message` resolves an id that lives only in
- a local mailbox. An id present **both** in an account mailbox and locally is
- reported as ambiguous rather than silently resolving to the account copy.
- ---
- #### `get-unread-count`
- Get unread message count.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | --------------------------------------------------- |
- | `mailbox` | string | No | Mailbox to check (omit for **INBOX**) |
- | `account` | string | No | Account to check (omit to sum each account's INBOX) |
- **Returns:** The unread count for the requested scope.
- > Omitting `mailbox` counts **INBOX**, not a cross-mailbox total. This changed in 2.8.15: summing every mailbox was slow and wrong on Gmail, where one message appears in INBOX, All Mail and every label it carries. For account-wide totals use [`get-mail-stats`](#get-mail-stats).
- ---
- #### `create-mailbox`
- Create a new mailbox.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | -------------------- |
- | `name` | string | Yes | Mailbox name |
- | `account` | string | No | Account to create in |
- ---
- #### `delete-mailbox`
- Delete a mailbox.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | -------------------------- |
- | `name` | string | Yes | Mailbox name |
- | `account` | string | No | Account containing mailbox |
- **⚠️ Safety:** Destructive — deletes the mailbox and its contents. Requires explicit user confirmation; list mailboxes first to confirm the name.
- ---
- #### `rename-mailbox`
- Rename a mailbox (creates new, moves messages, deletes old).
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | -------------------------- |
- | `oldName` | string | Yes | Current mailbox name |
- | `newName` | string | Yes | New mailbox name |
- | `account` | string | No | Account containing mailbox |
- ---
- ### Smart Mailbox Operations (intelligente Postfächer)
- > **Requires Full Disk Access.** These tools read and write `~/Library/Mail/V*/MailData/SyncedSmartMailboxes.plist`, which is TCC-protected. Without Full Disk Access for the server's Node runtime the read simply finds nothing, and the tools report "no smart mailboxes" or "launch Mail at least once" rather than a permission error — see [Node runtime & TCC permissions](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md).
- Smart mailboxes are Apple Mail's **criteria-based virtual views** — not real folders, so no messages are moved. AppleScript's `smart mailbox` / `intelligentes Postfach` terms don't compile reliably on localized (e.g. German) macOS, so these tools read and edit `~/Library/Mail/V*/MailData/SyncedSmartMailboxes.plist` directly.
- **How writes stay safe:** creating or deleting a smart mailbox first backs the plist up to `SyncedSmartMailboxes.plist.bak`, edits a temp copy with `plutil`/`PlistBuddy`, validates it with `plutil -lint`, and only then atomically renames it into place. Your **existing** smart mailboxes — including any with date/data criteria — are never rewritten, only the single target entry is added or removed. These tools do **not** quit or restart Mail: **quit Mail first** for reliable results, since a running Mail may not show a new smart mailbox until it's relaunched and can overwrite plist edits it didn't make.
- #### `list-smart-mailboxes`
- List existing smart mailboxes.
- **Parameters:** None
- **Returns:** List of smart mailbox names + criteria summary.
- ---
- #### `create-smart-mailbox`
- Create a smart mailbox with a simple contains rule.
- | Parameter | Type | Required | Description |
- | ----------------- | ------ | -------- | ------------------------------ |
- | `name` | string | Yes | Name for the smart mailbox |
- | `fromContains` | string | No | Match if From contains this |
- | `subjectContains` | string | No | Match if Subject contains this |
- | `bodyContains` | string | No | Match if Body contains this |
- Provide at least one of the three `*Contains` fields.
- **⚠️ Safety:** edits `SyncedSmartMailboxes.plist` (backed up + atomic, existing smart mailboxes preserved). Quit Mail first for reliable results; the new smart mailbox appears the next time Mail launches.
- ---
- #### `delete-smart-mailbox`
- Delete a smart mailbox by name.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ------------------ |
- | `name` | string | Yes | Smart mailbox name |
- **⚠️ Safety:** destructive — removes the smart mailbox from `SyncedSmartMailboxes.plist` (backed up + atomic; every other smart mailbox is preserved). Not undoable in-app. Confirm the exact name with `list-smart-mailboxes` first, and quit Mail first for reliable results.
- ---
- #### `create-newsletter-smart-mailboxes`
- High-level tool: scan recent messages in your INBOXes, detect likely newsletters (volume + signals like List-Unsubscribe, noreply, repetitive subjects), and create smart mailboxes for them (names prefixed "NL: ...").
- | Parameter | Type | Required | Description |
- | ---------- | ------- | -------- | ------------------------------------------ |
- | `dryRun` | boolean | No | Default true — only propose, do not create |
- | `minCount` | number | No | Min messages from a sender (default 3) |
- | `days` | number | No | Lookback window in days (default 90) |
- Defaults to a **safe dry run** that only proposes. Pass `dryRun: false` to actually create the smart mailboxes for newsletters cluttering your Inbox.
- **⚠️ Safety:** with `dryRun: false` this edits `SyncedSmartMailboxes.plist` (backed up + atomic, existing entries preserved) and can create many smart mailboxes at once — review a dry run first. Scans up to ~400 recent messages per inbox via AppleScript, which can be slow on large mailboxes.
- ---
- ### Account Operations
- #### `list-accounts`
- List all configured Mail accounts.
- **Parameters:** None
- **Returns:** List of account names and email addresses.
- #### `get-account-settings`
- Read the settings of one account: full name, email addresses, enabled, server and port, whether deleted mail goes to the Trash, when Trash/Junk/Sent are emptied, which IMAP folders are kept on the server, and the outgoing (SMTP) server.
- **Parameters:** `account` (name or email address)
- **Returns:** `{ account, settings }`. The password is never read or returned.
- #### `set-account-settings`
- Change settings of one account that cannot lock it out or redirect its mail.
- **Parameters:** `account`, and at least one of `enabled`, `fullName`, `includeWhenGettingNewMail`, `moveDeletedMessagesToTrash`, `emptyTrashOnQuit`, `emptyJunkOnQuit`, `emptySentOnQuit`, `storeDraftsOnServer`, `storeJunkOnServer`, `storeSentOnServer`, `storeDeletedOnServer`, `compactMailboxesWhenClosing`.
- **Returns:** the settings read back, or the settings Mail refused. Servers, ports, user names, passwords and the account's email addresses are read-only here. Allowed in `no_send` mode, not in `read_only`.
- ---
- ### Rules
- #### `list-rules`
- List all mail rules.
- **Parameters:** None
- **Returns:** List of rule names and enabled status.
- ---
- #### `enable-rule` / `disable-rule`
- Enable or disable a mail rule.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------- |
- | `name` | string | Yes | Rule name |
- ---
- #### `create-rule`
- Create a Mail rule with one or more conditions and actions.
- | Parameter | Type | Required | Description |
- | ------------ | -------- | -------- | ------------------------------------------------------------- |
- | `name` | string | Yes | Rule name (must be unique) |
- | `conditions` | object[] | Yes | One or more `{field, operator, value}` (see below) |
- | `actions` | object | Yes | At least one of `markRead`, `markFlagged`, `delete`, `moveTo` |
- | `matchAll` | boolean | No | `true` (default) = all conditions must match; `false` = any |
- | `enabled` | boolean | No | Whether the rule is enabled on creation (default `false`) |
- Each condition is `{ field, operator, value }` where `field` is one of `from`, `to`, `cc`, `subject`, `content` and `operator` is one of `contains`, `notContains`, `equals`, `beginsWith`, `endsWith`. Actions: `markRead` / `markFlagged` / `delete` (booleans), `moveTo` (mailbox name) with optional `moveToAccount`.
- New rules are created **disabled by default**, including rules that delete or move
- messages. Review the conditions and actions with `list-rules` and in Mail.app,
- then call `enable-rule` explicitly when the rule is approved. Set
- `enabled: true` only when immediate activation is deliberate.
- **Example:**
- ```json
- {
- "name": "Newsletters",
- "conditions": [{ "field": "from", "operator": "contains", "value": "newsletter" }],
- "actions": { "markRead": true, "moveTo": "Reading" }
- }
- ```
- ---
- #### `delete-rule`
- Delete a mail rule by name.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------- |
- | `name` | string | Yes | Rule name |
- **⚠️ Safety:** Destructive. Requires explicit user confirmation; list rules first to confirm the name.
- ---
- ### Contacts
- #### `search-contacts`
- Search the macOS Contacts database by name, organization, nickname, or email substring.
- Since 2.8.7 this reads the AddressBook SQLite files directly rather than driving Contacts.app over AppleScript, so **Contacts.app need not be running and no Automation grant is involved** — but the Node runtime does need **Full Disk Access**, and **Node 22.5+** (see [Requirements](#requirements)). Without either, the tool returns an empty list rather than an error.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | --------------------------------------------------------------------------------- |
- | `query` | string | Yes | Substring matched against full name, organization, nickname, or any email address |
- **Returns:** List of contacts with name, email addresses, and phone numbers. Results are **not** truncated — a broad query returns every match.
- ---
- ### Templates
- Email templates are **persisted to disk** so they survive server restarts, stored as JSON at `APPLE_MAIL_MCP_TEMPLATES_FILE` (default `~/Library/Application Support/apple-mail-mcp/templates.json`).
- #### `save-template`
- Save or update an email template.
- | Parameter | Type | Required | Description |
- | --------- | -------- | -------- | -------------------------- |
- | `name` | string | Yes | Template name |
- | `subject` | string | Yes | Default subject line |
- | `body` | string | Yes | Template body |
- | `to` | string[] | No | Default recipients |
- | `cc` | string[] | No | Default CC recipients |
- | `id` | string | No | Template ID (for updating) |
- ---
- #### `list-templates`
- List all saved templates.
- **Parameters:** None
- ---
- #### `get-template`
- Get a template by ID.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------- |
- | `id` | string | Yes | Template ID |
- ---
- #### `delete-template`
- Delete a template.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------- |
- | `id` | string | Yes | Template ID |
- **⚠️ Safety:** Destructive — removes the template from the on-disk store. Requires explicit user confirmation; list templates first to confirm the id.
- ---
- #### `use-template`
- Create a draft from a template, with optional overrides.
- | Parameter | Type | Required | Description |
- | --------- | -------- | -------- | ------------------- |
- | `id` | string | Yes | Template ID |
- | `to` | string[] | No | Override recipients |
- | `cc` | string[] | No | Override CC |
- | `subject` | string | No | Override subject |
- | `body` | string | No | Override body |
- ---
- ### Diagnostics
- #### `health-check`
- Verify Mail.app connectivity and permissions.
- **Parameters:** None
- **Returns:** Status of all health checks (app running, permissions, account access).
- ---
- #### `doctor`
- Run a full setup diagnostic: Mail.app automation permission, account state (flagging disabled accounts), and each configured IMAP/SMTP backend — each reported as ok / warn / fail with an actionable message.
- **Parameters:** None
- **Returns:** A per-check report (`structuredContent` carries the raw `{healthy, checks[]}`).
- ---
- #### `get-mail-stats`
- Get mail statistics.
- | Parameter | Type | Required | Description |
- | --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
- | `account` | string | No | Limit to one account (uses fast IMAP `STATUS` when that account is IMAP-configured). Omit to merge across all accounts. |
- **Returns:** Total and per-account message/unread counts, plus recently received stats (24h, 7d, 30d). The scoped IMAP path also returns a `perMailbox` breakdown.
- Gathering stats costs one IMAP `STATUS` per mailbox, and Gmail lists every label
- as a mailbox, so a large account is not instant. Accounts are counted
- **concurrently**, and each is bounded by `APPLE_MAIL_MCP_STATS_BUDGET_MS`
- (default `25000`). In the merged all-accounts path an account that fails or
- overruns is reported via `partial: true` + `failedAccounts` rather than being
- folded in as a silent zero; a scoped call to a single account returns an error
- naming the budget instead. Raise the budget if you have a very large account.
- The whole call is additionally bounded by one wall-clock deadline,
- `APPLE_MAIL_MCP_STATS_DEADLINE_MS` (default `50000`), which covers the Mail.app
- account enumeration as well as every per-account read. Per-step budgets alone
- were not enough: their worst cases **add up**, and the sum could exceed a
- client's request timeout, so the call died with nothing returned instead of
- degrading. Keep the deadline below your MCP client's request timeout — whatever
- cannot be read inside it is named in `failedAccounts`, so you always get a
- partial answer rather than a dead call.
- **Concurrent `get-mail-stats` calls do not run concurrently.** Tool calls are
- serialized so they cannot race into Mail.app's single-threaded AppleScript
- dispatch, so each call waits for the ones ahead of it and per-call latency grows
- with queue depth — N concurrent calls take about N × the single-call cost. Since
- this is the most expensive read tool, that is very visible here: measured on 3
- IMAP accounts, three concurrent calls returned at 5.5s / 10.3s / 15.6s against a
- ~5.2s solo cost. The deadline is measured from when the request **arrived**, so
- that wait is spent from the same budget as the work: a call that waited ≥1s
- reports `queueWaitMs`, and one that arrives with its deadline already spent
- returns straight away naming the queue rather than starting work whose answer
- would land after your client has given up. Issue these calls one at a time, and
- prefer `get-unread-count` when a single number will do.
- ---
- #### `get-sync-status`
- Check Mail.app sync activity.
- **Parameters:** None
- **Returns:** Whether sync is detected, pending uploads, recent activity, and seconds since last change.
- ---
- ## Auditing destructive operations
- `delete-message`, `move-message`, `batch-delete-messages` and
- `batch-move-messages` report what they actually did, not merely that Mail.app did
- not raise an error. This exists because of
- [#155](https://github.com/sweetrb/apple-mail-mcp/issues/155): a batch delete was
- reported to have removed two messages whose ids were never passed, and nothing in
- the server recorded enough to explain it.
- ### `countDelta` — always on, no configuration
- Every one of those four tools counts the affected **source** mailbox immediately
- before and immediately after the mutation, **inside the same AppleScript it was
- already running** (no extra `osascript` invocations, no measurable cost), and
- returns the comparison in `structuredContent`:
- ```json
- {
- "ok": true,
- "success": 2,
- "failed": 0,
- "countDelta": [
- {
- "account": "you@gmail.com",
- "mailbox": "INBOX",
- "before": 412,
- "after": 408,
- "expected": 2,
- "observed": 4,
- "status": "over"
- }
- ]
- }
- ```
- `status` is deliberately not a pass/fail flag:
- | `status` | Meaning | Warns? |
- | --------- | ---------------------------------------------------------------------------------------------------------- | ------- |
- | `match` | Exactly as many messages left the mailbox as the operation acted on. | No |
- | `over` | **More** left than were operated on. Messages are unaccounted for. | **Yes** |
- | `unknown` | No comparison this server is willing to assert. `unknownReason` says which of four situations produced it. | No |
- `unknownReason` distinguishes four cases that are _not_ interchangeable:
- | `unknownReason` | Meaning |
- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `count-unreadable` | Mail would not report a count at all (`before`/`after` null). |
- | `no-expectation` | No expectation is predictable, so no comparison exists — a move whose destination **is** the source mailbox. |
- | `count-did-not-move` | The count did not move. On a store that flags deletions instead of removing them this is the **ordinary, correct** reading for an operation that fully succeeded. |
- | `count-partial` | The count moved, but by less than the operation accounted for. A flag-only store cannot produce this, which is why it is worth telling apart. |
- > **`under` was removed in 2.11.0.** It used to mean "fewer left than expected"
- > and was documented as routine. Field evidence retired it — see
- > [Why `observed` is a lower bound](#why-observed-is-a-lower-bound-155).
- #### What an `over` warning does and does not tell you
- Only `over` produces a warning in the tool's text response. Be precise about what
- that warning proves, because a warning is useful only for as long as it is
- trusted:
- - **It establishes** that more messages left the source mailbox across the window
- of the operation than the operation accounted for. That is the data-loss
- direction, and it is the #155 signature.
- - **It does not establish that this server removed them.** The reading is a
- before/after pair around a window, so anything else that removes mail from that
- mailbox inside the window reads identically: a Mail.app rule firing mid-batch,
- a server-side filter, another client (phone, webmail, a second Mail.app)
- deleting or moving, or an IMAP expunge landing between the two counts.
- **Concurrent departure is the benign cause to rule out first**, and the warning
- text says so. What the asymmetry argument actually buys is the other half:
- concurrent _arrivals_ cannot produce `over`, because a message arriving
- mid-operation _raises_ the after-count and biases the reading short.
- That is why `over` is the interesting direction — a strong signal, not a proof.
- Setting `APPLE_MAIL_MCP_AUDIT_LOG` is what settles which one you have: the
- collateral diff below **names** the messages that disappeared, and "the
- newsletter my rule files every morning" is a very different report from a message
- nothing should have touched.
- #### Why `observed` is a lower bound (#155)
- **`observed` is the movement of Mail's count. It is a lower bound on how many
- messages left, not a count of how many left.**
- On iCloud, @scottstern0325 ran the check that settled this: for two batches
- reporting `observed: 0`, the messages were located **in Trash**, matched by
- `date received` + sender against the audit log's pre-image. The deletes had
- happened. Mail's count had not caught up. Across four readings — 0 of 4, 0 of 1
- (a _single-id_ delete), 15 of 16, and 14 of 15 — the shortfall bore no relation
- to batch size, which is what a lagging count looks like and not what a
- store-behaviour rule looks like.
- So a short reading is not evidence about your operation. **The per-id outcomes
Lines 2,001–2,609 are not shown. The link to the file on GitHub has every line.
src/security.test.ts · Bundled script · 303 lines · 1 finding marked
- /**
- * Tests for security hardening: input validation schemas and path traversal prevention.
- */
- import { describe, it, expect } from "vitest";
- import { resolve, isAbsolute } from "path";
- import { homedir } from "os";
- import { existsSync } from "fs";
- import { escapeForAppleScript, escapeForAppleScriptBody } from "@/services/appleMailManager.js";
- import {
- ATTACHMENTS_SCHEMA,
- BATCH_IDS_SCHEMA,
- DATE_FILTER_SCHEMA,
- MESSAGE_ID_SCHEMA,
- } from "@/schemas.js";
- describe("MESSAGE_ID_SCHEMA", () => {
- it("accepts valid numeric IDs", () => {
- expect(MESSAGE_ID_SCHEMA.parse("12345")).toBe("12345");
- expect(MESSAGE_ID_SCHEMA.parse("0")).toBe("0");
- expect(MESSAGE_ID_SCHEMA.parse("999999999")).toBe("999999999");
- });
- it("accepts injection-safe IMAP ids", () => {
- expect(MESSAGE_ID_SCHEMA.parse("imap:YWJjXzEyMw")).toBe("imap:YWJjXzEyMw");
- });
- it("rejects non-numeric IDs", () => {
- expect(() => MESSAGE_ID_SCHEMA.parse("abc")).toThrow();
- expect(() => MESSAGE_ID_SCHEMA.parse("123abc")).toThrow();
- expect(() => MESSAGE_ID_SCHEMA.parse("")).toThrow();
- });
- it("rejects AppleScript injection attempts", () => {
- expect(() => MESSAGE_ID_SCHEMA.parse('1" & do shell script "rm -rf /')).toThrow();
- Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
- Line 35 on GitHub
- expect(() => MESSAGE_ID_SCHEMA.parse("1; drop table")).toThrow();
- expect(() => MESSAGE_ID_SCHEMA.parse("-1")).toThrow();
- });
- it("rejects template-style IDs (tmpl_N format)", () => {
- expect(() => MESSAGE_ID_SCHEMA.parse("tmpl_1")).toThrow();
- });
- });
- describe("BATCH_IDS_SCHEMA", () => {
- it("accepts valid batch of numeric IDs", () => {
- const result = BATCH_IDS_SCHEMA.parse(["1", "2", "3"]);
- expect(result).toEqual(["1", "2", "3"]);
- });
- it("accepts a batch of IMAP ids", () => {
- expect(BATCH_IDS_SCHEMA.parse(["imap:YWJj", "imap:ZGVm"])).toEqual(["imap:YWJj", "imap:ZGVm"]);
- });
- it("rejects empty array", () => {
- expect(() => BATCH_IDS_SCHEMA.parse([])).toThrow("At least one message ID");
- });
- it("rejects more than 100 IDs", () => {
- const ids = Array.from({ length: 101 }, (_, i) => String(i));
- expect(() => BATCH_IDS_SCHEMA.parse(ids)).toThrow("Cannot process more than 100");
- });
- it("accepts exactly 100 IDs", () => {
- const ids = Array.from({ length: 100 }, (_, i) => String(i));
- expect(BATCH_IDS_SCHEMA.parse(ids)).toHaveLength(100);
- });
- it("rejects batch containing non-numeric IDs", () => {
- expect(() => BATCH_IDS_SCHEMA.parse(["123", "abc", "456"])).toThrow();
- });
- });
- describe("DATE_FILTER_SCHEMA", () => {
- it("accepts valid date strings", () => {
- expect(DATE_FILTER_SCHEMA.parse("January 1, 2026")).toBe("January 1, 2026");
- expect(DATE_FILTER_SCHEMA.parse("March 15, 2026")).toBe("March 15, 2026");
- expect(DATE_FILTER_SCHEMA.parse("2026-03-15")).toBe("2026-03-15");
- expect(DATE_FILTER_SCHEMA.parse("3/15/2026")).toBe("3/15/2026");
- });
- it("accepts undefined (optional)", () => {
- expect(DATE_FILTER_SCHEMA.parse(undefined)).toBeUndefined();
- });
- it("rejects strings with quotes (AppleScript injection)", () => {
- expect(() => DATE_FILTER_SCHEMA.parse('"January 1" & do shell script "evil"')).toThrow();
- });
- it("rejects strings with backslashes", () => {
- expect(() => DATE_FILTER_SCHEMA.parse("January\\1")).toThrow();
- });
- it("rejects strings with parentheses", () => {
- expect(() => DATE_FILTER_SCHEMA.parse("date(2026)")).toThrow();
- });
- it("rejects non-parseable date strings", () => {
- expect(() => DATE_FILTER_SCHEMA.parse("31")).toThrow();
- expect(() => DATE_FILTER_SCHEMA.parse("abc")).toThrow();
- expect(() => DATE_FILTER_SCHEMA.parse("1234567890")).toThrow();
- });
- });
- describe("saveAttachment input validation", () => {
- // Test the validation logic that lives in appleMailManager.saveAttachment
- // by checking the same regex/logic used there
- const isInvalidAttachmentName = (name: string): boolean => {
- return /[/\\\0]/.test(name) || name.includes("..");
- };
- it("blocks forward slash in attachment name", () => {
- expect(isInvalidAttachmentName("../../etc/passwd")).toBe(true);
- expect(isInvalidAttachmentName("path/to/file.txt")).toBe(true);
- });
- it("blocks backslash in attachment name", () => {
- expect(isInvalidAttachmentName("file\\name.txt")).toBe(true);
- });
- it("blocks null bytes in attachment name", () => {
- expect(isInvalidAttachmentName("file\0name.txt")).toBe(true);
- });
- it("blocks directory traversal in attachment name", () => {
- expect(isInvalidAttachmentName("..")).toBe(true);
- expect(isInvalidAttachmentName("../secret")).toBe(true);
- });
- it("allows normal attachment names", () => {
- expect(isInvalidAttachmentName("report.pdf")).toBe(false);
- expect(isInvalidAttachmentName("Q1 Budget (Final).xlsx")).toBe(false);
- expect(isInvalidAttachmentName("résumé.docx")).toBe(false);
- });
- const isAllowedPath = (savePath: string): boolean => {
- const resolvedPath = resolve(savePath);
- const allowedPrefixes = [homedir(), "/tmp", "/private/tmp", "/Volumes"];
- return allowedPrefixes.some((prefix: string) => resolvedPath.startsWith(prefix));
- };
- it("allows paths under home directory", () => {
- expect(isAllowedPath(`${homedir()}/Downloads`)).toBe(true);
- });
- it("allows /tmp", () => {
- expect(isAllowedPath("/tmp")).toBe(true);
- expect(isAllowedPath("/tmp/attachments")).toBe(true);
- });
- it("blocks traversal out of allowed directories", () => {
- expect(isAllowedPath("/tmp/../../etc")).toBe(false);
- });
- it("blocks /etc directly", () => {
- expect(isAllowedPath("/etc")).toBe(false);
- });
- it("blocks /usr paths", () => {
- expect(isAllowedPath("/usr/local")).toBe(false);
- });
- });
- describe("buildAttachmentCommands validation", () => {
- // Mirror the logic from appleMailManager.ts buildAttachmentCommands()
- // to test the validation in isolation without needing real files.
- function escapeForAppleScript(text: string): string {
- if (!text) return "";
- return text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
- }
- function buildAttachmentCommands(attachments?: string[]): string {
- if (!attachments || attachments.length === 0) return "";
- for (const filePath of attachments) {
- if (!isAbsolute(filePath)) {
- throw new Error(`Attachment path must be absolute: "${filePath}"`);
- }
- if (!existsSync(filePath)) {
- throw new Error(`Attachment file not found: "${filePath}"`);
- }
- }
- let commands = "";
- for (const filePath of attachments) {
- const safePath = escapeForAppleScript(filePath);
- commands += `make new attachment with properties {file name:POSIX file "${safePath}"} at after the last paragraph\n`;
- }
- return commands;
- }
- it("returns empty string for undefined", () => {
- expect(buildAttachmentCommands(undefined)).toBe("");
- });
- it("returns empty string for empty array", () => {
- expect(buildAttachmentCommands([])).toBe("");
- });
- it("rejects relative paths", () => {
- expect(() => buildAttachmentCommands(["relative/path.pdf"])).toThrow("must be absolute");
- });
- it("rejects paths starting with ./", () => {
- expect(() => buildAttachmentCommands(["./file.pdf"])).toThrow("must be absolute");
- });
- it("rejects nonexistent files", () => {
- expect(() => buildAttachmentCommands(["/nonexistent/file.pdf"])).toThrow("not found");
- });
- it("generates correct AppleScript for valid files", () => {
- // Use a file we know exists
- const testFile = "/usr/bin/env";
- const result = buildAttachmentCommands([testFile]);
- expect(result).toContain("make new attachment");
- expect(result).toContain("POSIX file");
- expect(result).toContain(testFile);
- });
- it("escapes double quotes in file paths", () => {
- // Test the escaping function directly since we can't easily mock existsSync
- const escaped = escapeForAppleScript('/Users/test/file "name".pdf');
- expect(escaped).toContain('file \\"name\\"');
- });
- it("handles multiple attachments", () => {
- const testFile = "/usr/bin/env";
- const result = buildAttachmentCommands([testFile, testFile]);
- const matches = result.match(/make new attachment/g);
- expect(matches).toHaveLength(2);
- });
- it("rejects more than 20 attachments at schema level", () => {
- const paths = Array.from({ length: 21 }, (_, i) => `/tmp/file${i}.pdf`);
- expect(() => ATTACHMENTS_SCHEMA.parse(paths)).toThrow("Cannot attach more than 20");
- });
- it("accepts exactly 20 attachments at schema level", () => {
- const paths = Array.from({ length: 20 }, (_, i) => `/tmp/file${i}.pdf`);
- expect(ATTACHMENTS_SCHEMA.parse(paths)).toHaveLength(20);
- });
- });
- describe("escapeForAppleScript vs escapeForAppleScriptBody (audit #10 + body newlines)", () => {
- // These test the REAL exported functions from appleMailManager.ts, not a
- // local mirror. The single-line variant strips control chars entirely; the
- // body variant converts line breaks to the two-character AppleScript escape
- // sequence `\n` so paragraph breaks survive without any raw control
- // character ever entering the emitted literal.
- it("body: newlines survive as the \\n escape sequence", () => {
- const body = "Paragraph one.\n\nParagraph two.\nLine three.";
- const escaped = escapeForAppleScriptBody(body);
- expect(escaped).toBe("Paragraph one.\\n\\nParagraph two.\\nLine three.");
- // No raw control characters in the emitted literal
- // eslint-disable-next-line no-control-regex
- expect(escaped).not.toMatch(/[\x00-\x1f\x7f]/);
- });
- it("body: CRLF and lone CR normalize to \\n", () => {
- expect(escapeForAppleScriptBody("a\r\nb\rc\nd")).toBe("a\\nb\\nc\\nd");
- });
- it("body: tabs become the \\t escape sequence", () => {
- expect(escapeForAppleScriptBody("col1\tcol2")).toBe("col1\\tcol2");
- });
- it("body: injection combining quotes and raw newlines cannot escape the literal", () => {
- const attack = '"\ntell application "Finder" to delete every file\n"';
- const escaped = escapeForAppleScriptBody(attack);
- // Quotes are escaped, newlines are the two-char sequence — the payload
- // stays inside the AppleScript string literal.
- expect(escaped).toBe('\\"\\ntell application \\"Finder\\" to delete every file\\n\\"');
- // eslint-disable-next-line no-control-regex
- expect(escaped).not.toMatch(/[\x00-\x1f\x7f]/);
- });
- it("body: backslash escaped before quote/newline (no double-escape confusion)", () => {
- // A literal backslash followed by the letter n must NOT collapse into a
- // linefeed escape ambiguity: input \n (two chars) → \\n (three chars out).
- expect(escapeForAppleScriptBody("\\n")).toBe("\\\\n");
- // And a real newline after a backslash: \ + LF → \\ + \n
- expect(escapeForAppleScriptBody("\\\n")).toBe("\\\\\\n");
- });
- it("body: strips remaining control characters (NUL, ESC, DEL)", () => {
- expect(escapeForAppleScriptBody("a\x00b\x1bc\x7fd")).toBe("abcd");
- });
- it("single-line: still strips ALL control chars including newlines", () => {
- expect(escapeForAppleScript("Subject\nline\r\ntwo\ttabbed\x00")).toBe("Subjectlinetwotabbed");
- });
- it("single-line: quote/backslash escaping unchanged", () => {
- expect(escapeForAppleScript('say "hi" \\ bye')).toBe('say \\"hi\\" \\\\ bye');
- });
- it("both: empty and falsy input yield empty string", () => {
- expect(escapeForAppleScript("")).toBe("");
- expect(escapeForAppleScriptBody("")).toBe("");
- });
- });
src/utils/headers.test.ts · Bundled script · 403 lines · 1 finding marked
- import { describe, it, expect } from "vitest";
- import {
- decodeEncodedWords,
- decodeHeaderBytes,
- headersStructured,
- isoOrUndefined,
- MAX_SENT_AFTER_RECEIVED_MS,
- parseHeaderBlock,
- plausibleDateSent,
- } from "./headers.js";
- const BLOCK = [
- "Received: from mx2.example.net (mx2.example.net [10.0.0.2])",
- "\tby imap.example.com with ESMTPS id abc123;",
- "\tWed, 03 Jun 2020 14:05:00 +0000",
- "Received: from sender.example.org ([10.0.0.9])",
- " by mx2.example.net; Wed, 03 Jun 2020 14:04:58 +0000",
- "Date: Wed, 3 Jun 2020 16:04:55 +0200 (CEST)",
- "From: =?UTF-8?Q?Jos=C3=A9_Puertolas?= <jose@example.org>",
- "To: Rob <rob@example.com>",
- "Cc: =?utf-8?B?Sm9zw6k=?= Dos <dos@example.org>",
- "Reply-To: list@example.org",
- "Subject: =?UTF-8?B?SGVsbG8g?=",
- " =?UTF-8?B?d29ybGQ=?=",
- "Message-ID: <orig-id@example.org>",
- "In-Reply-To: <parent@example.org>",
- "References: <root@example.org>",
- "\t<parent@example.org>",
- "MIME-Version: 1.0",
- "",
- "Body text that must not be parsed as a header",
- "X-Not-A-Header: in the body",
- ].join("\r\n");
- describe("parseHeaderBlock", () => {
- const p = parseHeaderBlock(BLOCK);
- it("stops at the first blank line so body text is never read as a header", () => {
- expect(p.headers.some((h) => h.name === "X-Not-A-Header")).toBe(false);
- expect(p.raw.endsWith("MIME-Version: 1.0")).toBe(true);
- });
- it("unfolds continuation lines and keeps every header in wire order", () => {
- expect(p.headers[0]).toEqual({
- name: "Received",
- value:
- "from mx2.example.net (mx2.example.net [10.0.0.2]) by imap.example.com with ESMTPS id abc123; Wed, 03 Jun 2020 14:05:00 +0000",
- });
- expect(p.headers.map((h) => h.name).slice(0, 4)).toEqual([
- "Received",
- "Received",
- "Date",
- "From",
- ]);
- });
- it("keeps every Received hop, last hop first", () => {
- expect(p.received).toHaveLength(2);
- expect(p.received[0]).toMatch(/^from mx2\.example\.net/);
- expect(p.received[1]).toMatch(/^from sender\.example\.org/);
- });
- it("sources `date` from the Date: header, tolerating a trailing zone comment", () => {
- expect(p.dateHeader).toBe("Wed, 3 Jun 2020 16:04:55 +0200 (CEST)");
- expect(p.date).toBe("2020-06-03T14:04:55.000Z");
- });
- it("decodes RFC 2047 words in the display fields and joins adjacent words", () => {
- expect(p.from).toBe("José Puertolas <jose@example.org>");
- expect(p.cc).toBe("José Dos <dos@example.org>");
- expect(p.subject).toBe("Hello world");
- expect(p.replyTo).toBe("list@example.org");
- expect(p.to).toBe("Rob <rob@example.com>");
- });
- it("leaves the raw header values undecoded", () => {
- expect(p.headers.find((h) => h.name === "Subject")?.value).toBe(
- "=?UTF-8?B?SGVsbG8g?= =?UTF-8?B?d29ybGQ=?="
- );
- });
- it("strips angle brackets from the threading ids", () => {
- expect(p.messageId).toBe("orig-id@example.org");
- expect(p.inReplyTo).toBe("parent@example.org");
- expect(p.references).toEqual(["root@example.org", "parent@example.org"]);
- });
- it("accepts LF-only input and a block with no body", () => {
- const q = parseHeaderBlock("Subject: plain\nDate: not a date\nMessage-Id: <x@y>\n");
- expect(q.subject).toBe("plain");
- expect(q.date).toBeUndefined();
- expect(q.dateHeader).toBe("not a date");
- expect(q.messageId).toBe("x@y");
- expect(q.references).toEqual([]);
- expect(q.received).toEqual([]);
- });
- it("is lenient with malformed lines instead of aborting", () => {
- const q = parseHeaderBlock("garbage line\nSubject: ok\n");
- expect(q.headers).toEqual([{ name: "Subject", value: "ok" }]);
- });
- // #226 — old Entourage/Outlook-for-Mac (~2005-2011, MIME boundary
- // OUTLOOK2MACxxxxxxxx) wrote Date: using the OS locale instead of RFC 5322
- // (e.g. Spanish "jue ago 30 13:55:12 2007" — "jue" = Thursday, "ago" =
- // August). The reporter's literal minimal repro turns out to already parse
- // correctly today (this pins that down as a regression guard); the real,
- // previously-unguarded gap was bare-CR line endings, below.
- const outlook2macRepro = [
- "From: Test Sender <test@example.com>",
- "To: 'Test Recipient'",
- "Date: jue ago 30 13:55:12 2007",
- "Subject: diferencial",
- "MIME-Version: 1.0",
- 'Content-Type: multipart/mixed; boundary="OUTLOOK2MAC8473928"',
- ];
- it.each([
- ["LF", "\n"],
- ["CRLF", "\r\n"],
- ])(
- "never drops or merges a header just because Date: is an unparseable locale string (%s)",
- (_label, sep) => {
- const q = parseHeaderBlock(outlook2macRepro.join(sep));
- expect(q.dateHeader).toBe("jue ago 30 13:55:12 2007");
- // Was `toBeUndefined()` until #229: this test's subject is header
- // INTEGRITY, and the undefined `date` merely recorded the then-current
- // limitation that `ago` (agosto) is not an English month abbreviation.
- // parseDateHeader now maps it, which is what the reporter asked for; the
- // integrity assertions below are unchanged and still the point.
- expect(q.date).toBe(new Date("Thu Aug 30 13:55:12 2007").toISOString());
- expect(q.subject).toBe("diferencial");
- expect(q.headers.map((h) => h.name)).toEqual([
- "From",
- "To",
- "Date",
- "Subject",
- "MIME-Version",
- "Content-Type",
- ]);
- }
- );
- it("parses bare-CR line endings the same as LF/CRLF (#226 — AppleScript's `all headers of msg` can return \\r-only text; previously this silently dropped every header)", () => {
- const q = parseHeaderBlock(outlook2macRepro.join("\r"));
- expect(q.dateHeader).toBe("jue ago 30 13:55:12 2007");
- expect(q.subject).toBe("diferencial");
- expect(q.headers).toHaveLength(6);
- });
- it("stops at the first blank line under bare-CR endings too (CRCR, not just LFLF)", () => {
- const q = parseHeaderBlock(
- [...outlook2macRepro, "", "Body text that must not be parsed as a header"].join("\r")
- );
- expect(q.headers.map((h) => h.name)).toEqual([
- "From",
- "To",
- "Date",
- "Subject",
- "MIME-Version",
- "Content-Type",
- ]);
- });
- it("returns an empty result for empty input", () => {
- const q = parseHeaderBlock("");
- expect(q.headers).toEqual([]);
- expect(q.raw).toBe("");
- expect(q.date).toBeUndefined();
- });
- });
- describe("decodeEncodedWords", () => {
- it("passes through text without encoded-words untouched", () => {
- expect(decodeEncodedWords("plain <a@b>")).toBe("plain <a@b>");
- });
- it("decodes Q encoding underscores as spaces and hex escapes", () => {
- expect(decodeEncodedWords("=?iso-8859-1?Q?caf=E9_au_lait?=")).toBe("café au lait");
- });
- it("falls back to UTF-8 for an unknown charset rather than throwing", () => {
- expect(decodeEncodedWords("=?x-unknown-cs?B?aGk=?=")).toBe("hi");
- });
- it("leaves an undecodable word in place", () => {
- // `?=` with no text and a bad charset label still round-trips as text.
- expect(decodeEncodedWords("=?utf-8?X?zzz?=")).toBe("=?utf-8?X?zzz?=");
- });
- });
- describe("headersStructured", () => {
- it("carries the backend arrival timestamp beside the Date: header", () => {
- const s = headersStructured(
- "imap:abc",
- parseHeaderBlock(BLOCK),
- new Date("2026-01-02T03:04:05Z")
- );
- expect(s.id).toBe("imap:abc");
- expect(s.date).toBe("2020-06-03T14:04:55.000Z");
- expect(s.dateReceived).toBe("2026-01-02T03:04:05.000Z");
- expect(s.headerCount).toBe(12);
- expect(s.messageId).toBe("orig-id@example.org");
- });
- it("omits dateReceived when the backend had none or it was invalid", () => {
- expect(headersStructured("1", parseHeaderBlock("Subject: x"))).not.toHaveProperty(
- "dateReceived"
- );
- expect(
- headersStructured("1", parseHeaderBlock("Subject: x"), new Date("garbage"))
- ).not.toHaveProperty("dateReceived");
- });
- });
- describe("isoOrUndefined", () => {
- it("handles Date, string, empty and invalid inputs", () => {
- expect(isoOrUndefined(new Date("2020-01-01T00:00:00Z"))).toBe("2020-01-01T00:00:00.000Z");
- expect(isoOrUndefined("2020-01-01T00:00:00Z")).toBe("2020-01-01T00:00:00.000Z");
- expect(isoOrUndefined("")).toBeUndefined();
- expect(isoOrUndefined(undefined)).toBeUndefined();
- expect(isoOrUndefined(new Date("nope"))).toBeUndefined();
- });
- });
- describe("#229 — locale month abbreviations in legacy Date: headers", () => {
- // Byte-exact header block supplied by @j5pu from `BODY.PEEK[HEADER]` on the
- // reporting mailbox (message A, id 345559). From/To/Cc masked at his request;
- // Date/Subject/MIME-Version/Content-Type are untouched. Legacy Entourage /
- // Outlook for Mac wrote the system locale's month abbreviation.
- const MSG_A =
- "From: XXXX XXXXXX XXXXX XXXXX <xxxxx@xxxxx.net>\r\n" +
- "To: 'XXXXX XXXXX XXXXXXX XXXXXXXX'\r\n" +
- "Cc: 'XXXXXXX XXXXXXXXX, XXXXX'\r\n" +
- "Date: jue ago 30 13:55:12 2007\r\n" +
- "Subject: diferencial\r\n" +
- "MIME-Version: 1.0\r\n" +
- 'Content-Type: multipart/mixed; boundary="OUTLOOK2MAC8473928"\r\n\r\n';
- it("parses a Spanish-locale Date: header that Date.parse rejects", () => {
- // `new Date("jue ago 30 13:55:12 2007")` is NaN — `ago` is agosto, not Aug.
- expect(Number.isNaN(new Date("jue ago 30 13:55:12 2007").getTime())).toBe(true);
- const h = parseHeaderBlock(MSG_A);
- expect(h.date).toBe(new Date("Thu Aug 30 13:55:12 2007").toISOString());
- expect(h.dateHeader).toBe("jue ago 30 13:55:12 2007");
- });
- it("covers the months that silently worked and the ones that did not", () => {
- // ⚠️ The bug was PARTIAL: Spanish `oct` == English `Oct`, so a spot check on
- // an October message reports the mailbox healthy. These four did not.
- for (const [abbr, month] of [
- ["ene", 0],
- ["abr", 3],
- ["ago", 7],
- ["dic", 11],
- ] as [string, number][]) {
- const h = parseHeaderBlock(`Date: jue ${abbr} 30 13:55:12 2007\r\nSubject: s\r\n\r\n`);
- expect(h.date, `${abbr} should parse`).toBeDefined();
- expect(new Date(h.date!).getMonth(), `${abbr} -> month`).toBe(month);
- }
- });
- it("still returns undefined for a genuinely unusable date", () => {
- const h = parseHeaderBlock("Date: not a date at all\r\nSubject: s\r\n\r\n");
- expect(h.date).toBeUndefined();
- expect(h.dateHeader).toBe("not a date at all"); // verbatim, still visible
- });
- });
- describe("#234 — Mail.app hands back `all headers` with the next header fused onto Date:", () => {
- // Byte-exact (From/To/Cc masked) output of Mail's own `all headers of msg` for
- // @j5pu's message A, captured in Script Editor with no connector in the loop and
- // posted as base64 in #234. Bare LF, no CR, no folding: the Date: VALUE never
- // arrives at all, and Mail pulled the Subject: line up onto the Date: name.
- const FUSED_B64 =
- "RnJvbTogeHh4eHggeHh4eHh4eCB4eHh4eHh4eHh4IHh4eHh4eHh4eHggPHh4eHh4eHh4eEB4eHh4" +
- Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
- Line 276 on GitHub
- "eC54eHg+ClRvOiAneHh4eHggeHh4eHggeHh4eHh4eCB4eHh4eHh4eCcKQ2M6ICd4eHh4eHggeHh4" +
- "eHh4eHh4LCB4eHh4eCcKRGF0ZTogU3ViamVjdDogZGlmZXJlbmNpYWwKTWltZS1WZXJzaW9uOiAx" +
- "LjAKQ29udGVudC1UeXBlOiBtdWx0aXBhcnQvbWl4ZWQ7IGJvdW5kYXJ5PSJPVVRMT09LMk1BQzg0" +
- "NzM5MjgiCgo=";
- const FUSED = Buffer.from(FUSED_B64, "base64").toString("utf8");
- it("the fixture really is the fused block (guards against a mangled fixture)", () => {
- expect(FUSED).toContain("\nDate: Subject: diferencial\nMime-Version: 1.0\n");
- expect(FUSED).not.toContain("\r");
- });
- it("splits the fused line back apart and reports the date as ABSENT, not a Subject string", () => {
- const h = parseHeaderBlock(FUSED);
- expect(h.dateHeader).toBeUndefined();
- expect(h.date).toBeUndefined();
- expect(h.subject).toBe("diferencial");
- expect(h.headers.map((x) => x.name)).toEqual([
- "From",
- "To",
- "Cc",
- "Date",
- "Subject",
- "Mime-Version",
- "Content-Type",
- ]);
- expect(h.headers.find((x) => x.name === "Date")?.value).toBe("");
- expect(h.warnings?.join(" ")).toMatch(/Date:.*Subject:/);
- // The forensic record is never rewritten.
- expect(h.raw).toContain("Date: Subject: diferencial");
- });
- it("leaves colon-bearing values alone: a real Date with 13:55:12 and a Subject of `Re: foo: bar`", () => {
- const h = parseHeaderBlock(
- "Date: Thu, 30 Aug 2007 13:55:12 +0200\nSubject: Re: foo: bar\nFrom: a <a@b.c>\n\n"
- );
- expect(h.dateHeader).toBe("Thu, 30 Aug 2007 13:55:12 +0200");
- expect(h.date).toBe("2007-08-30T11:55:12.000Z");
- expect(h.subject).toBe("Re: foo: bar");
- expect(h.headers).toHaveLength(3);
- expect(h.warnings).toBeUndefined();
- });
- it("does not split a Date value whose leading word is not a header name", () => {
- const h = parseHeaderBlock("Date: Note: unparseable\nSubject: s\n\n");
- expect(h.dateHeader).toBe("Note: unparseable");
- expect(h.headers).toHaveLength(2);
- expect(h.warnings).toBeUndefined();
- });
- it("only repairs Date: — a Subject whose text starts with a header name is left intact", () => {
- const h = parseHeaderBlock(
- "Date: Thu, 30 Aug 2007 13:55:12 +0200\nSubject: From: the desk of X\n\n"
- );
- expect(h.subject).toBe("From: the desk of X");
- expect(h.headers).toHaveLength(2);
- expect(h.warnings).toBeUndefined();
- });
- it("headersStructured names the backend and carries the repair warning (self-diagnosing)", () => {
- const s = headersStructured("345559", parseHeaderBlock(FUSED), undefined, "applescript");
- expect(s.backend).toBe("applescript");
- expect(s).not.toHaveProperty("dateHeader");
- expect(s).not.toHaveProperty("date");
- expect(s.subject).toBe("diferencial");
- expect(Array.isArray(s.warnings)).toBe(true);
- const clean = headersStructured(
- "imap:x",
- parseHeaderBlock("Subject: s\n\n"),
- undefined,
- "imap"
- );
- expect(clean.backend).toBe("imap");
- expect(clean).not.toHaveProperty("warnings");
- });
- });
- describe("#234 §2b — plausibleDateSent: a send time after arrival is invented, not skewed", () => {
- const RECEIVED = new Date("2014-01-14T12:53:59.000Z");
- const DAY = 24 * 60 * 60 * 1000;
- it("drops the reporter's decade-scale inversion (Mail's date sent 2024 vs arrival 2014)", () => {
- expect(plausibleDateSent(new Date("2024-08-24T00:26:38.000Z"), RECEIVED)).toBeUndefined();
- });
- it("keeps ordinary sender clock skew — hours ahead of arrival is normal", () => {
- const skewed = new Date(RECEIVED.getTime() + 9 * 60 * 60 * 1000);
- expect(plausibleDateSent(skewed, RECEIVED)).toEqual(skewed);
- });
- it("boundary: exactly the tolerance is kept, one second past it is dropped", () => {
- expect(MAX_SENT_AFTER_RECEIVED_MS).toBe(7 * DAY);
- const atLimit = new Date(RECEIVED.getTime() + MAX_SENT_AFTER_RECEIVED_MS);
- const past = new Date(RECEIVED.getTime() + MAX_SENT_AFTER_RECEIVED_MS + 1000);
- expect(plausibleDateSent(atLimit, RECEIVED)).toEqual(atLimit);
- expect(plausibleDateSent(past, RECEIVED)).toBeUndefined();
- });
- it("keeps a send time with no arrival to compare against, and drops an invalid one", () => {
- const sent = new Date("2007-08-30T11:55:12.000Z");
- expect(plausibleDateSent(sent, undefined)).toEqual(sent);
- expect(plausibleDateSent(sent, new Date(NaN))).toEqual(sent);
- expect(plausibleDateSent(new Date(NaN), RECEIVED)).toBeUndefined();
- expect(plausibleDateSent(undefined, RECEIVED)).toBeUndefined();
- });
- });
- describe("#234 §4 — decodeHeaderBytes: unencoded 8-bit header bytes", () => {
- it("decodes a raw latin-1 display name as windows-1252 instead of destroying it", () => {
- const bytes = Buffer.from(
- 'From: "Jos\xe9 Pu\xf1ez" <j@example.org>\r\nSubject: s\r\n',
- "latin1"
- );
- const text = decodeHeaderBytes(bytes);
- expect(text).toContain('From: "José Puñez" <j@example.org>');
- expect(text).not.toContain("\ufffd");
- });
- it("leaves valid UTF-8 lines as UTF-8, deciding per line", () => {
- const bytes = Buffer.concat([
- Buffer.from("Subject: Jos\u00e9 (utf-8)\r\n", "utf8"),
- Buffer.from("From: Pu\xf1ez <p@example.org>\r\n", "latin1"),
- ]);
- const h = parseHeaderBlock(decodeHeaderBytes(bytes));
- expect(h.subject).toBe("José (utf-8)");
- expect(h.from).toBe("Puñez <p@example.org>");
- });
- });
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.