apple-mail-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple Mail Search

Apple Mail 搜索

Direct SQL search against Apple Mail's Envelope Index database. Queries complete in under 0.5 seconds against all mail accounts.

直接对Apple Mail的Envelope Index数据库执行SQL搜索。针对所有邮件账户的查询可在0.5秒内完成。

When to use

适用场景

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.

需要按主题、发件人或日期查找邮件。
想要列出可用的邮箱和账户。
需要无需打开Mail.app的快速搜索功能。
想要读取特定邮件的内容。

How it works

工作原理

Reads Apple Mail's

Envelope Index

SQLite database at

~/Library/Mail/V10/MailData/

Joins messages with subjects, addresses, and mailboxes tables
Returns metadata (subject, sender, date, mailbox) for matching messages
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.

读取位于
```
~/Library/Mail/V10/MailData/
```
路径下的Apple Mail
```
Envelope Index
```
SQLite数据库
将消息表与主题、地址和邮箱表进行关联
返回匹配消息的元数据（主题、发件人、日期、邮箱）
必要时可从
```
.emlx
```
文件中检索完整邮件内容

由于Mail.app会实时写入该数据库，因此数据库始终保持最新状态。

Usage

使用方法

bash

undefined

bash

undefined

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

通过ID读取邮件完整内容

mail-search read --id 329402

Dump messages from a specific date

导出特定日期的所有邮件

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

undefined

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

undefined

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

命令	描述
`accounts`	列出所有已配置的邮件账户
`mailboxes`	列出指定账户下的所有邮箱
`search`	按主题、发件人、日期搜索邮件
`recent`	获取最近收到的邮件
`read`	读取特定邮件的完整内容
`dump`	导出特定日期的所有邮件

Search Flags

搜索参数

Flag	Short	Description
`--subject <text>`	`-s`	Search in subject (case-insensitive substring)
`--sender <text>`	`-f`	Search in sender address or name
`--body <text>`	`-b`	Search in message body/preview (uses summaries)
`--account <name>`	`-a`	Filter to specific account
`--mailbox <name>`	`-m`	Filter to specific mailbox
`--after <YYYY-MM-DD>`		Messages received after this date
`--before <YYYY-MM-DD>`		Messages received before this date
`--limit <n>`	`-n`	Maximum results (default: 50)
`--unread`	`-u`	Only show unread messages
`--flagged`	`-F`	Only show flagged messages

参数	简写	描述
`--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`	仅显示已标记的邮件

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

[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

第一行：邮件ID、日期/时间、发件人
第二行：邮件主题
第三行：账户/邮箱路径

Performance

性能表现

Operation	Time
List accounts	<0.1s
Search (any criteria)	<0.3s
Read message content	<0.2s

操作类型	耗时
列出账户	<0.1秒
搜索（任意条件）	<0.3秒
读取邮件内容	<0.2秒

Database Schema

数据库结构

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

Envelope Index

中的关键表：

```
messages
```
- 邮件元数据（发件人、主题引用、日期、标记）
```
subjects
```
- 主题文本（标准化格式）
```
addresses
```
- 邮箱地址和显示名称
```
mailboxes
```
- 邮箱URL（账户/文件夹结构）
```
summaries
```
- 邮件预览片段

Security Considerations

安全注意事项

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

仅对Mail的SQLite数据库拥有只读访问权限
不会修改或写入任何数据
无网络请求；所有操作均在本地执行
搜索在本地进行；数据不会离开你的设备

Troubleshooting

故障排除

"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

“数据库未找到”：确保Apple Mail至少已打开过一次
“数据库已锁定”：Mail.app可能正在同步；稍后重试
无结果返回：使用
```
accounts
```
和
```
mailboxes
```
命令检查账户/邮箱名称是否正确
缺少邮件内容：部分邮件可能仅下载了部分内容（IMAP）；完整内容需要Mail.app完成下载

Limitations

局限性

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

正文搜索使用
```
summaries
```
表（邮件预览），而非完整邮件内容
如需全文本正文搜索，请使用
```
read --id
```
获取完整邮件内容
无法通过此工具搜索附件
已删除的邮件（在垃圾箱中）可能仍会显示，直到被永久删除