apple-mail-search

• You need to find emails by subject, sender, or date.
• You want to list available mailboxes and accounts.
• You need fast search without opening Mail.app.
• You want to read email content from specific messages.

1. Reads Apple Mail's Envelope Index SQLite database at ~/Library/Mail/V10/MailData/
2. Joins messages with subjects, addresses, and mailboxes tables
3. Returns metadata (subject, sender, date, mailbox) for matching messages
4. Can retrieve full email content from .emlx files when needed

The database is always up-to-date as Mail.app writes to it in real-time.

```bash

# List all configured mail accounts

mail-search accounts

# List all mailboxes for an account

mail-search mailboxes --account "Wasc.me"

# Search by subject (case-insensitive, substring match)

mail-search search --subject "invoice"

# Search by sender

mail-search search --sender "github.com"

# Search in message body/preview

mail-search search --body "tracking number"

# Search within a specific account

mail-search search --subject "receipt" --account "iCloud"

# Search within a specific mailbox

mail-search search --subject "order" --mailbox "INBOX" --account "Wasc.me"

# Search by date range

mail-search search --subject "meeting" --after "2026-01-01" --before "2026-01-31"

# Limit results

mail-search search --sender "amazon" --limit 10

# Get recent messages

mail-search recent --limit 20

# Get recent messages from a specific account

mail-search recent --account "Wasc.me" --limit 10

# Read full content of a message by ID

mail-search read --id 329402

# Dump messages from a specific date

mail-search dump --date "2026-01-25"

```

Commands

| Command | Description |

| ----------- | ---------------------------------------- |

| accounts | List all configured mail accounts |

| mailboxes | List mailboxes for an account |

| search | Search messages by subject, sender, date |

| recent | Get most recent messages |

| read | Read full content of a specific message |

| dump | Dump all messages from a specific date |

Search Flags

| Flag | Short | Description |

| ----------------------- | ----- | ----------------------------------------------- |

| --subject | -s | Search in subject (case-insensitive substring) |

| --sender | -f | Search in sender address or name |

| --body | -b | Search in message body/preview (uses summaries) |

| --account | -a | Filter to specific account |

| --mailbox | -m | Filter to specific mailbox |

| --after | | Messages received after this date |

| --before | | Messages received before this date |

| --limit | -n | Maximum results (default: 50) |

| --unread | -u | Only show unread messages |

| --flagged | -F | Only show flagged messages |

Output Format

```

[329402] 2026-01-25 22:39 | notifications@github.com (vercel[bot])

[shadcn-ui/ui] fix: copy button copies full code even when collapsed (PR #9451)

Mailbox: Wasc.me/INBOX

```

• First line: Message ID, date/time, sender
• Second line: Subject
• Third line: Account/Mailbox path

| Operation | Time |

| --------------------- | ----- |

| List accounts | <0.1s |

| Search (any criteria) | <0.3s |

| Read message content | <0.2s |

Key tables in Envelope Index:

• messages - Message metadata (sender, subject refs, dates, flags)
• subjects - Subject text (normalized)
• addresses - Email addresses and display names
• mailboxes - Mailbox URLs (account/folder structure)
• summaries - Email preview snippets

• Read-only access to Mail's SQLite database
• No data is modified or written
• No network requests; all local operations
• Searches happen locally; nothing leaves your machine

• "Database not found": Ensure Apple Mail has been opened at least once
• "Database is locked": Mail.app may be syncing; retry in a moment
• Empty results: Check account/mailbox names with accounts and mailboxes commands
• Missing message content: Some messages may be partially downloaded (IMAP); full content requires Mail.app to download

• Body search uses the summaries table (email previews), not full message content
• For full-text body search, use read --id to get complete message content
• Attachments are not searchable via this tool
• Deleted messages (in Trash) may still appear until permanently deleted