Back to Details

apple-mail

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Apple Mail

Apple Mail

Interact with Mail.app via AppleScript and SQLite. Run scripts from: 
cd {baseDir}
通过AppleScript和SQLite与Mail.app交互。从以下路径运行脚本：
cd {baseDir}

Commands

命令

CommandUsage
Refresh
scripts/mail-refresh.sh [account] [wait_seconds]
List recent
scripts/mail-list.sh [mailbox] [account] [limit]
Search
scripts/mail-search.sh "query" [mailbox] [limit]
Fast search
scripts/mail-fast-search.sh "query" [limit]
Read email
scripts/mail-read.sh <message-id> [message-id...]
Delete
scripts/mail-delete.sh <message-id> [message-id...]
Mark read
scripts/mail-mark-read.sh <message-id> [message-id...]
Mark unread
scripts/mail-mark-unread.sh <message-id> [message-id...]
Send
scripts/mail-send.sh "to@email.com" "Subject" "Body" [from-account] [attachment]
¹
Reply
scripts/mail-reply.sh <message-id> "body" [reply-all]
List accounts
scripts/mail-accounts.sh
List mailboxes
scripts/mail-mailboxes.sh [account]
命令使用方式
刷新
scripts/mail-refresh.sh [账户] [等待秒数]
列出最近邮件
scripts/mail-list.sh [邮箱] [账户] [数量限制]
搜索
scripts/mail-search.sh "查询内容" [邮箱] [数量限制]
快速搜索
scripts/mail-fast-search.sh "查询内容" [数量限制]
读取邮件
scripts/mail-read.sh <消息ID> [消息ID...]
删除邮件
scripts/mail-delete.sh <消息ID> [消息ID...]
标记为已读
scripts/mail-mark-read.sh <消息ID> [消息ID...]
标记为未读
scripts/mail-mark-unread.sh <消息ID> [消息ID...]
发送邮件
scripts/mail-send.sh "收件人邮箱" "主题" "正文" [发件账户] [附件]
¹
回复邮件
scripts/mail-reply.sh <消息ID> "回复内容" [是否回复所有人]
列出账户
scripts/mail-accounts.sh
列出邮箱
scripts/mail-mailboxes.sh [账户]

Refreshing Mail

刷新邮件

Force Mail.app to check for new messages:
bash
scripts/mail-refresh.sh                    # All accounts, wait up to 10s
scripts/mail-refresh.sh Google             # Specific account only
scripts/mail-refresh.sh "" 5               # All accounts, max 5 seconds
scripts/mail-refresh.sh Google 0           # Google account, no wait
Smart sync detection:
  • Script monitors database message count
  • Returns early when sync completes (no changes for 2s)
  • Reports new message count: 
    Sync complete in 2s (+3 messages)
Notes:
  • Mail.app must be running (script will error if not)
  • mail-list.sh
    does NOT auto-refresh — call 
    mail-refresh.sh
    first if you need fresh data
强制Mail.app检查新消息：
bash
scripts/mail-refresh.sh                    # 所有账户，最多等待10秒
scripts/mail-refresh.sh Google             # 仅指定账户
scripts/mail-refresh.sh "" 5               # 所有账户，最多等待5秒
scripts/mail-refresh.sh Google 0           # Google账户，不等待
智能同步检测：
  • 脚本监控数据库消息数量
  • 同步完成后提前返回（2秒内无变化）
  • 报告新消息数量：
    Sync complete in 2s (+3 messages)
注意：
  • Mail.app必须处于运行状态（若未运行，脚本会报错）
  • mail-list.sh
    不会自动刷新——如果需要最新数据，请先调用 
    mail-refresh.sh

Output Format

输出格式

List/search returns: 
ID | ReadStatus | Date | Sender | Subject
  • ●
    = unread, blank = read
列表/搜索返回格式：
ID | 已读状态 | 日期 | 发件人 | 主题
  • ●
    = 未读，空白 = 已读

Gmail Mailboxes

Gmail邮箱

