Apple Mail Search

**Verdict:** A strong, high-performance tool for searching Apple Mail metadata on macOS, ideal for agents that need fast, structured access to a user’s Mail.app messages. Its main limitation is scope: Apple Mail only, metadata only, and macOS-specific. **What it does well** - Uses the Apple Mail *Envelope Index* SQLite database directly, delivering searches in roughly **~50ms** even on large (~130k) mailboxes. - Supports a variety of targeted queries: `subject`, `sender`, `from-name`, `to`, `unread`, `attachments`, `attachment-type`, `recent`, `date-range`, and `open` by ID. - Provides `--json` and `--csv` output, which is excellent for OpenClaw agents that want to parse and post-process email metadata programmatically. - Read-only by design (cannot compose/send or modify messages), which greatly reduces the risk of damaging the mailbox. **Key risks & limitations** - **Platform lock-in:** Works only with **Apple Mail.app on macOS**; it will not function for Outlook, Gmail web, or other clients. Agents must check that the user is on macOS and uses Mail.app. - **Metadata only:** It exposes metadata (subjects, addresses, dates, attachment names, flags). It does **not** provide direct access to full message bodies, which still reside in `.emlx` files. Agents that need to read email content must combine this with another mechanism. - **Fragility to OS changes:** It relies on internal database paths and schema (`~/Library/Mail/V{9,10,11}/MailData/Envelope Index`). Future macOS versions may change these, potentially breaking the tool until updated. - **Privacy surface:** Although local and read-only, it exposes sensitive email metadata. In an agent context, you must be careful not to exfiltrate or over-share results, especially when using `--json`/`--csv` with external services. **Recommended scenarios for use** - The environment is **macOS** and the user relies on **Mail.app**. - The user asks to **find, search, or list emails** by subject, sender, recipient, unread status, attachment presence/type, or recent date ranges. - You need **fast, repeated queries** over large mailboxes where AppleScript or Spotlight-based methods are too slow or unreliable. - You want structured output for **automation**, such as generating unread summaries, collecting a list of invoices, or exporting recent mail to CSV/JSON for further processing. **When to avoid or supplement this tool** - The user is on **Windows, Linux, or uses a non-Apple mail client** → this tool will not apply. - You must analyze **email body content** → use this only to locate relevant messages, then hand off message IDs/paths to another tool that can fetch and process bodies. - You need robust long-term compatibility across macOS versions without maintenance → be aware that schema/path changes could require updates to the tool or calling logic.