apple-mail-search

What This Skill Does

The apple-mail-search skill, powered by the fruitmail-cli engine, acts as a high-performance bridge between your AI agent and the macOS Apple Mail.app database. By directly querying the SQLite 'Envelope Index' used by Mail.app, this tool circumvents the extreme latency typically associated with AppleScript-based email retrieval. While native AppleScript methods can take over 8 minutes to index 130,000 emails, this tool performs the same operation in approximately 50 milliseconds. It provides robust capabilities for searching subject lines, filtering by sender, isolating unread messages, and retrieving the full raw content of email bodies, all while maintaining a strict read-only security posture.

Installation

To integrate this skill into your environment, ensure you are on a macOS system with Node.js installed. Run the following command in your terminal:

npm install -g apple-mail-search-cli

Once the CLI is available, you can add it to your OpenClaw agent using the installation command: clawhub install openclaw/skills/skills/gumadeiras/apple-mail-search-safe.

Use Cases

This skill is perfect for users who need to organize their inbox without manual navigation. Use it to quickly find historical invoices, locate forgotten shipping confirmations from specific domains, or extract actionable information from long threads. It is particularly effective for developers or power users who need to process high volumes of email data for reporting or archiving purposes without the overhead of the Mail.app GUI.

Example Prompts

1. "Find all unread emails from Amazon in the last 7 days and give me the subjects."
2. "Search for an email containing 'invoice' from the last month, then show me the full body of the most recent one."
3. "List the 10 most recent unread emails and provide them in a JSON format so I can process them in my project dashboard."

Tips & Limitations

• macOS Exclusive: This tool is strictly for local Apple Mail.app databases on macOS. It cannot access web-based email clients or non-macOS mail stores.
• Read-Only: For your safety, the tool cannot send or delete emails. If you require outgoing mail capabilities, please pair this with the himalaya skill.
• Data Safety: The tool performs read-only queries by default. For added security, utilize the --copy flag, which creates a temporary local copy of the database before running complex search queries to ensure your primary Mail index remains untouched.