Apple Mail Search for Openclaw

A lightning-fast CLI tool for searching Apple Mail metadata via direct SQLite database queries on macOS.

mneves75

v1.0.0

Jan 8, 2026

Install

Information

Skill.md

Install & Download

1. ClawHub CLI

The fastest way to install a skill directly from the registry.


                  npx clawhub@latest install apple-mail-search

2. Manual Installation

Copy the skill folder to one of these locations

Global

~/.openclaw/skills/

Workspace

<project>/skills/

Priority: Workspace > Local > Bundled

3. Prompt Installation

Copy this prompt to OpenClaw to install it automatically.


                  Help me install apple-mail-search 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 Search?

Apple Mail Search is a high-performance utility designed to solve the limitations of searching emails on macOS. Since the release of Big Sur, traditional Spotlight indexing for mail has often been unreliable, and AppleScript methods are notoriously slow, taking several minutes to process large mailboxes. This tool, integrated into the Openclaw Skills collection, queries the Envelope Index SQLite database directly, reducing search times from minutes to roughly 50 milliseconds.

By accessing the underlying database, this skill allows users to perform complex lookups for subjects, senders, attachments, and unread status without the overhead of the Mail.app interface. It is an essential utility for developers and power users who need to automate email workflows or retrieve data quickly within the Openclaw Skills framework.

Apple Mail Search Use Cases

Rapidly finding specific invoices or documents by searching subject lines across thousands of messages.
Filtering for unread emails or messages containing specific attachment types like PDFs or images.
Generating reports on recent email activity or sender statistics for data analysis.
Locating historical emails within a specific date range without waiting for the Mail.app UI to index.
Programmatically retrieving email metadata in JSON format for use in custom scripts or automations.

How Apple Mail Search Works

The tool locates the macOS Mail Envelope Index SQLite database, typically found in the Library folder under versioned directories (V9, V10, V11, etc.).
When a search command is issued, it executes optimized SQL JOIN queries against tables like messages, subjects, and addresses.
The results are fetched directly from the local disk, bypassing the Mail.app process entirely to ensure maximum speed.
Output is formatted according to user preference (Plain Text, JSON, or CSV) for immediate display or piping into other Openclaw Skills commands.

Apple Mail Search Setup

To install this tool for use with your Openclaw Skills, follow these steps:

# Move the mail-search utility to a directory in your PATH
cp mail-search /usr/local/bin/

# Grant execution permissions to the script
chmod +x /usr/local/bin/mail-search

Apple Mail Search Data Schema & Taxonomy

The skill interacts with the Apple Mail SQLite schema to provide structured access to your communication data. Below is the primary mapping used for Openclaw Skills integration:

Data Object	Source Table	Description
Metadata	`messages`	Core message data including dates, read/unread flags, and unique IDs.
Subjects	`subjects`	Indexed subject lines mapped to message entries.
Contacts	`addresses`	Sender and recipient email addresses and display names.
Files	`attachments`	Metadata regarding filenames and types attached to emails.

Apple Mail Search Advanced Features

Direct SQL access: Users can run raw SQLite queries for highly specific data extraction tasks.
Format flexibility: Supports --json and --csv flags, making it compatible with data processing tools like jq.
Attachment filtering: Specifically isolate emails based on attachment presence or file extension.
Database Statistics: Use the stats command to get a high-level overview of mailbox volume and indexing status within the Openclaw Skills environment.