Gmailtail：一款强大的 Gmail 消息监控工具

在数字化办公时代，我们每天都会收到来自不同渠道的大量电子邮件。然而，手动查看每一封邮件效率低下且容易错过重要信息。好消息是，有一个名为 Gmailtail 的命令行工具，能够帮助我们实时监控 Gmail 邮件并以 JSON 格式输出，便于与其他工具集成和自动化处理。

什么是 Gmailtail？

Gmailtail 是一款专为自动化、监控和集成设计的 Gmail 消息监控工具。它具备以下核心功能：

  • 实时监控 ：通过 --tail 模式，可以持续监测新邮件，确保不会错过任何重要信息。
  • 灵活的过滤功能 ：支持按发件人、主题、标签、附件等多种条件进行过滤，方便用户只关注自己感兴趣的邮件。
  • 断点续传 ：借助检查点支持，用户可以从上次停止的地方继续监控，避免重复处理已查看的邮件。
  • 多种输出格式 ：支持 JSON、JSON Lines、紧凑格式等多种输出格式，满足不同场景下的数据处理需求。
  • 配置文件 ：采用 YAML 配置文件，方便用户设置复杂的监控规则和参数。
  • 强大的 Gmail 搜索工具语法 ：完全支持 Gmail 的搜索查询语法，让用户能够精准地定位目标邮件。
  • 简单的身份验证 ：支持 OAuth2 和服务账户两种身份验证方式，确保安全访问 Gmail 数据。

快速入门

安装 Gmailtail

推荐使用 uv 进行安装，以下是具体步骤：

  1. 如果尚未安装 uv，可以通过以下命令安装：

