A specialized macOS integration for Mail.app that enables lightning-fast email searching, reading, and management through a hybrid AppleScript and SQLite approach.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install apple-mail
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install apple-mail using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Apple Mail?
The Apple Mail skill provides a robust interface for interacting with the native macOS Mail application. By utilizing Openclaw Skills to bridge the gap between CLI tools and the Mail.app database, users can perform complex email operations without manual intervention. It is designed for speed and reliability, making it an ideal choice for developers and power users who need to automate their communication workflows on macOS.
This skill stands out by using a dual-engine approach: SQLite for near-instant metadata searches and optimized AppleScript for direct message manipulation. Whether you are building an automated triage system or simply need a faster way to query your archives, this integration provides the necessary tools to handle mail efficiently.
Apple Mail Use Cases
- Automating the sorting and deletion of spam or notification emails in bulk.
- Building custom AI agents that can read and summarize daily executive briefs.
- Rapidly searching through years of archived messages in milliseconds using SQLite.
- Integrating email sending and replying capabilities into developer CI/CD workflows.
- Monitoring specific mailboxes for new messages and triggering local system actions.
How Apple Mail Works
- The skill accesses the local Mail database located in the user Library to retrieve message metadata and account structures.
- For search operations, it creates a temporary copy of the Envelope Index to allow safe, concurrent querying while Mail.app is active.
- It uses a position-optimized AppleScript technique that jumps directly to specific message indices, avoiding the slow iteration typical of standard AppleScript mail automation.
- Commands are executed through modular bash scripts that handle everything from account listing to batch message processing.
- Real-time feedback is provided during sync operations by monitoring database changes to detect when a mailbox refresh is complete.
Apple Mail Setup
To use this integration within the Openclaw Skills ecosystem, ensure you are running macOS with Mail.app configured.
# Navigate to the skill directory
cd apple-mail
# Verify your accounts are visible to the system
scripts/mail-accounts.sh
# Perform an initial refresh to sync the local database
scripts/mail-refresh.sh
Note: You must grant your terminal or IDE the necessary 'Automation' permissions in System Settings to control Mail.app via AppleScript.
Apple Mail Data Schema & Taxonomy
The skill organizes data by extracting fields from the macOS Envelope Index and formatting them for CLI consumption.
| Attribute | Description |
|---|---|
| Message ID | The internal identifier used for direct message access |
| Read Status | A boolean flag (displayed as ● for unread) |
| Date | The timestamp of when the email was received |
| Sender | The display name or email address of the origin |
| Subject | The header text of the email |
| Account UUID | Used internally to map messages to specific mail providers |
Apple Mail Advanced Features
- Fast Search: Executes metadata queries in ~50ms by bypassing the Mail.app GUI and querying the SQLite index directly.
- Smart Sync Detection: Automatically detects when a mailbox has finished downloading new messages by monitoring database stability.
- Batch Operations: Supports processing multiple message IDs simultaneously for reading, deleting, or marking as read/unread.
- Gmail Compatibility: Includes specific logic to handle the [Gmail]/ prefix required for special folders like Sent and Trash.
- Safe DB Access: Uses temporary database shadowing to prevent locking issues while the mail client is open.
SKILL.md
Loading
Related Openclaw Skills
Apple Contacts
A macOS-native skill that enables AI agents to query the Contacts.app for names, phone numbers, and email addresses using AppleScript.
Apple Calendar for macOS
A macOS-native integration enabling AI agents to perform full CRUD operations and event management on Calendar.app using AppleScript.
Polymarket US Prediction Markets
Access real-time prediction market data and execute trades on Polymarket US using Openclaw Skills.
Z.AI Web Search API Skill
An AI-powered web search skill optimized for Chinese-language content and LLM-ready structured data.
Apple Music
A powerful integration for macOS that allows AI agents to control playback, manage library content, and handle AirPlay routing through AppleScript and the MusicKit API.
Apple Photos Integration
A specialized tool for searching, listing, and exporting media from the macOS Photos.app library using script-driven SQLite queries.
METADATA
Featured*