⚠️ Gmail special folders need 
[Gmail]/
prefix:
Shows asUse
Spam
[Gmail]/Spam
Sent Mail
[Gmail]/Sent Mail
All Mail
[Gmail]/All Mail
Trash
[Gmail]/Trash
Custom labels work without prefix.
⚠️ Gmail特殊文件夹需要添加
[Gmail]/
前缀：
显示名称使用格式
垃圾邮件
[Gmail]/Spam
已发送邮件
[Gmail]/Sent Mail
所有邮件
[Gmail]/All Mail
垃圾箱
[Gmail]/Trash
自定义标签无需添加前缀。

Fast Search (SQLite)

快速搜索（SQLite）

✨ Now safe even if Mail.app is running — copies database to temp file first.
bash
scripts/mail-fast-search.sh "query" [limit]  # ~50ms vs minutes
Previously required Mail.app to be quit. Now works anytime by copying the database to a temp file before querying.
✨ 现在即使Mail.app运行时也能安全使用 —— 先将数据库复制到临时文件。
bash
scripts/mail-fast-search.sh "查询内容" [数量限制]  # 约50毫秒，对比常规搜索需数分钟
此前需要关闭Mail.app才能使用。现在通过先将数据库复制到临时文件再查询，可随时使用。

Performance Notes

性能说明

Speed by operation:
OperationSpeedNotes
mail-fast-search.sh
~50msSQLite query, fastest
mail-accounts.sh
<1sSimple AppleScript
mail-list.sh
1-3sAppleScript, direct mailbox access
mail-send.sh
1-2sCreates and sends message
mail-read.sh
~2sPosition-optimized lookup
mail-delete.sh
~0.5sPosition-optimized lookup
mail-mark-*.sh
~1.5sPosition-optimized lookup
Optimization technique: SQLite provides account UUID and approximate message position. AppleScript jumps directly to that position instead of iterating from the start.
Batch operations supported:
  • mail-read.sh 123 456 789
    - Read multiple (separator between each)
  • mail-delete.sh 123 456 789
    - Delete multiple
  • mail-mark-read.sh 123 456
    - Mark multiple as read
  • mail-mark-unread.sh 123 456
    - Mark multiple as unread
⚠️ No auto-refresh: Scripts read cached data. Call 
mail-refresh.sh
first if you need latest emails.
各操作速度：
操作速度说明
mail-fast-search.sh
约50毫秒SQLite查询，速度最快
mail-accounts.sh
<1秒简单AppleScript脚本
mail-list.sh
1-3秒AppleScript脚本，直接访问邮箱
mail-send.sh
1-2秒创建并发送消息
mail-read.sh
约2秒基于位置优化的查找
mail-delete.sh
约0.5秒基于位置优化的查找
mail-mark-*.sh
约1.5秒基于位置优化的查找
优化技术： SQLite提供账户UUID和消息近似位置。AppleScript直接跳转到该位置，而非从头开始遍历。
支持批量操作：
  • mail-read.sh 123 456 789
    - 读取多封邮件（用空格分隔ID）
  • mail-delete.sh 123 456 789
    - 删除多封邮件
  • mail-mark-read.sh 123 456
    - 标记多封邮件为已读
  • mail-mark-unread.sh 123 456
    - 标记多封邮件为未读
⚠️ 无自动刷新： 脚本读取缓存数据。如果需要最新邮件，请先调用 
mail-refresh.sh

Managing Emails

邮件管理

Delete emails:
bash
scripts/mail-delete.sh 12345                    # Delete one
scripts/mail-delete.sh 12345 12346 12347        # Delete multiple
Mark as read/unread:
bash
scripts/mail-mark-read.sh 12345 12346           # Mark as read
scripts/mail-mark-unread.sh 12345               # Mark as unread
Bulk operations example:
bash
undefined
删除邮件：
bash
scripts/mail-delete.sh 12345                    # 删除单封邮件
scripts/mail-delete.sh 12345 12346 12347        # 删除多封邮件
标记为已读/未读：
bash
scripts/mail-mark-read.sh 12345 12346           # 标记为已读
scripts/mail-mark-unread.sh 12345               # 标记为未读
批量操作示例：
bash
undefined