curl -LsSf https://astral.sh/uv/install.sh | sh


  2. 克隆 Gmailtail 项目并进行设置：
     ```bash
git clone https://github.com/c4pt0r/gmailtail.git
cd gmailtail
uv sync

配置 Google API 凭据

要使用 Gmailtail，需要先配置 Google API 凭据：

  1. 登录 👉Google Cloud Console。
  2. 创建一个新项目或选择一个现有项目。
  3. 启用 Gmail API。
  4. 创建凭据（为桌面应用程序创建 OAuth 2.0 客户端 ID）。
  5. 下载凭据 JSON 文件。

运行 Gmailtail

完成上述步骤后，即可运行 Gmailtail：

uv run gmailtail --credentials credentials.json --tail

使用场景示例

基本监控

  • 监控所有新邮件 ：只需运行 gmailtail --tail，即可实时查看所有新收到的邮件。
  • 监控特定发件人的邮件 ：如果只想关注某个特定发件人（如 GitHub 通知），可以使用 gmailtail --from "noreply@github.com" --tail。
  • 使用 Gmail 搜索专业搜索查询监控邮件 ：例如，使用 gmailtail --query "subject:alert OR subject:error" --tail，可以监控主题包含 “alert” 或 “error” 的邮件。

过滤选项

  • 仅监控未读邮件 ：通过添加 --unread-only 参数，只查看尚未阅读的邮件，命令为 gmailtail --unread-only --tail。
  • 监控带有附件的邮件并包含附件信息 ：使用 gmailtail --has-attachment --include-attachments --tail，能够获取带有附件的邮件以及附件的详细信息。
  • 监控特定标签的邮件 ：比如只想查看标记为 “重要” 和 “工作” 的邮件，可以运行 gmailtail --label important --label work --tail。
  • 自特定日期以来的邮件 ：如果只想查看从某个日期（如 2025 年 1 月 1 日）之后的邮件，命令为 gmailtail --since "2025-01-01T00:00:00Z" --tail。

输出格式

  • 漂亮的 JSON 输出 ：使用 gmailtail --format json --pretty --tail，以易于阅读的格式查看邮件的 JSON 数据。
  • JSON Lines 格式（每行一个 JSON） ：运行 gmailtail --format json-lines --tail，生成适合流处理的数据格式。
  • 紧凑格式 ：通过 gmailtail --format compact --tail，获取简洁的邮件信息展示。
  • 包含邮件正文 ：若需要获取邮件正文内容，可添加 --include-body 参数，并通过 --max-body-length 参数控制正文的最大长度，例如 gmailtail --include-body --max-body-length 500 --tail。
  • 自定义字段输出 ：如果只想查看特定字段（如邮件 ID、主题、发件人、时间戳），可以使用 gmailtail --fields "id,subject,from,timestamp" --tail。

检查点管理

  • 从上次检查点恢复监控 ：通过 gmailtail --resume --tail，从上次停止的检查点继续监控邮件。
  • 重置检查点并重新开始 ：若想清除之前的检查点并重新开始监控，使用 gmailtail --reset-checkpoint --tail。
  • 自定义检查点文件 ：可以指定检查点文件的路径，例如 gmailtail --checkpoint-file ./my-checkpoint --tail。

使用配置文件

创建一个配置文件（如 gmailtail.yaml），将相关设置放入其中，然后通过 gmailtail --config-file gmailtail.yaml 调用配置文件来运行 Gmailtail。这在需要设置复杂的监控规则时非常方便。

高级用法与 jq 结合

jq 是一个轻量级的命令行 JSON 处理器，与 Gmailtail 结合可以实现强大的数据分析功能。以下是一些示例：

  • 提取发件人邮箱和主题 ：gmailtail --format json-lines --tail | jq -r '.from.email + ": " + .subject，可以快速获取每封邮件的发件人和主题信息。
  • 按特定发件人过滤并获取时间戳 ：gmailtail --format json-lines --tail | jq -r 'select(.from.email == "noreply@github.com") | .timestamp'，只查看来自 GitHub 的邮件的时间戳。
  • 按发件人统计邮件数量 ：gmailtail --format json-lines --once | jq -r '.from.email' | sort | uniq -c | sort -nr，可以统计每个发件人发送的邮件数量。
  • 获取所有唯一标签 ：gmailtail --format json-lines --once | jq -r '.labels[]?' | sort | uniq，查看所有邮件中出现的唯一标签。
  • 提取带有附件的邮件并展示附件信息 ：gmailtail --format json-lines --include-attachments --tail | jq 'select(.attachments | length > 0) | {subject, from: .from.email, attachments: [.attachments[].filename]}'，获取带有附件的邮件的标题、发件人和附件文件名。
  • 监控紧急邮件并发送桌面通知（macOS） ：gmailtail --query "label:urgent OR subject:urgent" --format json-lines --tail | jq -r '.subject' | while read subject; do osascript -e "display notification \"$subject\" with title \"Urgent Email\""; done，当收到标记为 “紧急” 或主题包含 “urgent” 的邮件时，会在 macOS 上显示桌面通知。
  • 提取邮件正文并保存到文件 ：gmailtail --include-body --format json-lines --once | jq -r '"\(.id).txt|\(.body // .snippet)"' | while IFS='|' read filename content; do echo "$content" > "$filename"; done，将邮件正文或片段保存到以邮件 ID 命名的文本文件中。
  • 监控 GitHub 通知并提取 PR/issue 号码 ：gmailtail --from "notifications@github.com" --format json-lines --tail | jq -r 'select(.subject | test("Pull Request|Issue")) | .subject | capture(".*#(?<number>[0-9]+).*") | .number'，从 GitHub 通知邮件中提取拉取请求或问题的编号。
  • 创建每日邮件活动摘要 ：gmailtail --since "$(date -d 'today' '+%Y-%m-%dT00:00:00Z')" --format json-lines --once | jq -r '[group_by(.from.email) | .[] | {sender: .[0].from.email, count: length}] | sort_by(.count) | reverse'，生成当日按发件人分组的邮件统计摘要。
  • 监控邮件正文中包含特定关键字并发出警报 ：gmailtail --include-body --format json-lines --tail | jq -r 'select(.body | test("error|fail|alert"; "i")) | "ALERT: \(.from.email) - \(.subject)"'，当邮件正文中出现 “error”、“fail” 或 “alert” 等关键字时，会输出警报信息。
  • 提取并格式化会议邀请 ：gmailtail --query "has:attachment filename:ics" --include-attachments --format json-lines --tail | jq '{meeting: .subject, organizer: .from.email, time: .timestamp, location: (.body | capture("Location:.*(?<loc>.*)")? | .loc // "N/A")}'，对带有日历附件的会议邀请邮件进行信息提取和格式化。

命令行选项详解

身份验证

  • --credentials PATH：指定 OAuth2 凭据文件的路径。
  • --auth-token PATH：用于服务账户身份验证的令牌文件路径。
  • --cached-auth-token PATH：缓存的身份验证令牌文件路径，默认为 ~/.gmailtail/tokens。

过滤

  • --query QUERY：使用 Gmail 搜索更多关于这个工具的使用问题。下面是一些常见问题及解答：

如何处理大量邮件？

Gmailtail 提供了 --max-messages N 参数，可以限制处理的最大邮件数量。例如，gmailtail --max-messages 100 --tail 只会处理最多 100 封邮件。

可以同时使用多个过滤条件吗？

是的，可以同时使用多个过滤条件。例如，gmailtail --from "example@domain.com" --subject "important" --tail 会同时根据发件人和主题进行过滤。

如果忘记了一些参数的具体用法怎么办？

可以随时运行 gmailtail --help 查看所有可用的命令行选项及其说明。

希望这篇博客文章能够帮助你更好地了解和使用 Gmailtail 工具。如果你有任何疑问或建议，欢迎在评论区留言讨论。索语法进行过滤。

  • --from EMAIL：按发件人邮箱地址过滤。
  • --to EMAIL：按收件人邮箱地址过滤。
  • --subject PATTERN：按主题进行过滤，支持正则表达式。
  • --label LABEL：按标签过滤，可以多次使用以指定多个标签。
  • --has-attachment：仅包含有附件的邮件。
  • --unread-only：仅包含未读邮件。
  • --since DATETIME：从指定的 ISO 8601 时间开始过滤邮件。

输出

  • --format FORMAT：指定输出格式，可选值为 json、json-lines、compact。
  • --fields FIELDS：指定要包含的字段列表，用逗号分隔。
  • --include-body：在输出中包含邮件正文。
  • --include-attachments：在输出中包含附件信息。
  • --max-body-length N：设置正文的最大长度，默认为 1000。
  • --pretty：以美观的格式打印 JSON 输出。

监控

  • --tail, -f：启用持续监控模式，类似于 tail -f 命令。
  • --once：只运行一次然后退出。
  • --poll-interval N：设置轮询间隔，单位为秒，默认为 30。
  • --batch-size N：每个批次处理的消息数量，默认为 10。

检查点

  • --checkpoint-file PATH：指定检查点文件的路径。
  • --checkpoint-interval N：设置检查点保存间隔，单位为秒，默认为 60。
  • --resume：从上次的检查点恢复监控。
  • --reset-checkpoint：重置检查点。

其他

  • --verbose, -v：开启详细输出模式。
  • --quiet：静默模式，只输出邮件 JSON 数据。
  • --log-file PATH：指定日志文件的路径。
  • --config-file PATH：指定配置文件的路径。
  • --dry-run：模拟运行，不实际进行处理。

输出格式示例

以下是 Gmailtail 输出的 JSON 格式示例：

{
  "id": "18234567890abcdef",
  "threadId": "18234567890abcdef",
  "timestamp": "2025-07-01T10:30:00Z",
  "subject": "GitHub 通知",
  "from": {
    "name": "GitHub",
    "email": "noreply@github.com"
  },
  "to": [
    {
      "name": "John Doe",
      "email": "john@example.com"
    }
  ],
  "labels": ["INBOX", "UNREAD"],
  "snippet": "您有一个新的拉取请求...",
  "body": "完整的邮件正文内容...",
  "attachments": [
    {
      "filename": "报告.pdf",
      "mimeType": "application/pdf",
      "size": 1024
    }
  ]
}

使用场景

  • 监控系统 ：可以设置 Gmailtail 监控特定模式的邮件，例如服务器故障警报或业务关键指标的更新，从而实现及时的通知和响应。
  • 自动化工作流 ：根据邮件内容触发自动化操作，如收到订单确认邮件后自动更新库存管理系统，或者在收到特定关键词的邮件时自动创建工单。
  • 数据分析 ：收集邮件数据并进行分析，了解邮件流量趋势、平均响应时间、常见主题等信息，以优化业务流程或客户服务。
  • 系统集成 ：将 Gmail 数据整合到其他工具和系统中，如将邮件信息导入到客户关系管理系统（CRM）或项目管理工具中，实现数据的统一管理和利用。
  • 邮件备份 ：以结构化的 JSON 格式归档重要邮件，确保邮件数据的安全存储和长期可访问性。
  • CI/CD 流程 ：在持续集成和持续部署（CI/CD）流程中监控构建通知和警报邮件，以便及时发现和处理构建失败或部署问题。

配置文件示例

创建一个 gmailtail.yaml 配置文件，示例内容如下：

# 认证设置
auth:
  credentials_file: ~/.config/gmailtail/credentials.json
  # auth_token: ~/.config/gmailtail/service-account.json
  cached_auth_token: ~/.config/gmailtail/tokens

# 邮件过滤设置
filters:
  query: "label:important"
  # from: "noreply@github.com"
  # to: "me@example.com"
  # subject: "alert|error|warning"
  # labels: ["important", "inbox"]
  # has_attachment: true
  unread_only: true
  # since: "2025-01-01T00:00:00Z"

# 输出格式设置
output:
  format: json-lines
  include_body: true
  include_attachments: true
  max_body_length: 500
  pretty: false
  # fields: ["id", "subject", "from", "timestamp", "labels"]

# 监控行为设置
monitoring:
  poll_interval: 60
  batch_size: 20
  tail: true
  # max_messages: 1000

# 检查点设置
checkpoint:
  checkpoint_file: ~/.config/gmailtail/checkpoint
  checkpoint_interval: 120
  resume: true

# 日志设置
verbose: false
quiet: false
# log_file: ~/.config/gmailtail/gmailtail.log

身份验证设置

OAuth2（个人使用推荐）

  1. 登录 👉Google Cloud Console。
  2. 创建或选择一个项目。
  3. 启用 Gmail API。
  4. 在 “凭据” 页面中，点击 “创建凭据” → “OAuth 2.0 客户端 ID”。
  5. 选择 “桌面应用” 类型。
  6. 下载生成的 JSON 文件。
  7. 使用 --credentials path/to/credentials.json 指定凭据文件路径。

服务账户（适用于服务器 / 自动化环境）

  1. 在 Google Cloud Console 的 “凭据” 页面中，创建 “服务账户”。
  2. 下载生成的 JSON 密钥文件。
  3. 使用 --service-account path/to/service-account.json 指定服务账户密钥文件路径。

需要注意的是，服务账户需要进行域范围的授权才能访问 Gmail。

常见问题（FAQ）

Gmailtail 支持同时监控多个邮箱吗？

目前，Gmailtail 主要针对单个 Gmail 邮箱进行监控。如果你需要监控多个邮箱，可以为每个邮箱分别设置不同的 Gmailtail 实例，并使用不同的配置文件和凭据进行运行。

如何处理 Gmailtail 输出的 JSON 数据？

可以使用各种编程语言和工具来处理 JSON 数据。例如，使用 Python 的 json 模块解析数据，或者使用 jq 命令行工具进行简单的数据提取和转换，如在前面高级用法部分所展示的示例。

Gmailtail 是否支持邮件自动回复功能？

Gmailtail 本身不直接支持自动回复邮件功能。不过，你可以结合其他工具和 API，根据 Gmailtail 输出的邮件数据来实现自动回复逻辑。例如，使用 Gmail API 的发送邮件功能，在接收到特定条件的邮件后，发送自动生成的回复邮件。

如何确保 Gmailtail 的稳定运行和数据安全性？

为了确保稳定运行，建议定期检查 Gmailtail 的日志文件，监控其运行状态，并设置适当的错误处理和恢复机制。在数据安全性方面，妥善保管身份验证凭据，避免将敏感信息暴露给未经授权的用户。同时，遵循 Google 的 API 使用政策和最佳实践，合理设置监控频率和数据处理逻辑，以保护用户隐私和数据安全。

Gmailtail 是否可以与其他消息队列或流处理系统集成？

是的，由于 Gmailtail 支持输出 JSON 格式的邮件数据，并且可以以 JSON Lines 等适合流处理的格式输出，因此可以很容易地与其他消息队列（如 RabbitMQ、Kafka）或流处理系统（如 Apache Flink、Apache Storm）集成。通过将 Gmailtail 输出的数据发送到消息队列或流处理系统中，可以实现更复杂的数据处理和分析流程，例如实时邮件内容分析、邮件流量监控、事件驱动的自动化工作流等。