apple-mail-search-2
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.
Best use case
apple-mail-search-2 is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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.
Teams using apple-mail-search-2 should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/apple-mail-search-2/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How apple-mail-search-2 Compares
| Feature / Agent | apple-mail-search-2 | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Apple Mail Search
Search Apple Mail.app emails instantly via SQLite. ~50ms vs 8+ minutes with AppleScript.
## Installation
```bash
# Copy mail-search to your PATH
cp mail-search /usr/local/bin/
chmod +x /usr/local/bin/mail-search
```
## Usage
```bash
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
```bash
# 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:
```bash
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
MITRelated Skills
npm-search
Search npm packages. Use for finding Node.js/JavaScript packages, libraries, and tools.
morning-email-rollup
Daily morning rollup of important emails and calendar events at 8am with AI-generated summaries
moltresearch
Molt Research 🦞 - AI research collaboration platform. Verify you're not human, propose research, contribute analysis, peer review, earn bounties, and build collective intelligence. Use when doing research, collaborating on papers, or exploring what AI agents are studying together.
email-sequence
When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," or "lifecycle emails." For in-app onboarding, see onboarding-cro.
local-rag-search
Efficiently perform web searches using the mcp-local-rag server with semantic similarity ranking. Use this skill when you need to search the web for current information, research topics across multiple sources, or gather context from the internet without using external APIs. This skill teaches effective use of RAG-based web search with DuckDuckGo, Google, and multi-engine deep research capabilities.
kagi-search
Web search using Kagi Search API. Use when you need to search the web for current information, facts, or references. Requires KAGI_API_KEY in the environment.
imap-smtp-email
Read and send email via IMAP/SMTP. Check for new/unread messages, fetch content, search mailboxes, mark as read/unread, and send emails with attachments. Works with any IMAP/SMTP server including Gmail, Outlook, 163.com, vip.163.com, 126.com, vip.126.com, 188.com, and vip.188.com.
imap-email
Read and manage email via IMAP (ProtonMail Bridge, Gmail, etc.). Check for new/unread messages, fetch content, search mailboxes, and mark as read/unread. Works with any IMAP server including ProtonMail Bridge.
grok-search
Search the web or X/Twitter using xAI Grok server-side tools (web_search, x_search) via the xAI Responses API. Use when you need tweets/threads/users from X, want Grok as an alternative to Brave, or you need structured JSON + citations.
google-search
Search the web using Google Custom Search Engine (PSE). Use this when you need live information, documentation, or to research topics and the built-in web_search is unavailable.
gemini-deep-research
Perform complex, long-running research tasks using Gemini Deep Research Agent. Use when asked to research topics requiring multi-source synthesis, competitive analysis, market research, or comprehensive technical investigations that benefit from systematic web search and analysis.
exa-web-search-free
Free AI search via Exa MCP. Web search for news/info, code search for docs/examples from GitHub/StackOverflow, company research for business intel. No API key needed.