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.

⭐3stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️5downloads

When & Why to Use This Skill

This Claude skill enables lightning-fast searching of Apple Mail on macOS by querying the local SQLite database directly. It bypasses slow AppleScript methods and broken Spotlight indexes, delivering search results in approximately 50ms compared to several minutes. It is designed for users who need to instantly retrieve email metadata—such as subjects, senders, dates, and attachments—to enhance their productivity and information retrieval workflows within Claude.

Use Cases

  • Locate specific documents: Quickly find invoices, receipts, or bank statements by searching for keywords in the subject line across thousands of emails.
  • Filter by attachment: Identify and list all emails containing specific attachment types, such as PDFs or images, from a particular sender.
  • Email history retrieval: Gather a chronological list of communications from a specific contact to provide context for a project or meeting.
  • Unread mail management: Instantly list all unread messages to prioritize tasks and ensure no important communication is missed.
  • Data Export for Analysis: Export recent email metadata to JSON or CSV formats for further processing, reporting, or integration with other productivity tools.
nameapple-mail-search
descriptionFast 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.
homepagehttps://github.com/steipete/clawdbot
metadata{"clawdbot":{"emoji":"📬","os":["darwin"],"requires":{"bins":["sqlite3"]}}}

Apple Mail Search

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 "recipient@example.com"  # 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