apple-mail-search

Apple Mail の検索

Apple Mail の Envelope Index データベースを直接 SQL 検索します。すべてのメールアカウントを対象としたクエリは 0.5 秒未満で完了します。

使用する場面

• 件名、送信者、日付でメールを検索したい場合。
• 利用可能なメールボックスとアカウントを一覧表示したい場合。
• Mail.app を開かずにすばやく検索したい場合。
• 特定のメッセージのメール本文を読みたい場合。

仕組み

1. ~/Library/Mail/V10/MailData/ にある Apple Mail の Envelope Index SQLite データベースを読み取ります。
2. メッセージを件名、アドレス、メールボックスの各テーブルと結合します。
3. 条件に一致するメッセージのメタデータ（件名、送信者、日付、メールボックス）を返します。
4. 必要に応じて、.emlx ファイルからメール本文全体を取得できます。

Mail.app がリアルタイムでデータベースに書き込むため、データベースは常に最新の状態です。

使い方

# 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"

コマンド

コマンド	説明
accounts	設定済みのすべてのメールアカウントを一覧表示します
mailboxes	アカウントのメールボックスを一覧表示します
search	件名、送信者、日付でメッセージを検索します
recent	最新のメッセージを取得します
read	特定のメッセージの本文全体を読み取ります
dump	特定の日付のすべてのメッセージを出力します

検索フラグ

フラグ	短縮形	説明
--subject <text>	-s	件名を検索します（大文字と小文字を区別しない部分一致）
--sender <text>	-f	送信者のアドレスまたは名前を検索します
--body <text>	-b	メッセージ本文／プレビューを検索します（要約を使用）
--account <name>	-a	特定のアカウントに絞り込みます
--mailbox <name>	-m	特定のメールボックスに絞り込みます
--after <YYYY-MM-DD>		この日付より後に受信したメッセージ
--before <YYYY-MM-DD>		この日付より前に受信したメッセージ
--limit <n>	-n	結果の最大数（デフォルト：50）
--unread	-u	未読メッセージのみを表示します
--flagged	-F	フラグ付きメッセージのみを表示します

出力形式

[329402] 2026-01-25 22:39 | [email protected] (vercel[bot])
        [shadcn-ui/ui] fix: copy button copies full code even when collapsed (PR #9451)
        Mailbox: Wasc.me/INBOX

• 1 行目：メッセージ ID、日付／時刻、送信者
• 2 行目：件名
• 3 行目：アカウント／メールボックスのパス

パフォーマンス

操作	時間
アカウントの一覧表示	<0.1s
検索（任意の条件）	<0.3s
メッセージ本文の読み取り	<0.2s

データベーススキーマ

Envelope Index の主なテーブル：

• messages - メッセージのメタデータ（送信者、件名の参照、日付、フラグ）
• subjects - 件名のテキスト（正規化済み）
• addresses - メールアドレスと表示名
• mailboxes - メールボックスの URL（アカウント／フォルダー構造）
• summaries - メールのプレビュー抜粋

セキュリティに関する考慮事項

• Mail の SQLite データベースへの読み取り専用アクセス
• データの変更や書き込みは行いません
• ネットワークリクエストはなく、すべてローカルで処理します
• 検索はローカルで実行され、マシンの外にデータが送信されることはありません

トラブルシューティング

• 「Database not found」：Apple Mail が少なくとも一度は起動されていることを確認してください
• 「Database is locked」：Mail.app が同期中の可能性があります。少し待ってから再試行してください
• 結果が空：accounts コマンドと mailboxes コマンドでアカウント名／メールボックス名を確認してください
• メッセージ本文が見つからない：メッセージが一部しかダウンロードされていない場合があります（IMAP）。本文全体を取得するには、Mail.app にダウンロードさせる必要があります

制限事項

• 本文検索では、メッセージ本文全体ではなく summaries テーブル（メールのプレビュー）を使用します
• 本文全体を全文検索するには、read --id を使用してメッセージ本文全体を取得してください
• このツールでは添付ファイルを検索できません
• 削除済みのメッセージ（ゴミ箱内）は完全に削除されるまで表示される場合があります