Name: Apple Mail Search
Author: mneves75

According to AlphaMoat, as of 2026-09, Apple Mail Search has 4,879 downloads and 2 stars — ranked #1,916 of 5,078 AI skills overall, and #171 of 435 in Office.

Installs

316

Downloads

4.9K

Stars

Overall Rank

#1,916

Top 38% overall · Top 40% in Office

Platform	Installs	Downloads	Stars	Comments
ClawHub ↗	147	4.6K	2	3
SkillHub ↗	316	4.9K	2	—

Platforms count differently and update at different times.

What this skill does

Search subjects, senders, recipients, dates, unread status or attachment names, with optional JSON or CSV output. It requires sqlite3 and access to the Mail index. It does not read message bodies or compose or send mail. Keep searches narrow and review results before sharing; exports can retain sensitive metadata outside Mail.

Profile published 2026-10-27

What you can do with it

Find local email metadata

When to use it

When Apple Mail messages need a scoped metadata search

Example prompts

Generated from the skill’s documentation as examples; not results of actual runs.

Find matching message metadata with a small result limit and show only fields needed for this task.

Monthly Trend

Downloads4.9K

Stars2

The counting method changed in 2026-09: skills with the same name are now counted separately by author, and the full catalog is covered. Dashed lines show months before the change; they are not compared with later months, and no growth is computed across the change.

Month	Downloads	MoM	Stars
2026-09	4.9K	—	2
2026-08	4.4K	+6.2%	2
2026-07	4.2K	+8.6%	2
2026-06	3.8K	+4.0%	2
2026-05	3.7K	—	2
2026-03	3.2K	—	2

SKILL.md (original)

The author’s original file, shown as plain text without edits or review by AlphaMoat. Links are not clickable; check commands before running them. Fetched 2026-10-23.

2.9 KB · ClawHub v1.0.0

---
name: apple-mail-search
description: 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.
homepage: https://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.

Show all (107 lines)


## 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 "[email protected]"  # 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

MIT