Apple Mail Search

Fast Apple Mail search via SQLite on macOS. Search emails by subject, sender, date, attachments - results in ~50ms vs 8+ minutes with AppleScript. Use when asked to find, search, or list emails.

Security Scan

The skill's stated purpose (fast Apple Mail search via the Envelope Index) matches its instructions, but the SKILL.md expects an external 'mail-search' binary (not bundled) and the registry metadata and SKILL.md disagree about required binaries—these inconsistencies warrant caution.

Purpose & Capability

Name/description, technical details, and example commands all align with a tool that queries Mail's Envelope Index via sqlite. However the SKILL.md metadata declares sqlite3 as a required binary while the registry metadata showed no required binaries—an inconsistency. Also the instructions assume a 'mail-search' executable is available to copy to /usr/local/bin, but this skill bundle contains no code files or binary.

Instruction Scope

Instructions are narrowly scoped to reading Mail.app's Envelope Index (~/Library/Mail/.../MailData/Envelope Index) and using sqlite3; that is coherent with the purpose. The concerning part is explicit install guidance to copy an external 'mail-search' binary into /usr/local/bin despite no binary being packaged. The doc does not instruct any unrelated data collection or external network exfiltration, but the install step gives an agent the ability to place a binary on the system if the agent follows it.

Install Mechanism

There is no formal install spec in the registry (instruction-only), which is low-risk. But SKILL.md requires an external binary to be copied into /usr/local/bin — since the binary is not included, the user/agent would need to obtain it (e.g., from the listed GitHub homepage). Downloading and installing an unsigned binary from an external source is higher risk; the skill does not provide an official, auditable install mechanism in-package.

Credentials

The skill requests no environment variables, no credentials, and no config paths beyond the Mail Envelope Index path (which the tool legitimately needs to read). There are no unexplained secret requests.

Persistence & Privilege

Skill flags show no always:true or other elevated persistence. The only persistence-like action in the instructions is copying a CLI binary to /usr/local/bin (normal for CLI tools) which requires write privileges but is not intrinsic to the skill bundle itself.

What to consider before installing

This skill appears to do what it says (query Mail's Envelope Index with sqlite), but there are important inconsistencies to resolve before installing or running anything: 1) The SKILL.md expects a 'mail-search' executable to be copied into /usr/local/bin, yet the skill package contains no binary—verify where that binary is supposed to come from (the GitHub homepage may host it). 2) The SKILL.md metadata requires sqlite3 but the registry metadata reported none—ensure sqlite3 is the only external dependency. Before installing: inspect the upstream GitHub repository and its source code, prefer building the tool from source rather than downloading unsigned releases, verify the binary's integrity (checksums/signatures), and review the code to ensure it only reads the Mail Envelope Index and does not transmit data externally. Avoid running cp/chmod from untrusted instructions; instead fetch/install the tool manually in a controlled environment. If you must grant the tool access to Mail data, consider running it on a disposable account or VM and back up Mail data first. If you want more assurance, provide the repository link and I can point out exact files/lines to review (or confirm whether a bundled binary should have been included).

Search Apple Mail.app emails instantly via SQLite. ~50ms vs 8+ minutes with AppleScript.

Installation

# Copy mail-search to your PATH
cp mail-search /usr/local/bin/
chmod +x /usr/local/bin/mail-search

Usage

mail-search subject "invoice"           # Search subjects
mail-search sender "@amazon.com"        # Search by sender email
mail-search from-name "John"            # Search by sender name
mail-search to "[e-mail]"  # Search sent mail
mail-search unread                      # List unread emails
mail-search attachments                 # List emails with attachments
mail-search attachment-type pdf         # Find PDFs
mail-search recent 7                    # Last 7 days
mail-search date-range 2025-01-01 2025-01-31
mail-search open 12345                  # Open email by ID
mail-search stats                       # Database statistics

Options

-n, --limit N    Max results (default: 20)
-j, --json       Output as JSON
-c, --csv        Output as CSV
-q, --quiet      No headers
--db PATH        Override database path

Examples

# Find bank statements from last month
mail-search subject "statement" -n 50

# Get unread emails as JSON for processing
mail-search unread --json | jq '.[] | .subject'

# Find all PDFs from a specific sender
mail-search sender "@bankofamerica.com" -n 100 | grep -i statement

# Export recent emails to CSV
mail-search recent 30 --csv > recent_emails.csv

Why This Exists

Method	Time for 130k emails
AppleScript iteration	8+ minutes
Spotlight/mdfind	Broken since Big Sur
SQLite (this tool)	~50ms

Apple removed the emlx Spotlight importer in macOS Big Sur. This tool queries the Envelope Index SQLite database directly.

Technical Details

Database: ~/Library/Mail/V{9,10,11}/MailData/Envelope Index

Key tables:

• messages - Email metadata (dates, flags, FKs)
• subjects - Subject lines
• addresses - Email addresses and display names
• recipients - TO/CC mappings
• attachments - Attachment filenames

Limitations:

• Read-only (cannot compose/send)
• Metadata only (bodies in .emlx files)
• Mail.app only (not Outlook, etc.)

Advanced: Raw SQL

For custom queries, use sqlite3 directly:

sqlite3 -header -column ~/Library/Mail/V10/MailData/Envelope\ Index "
SELECT m.ROWID, s.subject, a.address
FROM messages m
JOIN subjects s ON m.subject = s.ROWID
LEFT JOIN addresses a ON m.sender = a.ROWID
WHERE s.subject LIKE '%your query%'
ORDER BY m.date_sent DESC
LIMIT 20;
"

License

MIT