apple-mail

What This Skill Does

The Apple Mail skill provides deep integration with the macOS Mail.app, enabling users to programmatically manage their email directly from the OpenClaw AI agent. This powerful skill allows for a wide range of actions, including reading inbox messages, searching for specific emails using flexible queries, sending new emails, replying to existing ones, and deleting or marking messages as read or unread. It achieves this by leveraging AppleScript and direct SQLite access to the Mail.app's underlying data store, offering fast and efficient operations without the need for manual enumeration of messages. Key features include a "fast search" capability optimized for speed by working on a temporary copy of the database, and a "refresh" command to force Mail.app to check for new messages across all accounts. The skill also provides utilities to list available email accounts and mailboxes within specific accounts.

Installation

To install the Apple Mail skill, use the following command in your OpenClaw environment:

clawhub install openclaw/skills/skills/tyler6204/apple-mail

This command will download and set up all the necessary scripts and configurations for the skill to function.

Use Cases

This skill is ideal for automating email-related tasks on macOS. Users can:

• Automate email responses: Set up rules to automatically reply to common inquiries.
• Organize inbox: Automatically delete spam or mark certain emails as read.
• Search for critical information: Quickly find specific emails (e.g., invoices, meeting requests) without opening Mail.app.
• Generate reports: Extract email data for analysis or record-keeping.
• Send automated notifications: Trigger email alerts based on system events.
• Manage email communications efficiently: Perform batch operations like marking multiple emails as read or deleting them.

Example Prompts

1. "Search my inbox for emails from '[email protected]' with the subject 'Order Confirmation' and show me the latest 5."
2. "Send an email to '[email protected]' from my work account with the subject 'Project Update' and the body 'Please find the latest project status report attached.'"
3. "Mark the email with ID '12345' as read and then reply to it with 'Got it, thanks!'"

Tips & Limitations

• Mail.app must be running: The scripts will fail if Mail.app is not open. Ensure it's running before executing commands.
• Gmail special folders: For Gmail accounts, special folders like Spam, Sent Mail, All Mail, and Trash require a specific prefix: [Gmail]/Spam, [Gmail]/Sent Mail, etc. Custom labels work without this prefix.
• Refresh before listing: Commands like mail-list.sh do not auto-refresh. For the most up-to-date information, run mail-refresh.sh first.
• Fast search safety: The mail-fast-search.sh command is now safe to use even when Mail.app is running, as it operates on a temporary copy of the database.
• Attachment limitations: The mail-send.sh command supports a single attachment. For more complex attachments, you may need to explore alternative methods or script modifications.
• Performance: While most operations are fast, complex searches or operations on very large mailboxes can still take time. The "fast search" is highly recommended for performance-critical queries.