Find spam emails

查找垃圾邮件

scripts/mail-fast-search.sh "spam" 50 > spam.txt
scripts/mail-fast-search.sh "spam" 50 > spam.txt

Extract IDs and delete them

提取ID并删除

grep "^[0-9]" spam.txt | cut -d'|' -f1 | xargs scripts/mail-delete.sh
undefined
grep "^[0-9]" spam.txt | cut -d'|' -f1 | xargs scripts/mail-delete.sh
undefined

Reading Email Bodies

读取邮件正文

bash
scripts/mail-read.sh 12345              # Single email
scripts/mail-read.sh 12345 12346 12347  # Multiple emails (separated output)
Uses position-optimized lookup (~2s per message). Multiple emails are separated by 
========
with a summary at the end.
bash
scripts/mail-read.sh 12345              # 读取单封邮件
scripts/mail-read.sh 12345 12346 12347  # 读取多封邮件（输出内容用分隔符区分）
使用基于位置优化的查找（每封邮件约2秒）。多封邮件的输出内容用
========
分隔，末尾附汇总信息。

Errors

错误信息

ErrorCause
Mail.app is not running
Open Mail.app before running scripts
Account not found
Invalid account — check mail-accounts.sh
Message not found
Invalid/deleted ID — get fresh from mail-list.sh
Can't get mailbox
Invalid name — check mail-mailboxes.sh
Mail database not found
SQLite DB missing — check ~/Library/Mail/V{9,10,11}/MailData/
错误提示原因
Mail.app is not running
运行脚本前请打开Mail.app
Account not found
账户无效——请查看
mail-accounts.sh
的输出
Message not found
消息ID无效/已删除——请从
mail-list.sh
获取最新ID
Can't get mailbox
邮箱名称无效——请查看
mail-mailboxes.sh
的输出
Mail database not found
SQLite数据库缺失——请检查路径 ~/Library/Mail/V{9,10,11}/MailData/

Technical Details

技术细节

Database: 
~/Library/Mail/V{9,10,11}/MailData/Envelope Index
Message lookup method (optimized):
  1. Query SQLite for account UUID, mailbox path, and approximate position
  2. AppleScript accesses the specific account directly (no iteration)
  3. Search starts at the approximate position (±5 messages buffer)
  4. Falls back to full mailbox search only if position hint fails
Safety:
  • Fast search copies database to temp file before querying
  • Safe to use even if Mail.app is running
  • Delete/read/mark operations query live database but access is minimal
数据库路径： 
~/Library/Mail/V{9,10,11}/MailData/Envelope Index
消息查找方法（优化版）：
  1. 查询SQLite获取账户UUID、邮箱路径和消息近似位置
  2. AppleScript直接访问指定账户（无需遍历）
  3. 从近似位置开始搜索（±5条消息缓冲）
  4. 仅当位置提示失效时，才回退到全邮箱搜索
安全性：
  • 快速搜索会先将数据库复制到临时文件再查询
  • 即使Mail.app运行时也可安全使用
  • 删除/读取/标记操作会查询实时数据库，但访问量极小

Notes

注意事项

  • Message IDs are internal, get fresh ones from list/search
  • Confirm recipient before sending
  • AppleScript search is slow but comprehensive; SQLite is fast for metadata
  • Delete/mark operations support bulk actions (pass multiple IDs)
  • Always refresh before listing if you need the absolute latest emails
¹ Known limitation: Mail.app adds a leading blank line to sent emails. This is an AppleScript/Mail.app behavior that cannot be bypassed.
  • 消息ID为内部标识，请从列表/搜索结果中获取最新ID
  • 发送邮件前请确认收件人
  • AppleScript搜索速度慢但全面；SQLite搜索仅针对元数据，速度快
  • 删除/标记操作支持批量处理（传入多个ID）
  • 如果需要绝对最新的邮件，列出前务必先刷新
¹ 已知限制： Mail.app会在发送的邮件开头添加一个空白行。这是AppleScript/Mail.app的固有行为，无法规避。