Gmail API 搜索查询示例

Gmail API 搜索查询语法是如何工作的？

Gmail API 搜索查询的工作方式，是把一个 Gmail 搜索表达式传入 users.messages.list 的 q 查询参数。Google 在文档中说明，该参数支持与 Gmail 搜索框相同的查询格式，因此一次 HTTP 请求就能按发件人、收件人、主题、未读状态、日期、附件状态和邮件 ID 进行过滤。

关键限制在于 messages.list 返回的是邮件 ID，而不是完整正文。该方法默认返回 100 条结果，每页最多接受 500 条，所以一次命中 1,500 封邮件的搜索，在读取任何内容之前至少需要 3 次列表调用。官方的 users.messages.list 参考文档还指出，q 不能与 gmail.metadata 权限范围一起使用。

下面这个最小化的 Python 示例展示了直接调用 API 的形态。它搜索来自某个发件人的未读邮件，把首页结果限制在 50 个 ID，并把正文读取留给第二步。这种分离很重要，因为每次读取正文都是又一次 API 调用。

response = service.users().messages().list(
    userId="me",
    q="from:billing@stripe.com is:unread",
    maxResults=50,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

如何按发件人、收件人、主题和未读状态搜索？

Gmail 搜索查询可以在一个字符串里组合多个字段运算符，因此发件人、收件人、主题和未读过滤条件可以共存于同一个 q 值中。实践中的做法是在开始分页之前就把查询收窄，因为每多一条结果，之后都可能多一次 messages.get 调用。

Google 的示例包含 from:、rfc822msgid: 和 is:unread 等运算符。Gmail 界面还支持 to:、subject:、精确短语和取反。在 API 代码中，这些运算符只是一个经过 URL 编码的字符串；服务器执行搜索并返回匹配的邮件 ID。对代理或定时任务来说，先把结果限制在 25 条是不错的起点：既有足够的候选，又不会被迫读取整个邮箱。

这条 CLI 命令使用了 nylas email search 中经过验证的标志。位置参数查询是 invoice，因为当前命令会把非通配符查询当作主题文本；from: 等字段运算符属于 Gmail API 语法，不会被 CLI 原样透传。该命令返回 25 条 JSON 结果，便于脚本或代理工具使用。

nylas email search "invoice" \
  --from "billing@stripe.com" \
  --unread \
  --limit 25 \
  --json

Gmail 标签和分类搜索是如何工作的？

Gmail 标签不是文件夹；它们是可以出现在多封邮件上的标记，一封邮件也可以同时带有多个标签。Google 在文档中描述了 2 类标签：保留的 SYSTEM 标签（例如 INBOX），以及由邮箱所有者或集成创建的自定义 USER 标签。

Gmail 标签指南列出了常见系统标签，包括 INBOX、SPAM、TRASH、UNREAD、STARRED，以及 5 个分类标签：CATEGORY_PERSONAL、CATEGORY_SOCIAL、CATEGORY_PROMOTIONS、CATEGORY_UPDATES 和 CATEGORY_FORUMS。搜索查询通常使用面向用户的语法，例如 category:promotions，而 API 的标签过滤使用标签 ID，例如 CATEGORY_PROMOTIONS。

CLI 通过与其他提供商相同的文件夹式接口来暴露 Gmail 分类标签。下面的示例先搜索 25 封"促销"分类邮件，再对"社交"分类邮件做主题搜索。两条命令都使用 --in，这是 nylas email search 中经过验证的文件夹过滤标志。

nylas email search "*" --in "CATEGORY_PROMOTIONS" --limit 25 --json

nylas email search "webinar" \
  --in "CATEGORY_SOCIAL" \
  --limit 25 \
  --json

如何在不先解码 MIME 的情况下搜索附件？

Gmail 附件搜索应该从搜索索引入手，而不是从 MIME 解析入手。查询 has:attachment 会在代码下载邮件负载之前先收窄结果集，避免为了发现只有 3 封邮件带文件，而把大邮箱里的每封邮件都解码一遍。

下载附件仍然是第二个 API 步骤。Gmail 附件资源文档把 attachmentId 描述为在单独的 messages.attachments.get 请求中使用的值，且返回的数据采用 base64url 编码。也就是说，直接集成 Gmail 需要完成搜索、邮件分段遍历、附件 ID 查找、字节解码和文件写入这一整套流程。

CLI 让第一步保持小规模，并把文件下载推迟到你选定某封邮件和附件 ID 之后。下面这 3 条命令依次：搜索带附件的邮件、列出选定邮件上的附件，然后把指定附件下载到本地路径。

nylas email search "*" --has-attachment --from "billing@stripe.com" --limit 25 --json

nylas email attachments list <message-id> --json

nylas email attachments download <attachment-id> <message-id> --output ./invoice.pdf

如何按日期范围搜索和查找旧邮件？

Gmail 的日期搜索在搜索表达式内部使用 after:、before:、older: 和 newer: 等运算符，而 CLI 把日期边界暴露为显式标志。无论哪种方式，自动化任务都应使用固定日期，这样同一个任务在每 24 小时重跑时能产生可复现的结果。

固定时间窗口可以防止隐性的全邮箱扫描。一个月度发票任务可以只搜索 2026 年 1 月，再在对主题和发件人排序之后读取选定的邮件。在 API 代码中，日期范围写在 q 字符串里。在 CLI 中，--after 和 --before 让日期边界对审阅者可见，也便于在封装脚本中强制执行。

这条命令搜索 2026 年 1 月 1 日至 2 月 1 日之间主题包含 invoice 的邮件。它最多返回 50 个候选，足以支撑人工报告或代理排序，而不会让检索步骤膨胀成数千封正文。

nylas email search "invoice" \
  --after 2026-01-01 \
  --before 2026-02-01 \
  --limit 50 \
  --json

如何用 rfc822msgid 找到某一封邮件？

rfc822msgid: 运算符用于搜索某个特定的互联网邮件 ID。当 webhook、退信、日志行或工单记录了原始 Message-ID 标头时，它特别有用。不必按主题扫描，这种搜索直接命中一个全局有意义的标识符，通常只对应 1 个会话。

Google 在 users.messages.list 的文档示例中包含了 rfc822msgid:。这个运算符在调试重复发送、webhook 扇出和回复线程时最有用，因为它绕过了模糊文本搜索。如果邮件副本存在于多个标签或线程视图中，结果仍可能多于 1 封，所以请保持较低的 limit，并在读取正文前检查 ID。

CLI 目前没有为 rfc822msgid: 提供 Gmail 原生 q 的透传。对这个运算符请直接使用 Gmail API；只有在能用发件人、主题、日期、文件夹或附件过滤近似实现查找时，才使用 CLI 标志。下面的示例把 API 结果集限制在 5 个 ID。

response = service.users().messages().list(
    userId="me",
    q="rfc822msgid:<20260516.12345@example.com>",
    maxResults=5,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

如何安全地翻页 Gmail 搜索结果？

安全的 Gmail 搜索分页要保持查询稳定、保存当前的 nextPageToken，并在达到业务上限时立即停止。API 允许每页最多 500 条结果，但生产任务通常应该定义更小的总量上限，例如 200 或 1,000 封邮件。

分页正是直接 API 代码快速膨胀的地方。你需要一个处理 nextPageToken 的循环、一个结果上限、针对瞬时故障的重试行为，还需要在不重复处理同一页的前提下恢复执行的能力。如果一个每日任务只需要最新的 200 张收据，抓取 2,000 条匹配只会增加配额成本和审阅时间，并不会改善输出。

下面这个 Python 循环保持搜索查询不变，并在收集到 200 个邮件 ID 后停止。它展示了直接集成在调用 messages.get 获取主题、摘要或正文之前，就必须自行维护的额外状态。

query = "from:billing@stripe.com has:attachment after:2026/01/01"
page_token = None
message_ids = []

while len(message_ids) < 200:
    response = service.users().messages().list(
        userId="me",
        q=query,
        maxResults=min(100, 200 - len(message_ids)),
        pageToken=page_token,
    ).execute()

    message_ids.extend(message["id"] for message in response.get("messages", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

如何把 Gmail 搜索结果变成可读的邮件？

Gmail 搜索结果只有经过第二次抓取才能变得可读，因为 messages.list 返回的是轻量级邮件记录。要展示主题、发件人、摘要或正文，代码必须对选定的 ID 调用 messages.get，然后解析标头和 base64url 编码的负载数据。

这正是很多示例隐藏的部分。一次返回 50 个邮件 ID 的搜索，如果工作流要读取每条匹配，就会变成 50 次后续调用。对代理工作流而言，更安全的模式是：先搜索、对元数据排序、只读取 1 到 5 封选定邮件，然后停止。CLI 用相互独立的 nylas email search 和 nylas email read 命令体现了这条检索边界。

下面的命令先搜索，再读取选定的那封邮件。这种 2 步结构是有意为之：它让脚本或模型在为正文内容花费更多调用之前，先检查 ID 和摘要。

nylas email search "contract" --from legal@example.com --limit 10 --json

nylas email read <message-id> --json

CLI 如何把搜索映射到不同提供商？

CLI 给开发者一条统一的搜索命令，而 6 个提供商家族各自维护自己的搜索引擎和邮箱模型。Gmail 有 q 和标签，Microsoft 邮件有 Graph 过滤和文件夹 API，IMAP 服务器则提供 SEARCH 命令加邮箱文件夹。真正有用的契约是：一套命令界面，把提供商特有的行为隐藏在背后。

本指南中提供商侧的行为描述来自 Google 文档和经过验证的 CLI 帮助信息，并非在每个后端上做过端到端实测。category:promotions 和 rfc822msgid: 等 Gmail 专属运算符在本文中均指直接调用 API 的语法。对于跨提供商工作流，优先使用 --from、--to、--subject、--after、--before 和 --has-attachment 等 CLI 标志。

标签、文件夹和分类如何影响搜索质量？

Gmail 的搜索质量取决于是否选对了邮箱概念：标签、文件夹还是分类。Gmail 标签是多对多的标记，提供商文件夹通常对应单一位置，而 Gmail 分类是由 Google 分配的系统标签。把这 3 个邮箱概念混在一起，是搜索结果过多或漏掉预期邮件的常见原因。

当用户记得邮件里的词语时，用全文搜索。当工作流已经对邮件做过分类时，用标签。当目标是"促销"或"社交"这样的 Gmail 标签页时，用分类。当你需要一条同样适用于 Outlook、Exchange、Yahoo、iCloud 和 IMAP 的提供商中立命令时，用文件夹。

通常最容易调试的是一个 2 步模式：先列出可用的文件夹或标签，再在选定的位置内搜索。这样文件夹名称会留在日志里清晰可见，也避免在本应使用 CLI 文件夹抽象的跨提供商工作流中，硬编码一个 Gmail 专属标签。

上线任务之前如何测试 Gmail 搜索查询？

在把 Gmail 搜索查询放进 cron、CI 或代理工具之前，用 4 步检查循环来测试它：用小 limit 运行、检查 ID、读取 1 封选定邮件、保存确切的查询字符串。这能在查询读取数百封正文之前，提前发现过宽的搜索。

第一次运行应使用 --limit 5 或 --limit 10，而不是生产上限。先确认最新的 5 条匹配确实是你预期的那类邮件，再在发件人、日期、文件夹和附件过滤都表现正确之后放宽 limit。对于月度任务，至少要测试 2 个日期窗口：一个有已知匹配，一个为空窗口。

下面这个冒烟测试让输出保持小巧、易于审阅。第一条命令证明搜索范围已收窄；第二条命令读取一个候选。如果选出的邮件不对，先修正查询，再添加分页或发送逻辑。

nylas email search "invoice" --from billing@example.com --limit 5 --json

nylas email read <message-id> --json

AI 代理应如何安全地使用 Gmail 搜索？

AI 代理应把 Gmail 搜索当作一个有边界的检索步骤，而不是读取整个邮箱的许可。安全的代理循环是：窄范围搜索、限制候选数量、检查元数据、只读取选定邮件，并在任何发送或破坏性操作之前请求批准。

差异是可度量的。一个搜索 25 封邮件、只读取 3 封正文的代理，其提示词体积、成本和隐私足迹都远小于先读取 250 封正文的代理。搜索查询本身也成为审计产物：审阅者可以看到代理搜索的是 from:customer@example.com、has:attachment，还是 contract 这样的宽泛词。

下面这个 shell 模式是代理工具的良好基线。它收集 25 个候选 ID，让排序步骤选出一个，然后才读取正文内容。这些命令名称能干净地对应到审计日志和命令白名单。

nylas email search "contract" --from customer@example.com --limit 25 --json \
  | jq -r '.[].id' \
  | head -5

nylas email read <selected-message-id> --json

什么时候应该用 Gmail API 而不是 CLI？

当应用需要 1 个 Gmail 专属控制平面时，请直接使用 Gmail API：原生 q 运算符（例如 rfc822msgid:）、Gmail 管理、自有的 Google Cloud 项目、域范围委派、Pub/Sub watch 续期，或已经内嵌 Google OAuth 流程的界面。当你想要终端工作流、代理工具、定时任务，或环节更少的多提供商脚本时，请使用 CLI。

这个决策与 Gmail API 好不好无关，而在于谁来负责底层管线。直接调用 API 的代码要负责 OAuth 配置、查询构造、分页、邮件读取、base64url 解码、重试行为和提供商锁定。CLI 路线只负责命令选择和输出处理，提供商集成由 Nylas 在幕后处理。

对大多数开发者自动化场景，先走 CLI 路线，只有当你能说出具体的 Gmail 专属功能时，才转向直接调用 Gmail API。这条规则可以避免一次性脚本、AI 代理工具和 CI 任务演变成长期存活的 OAuth 客户端。

接下来可以做什么？

• Gmail API 分页与同步 — nextPageToken、historyId、标签范围限定与搜索结果分页
• Gmail API 垃圾邮件与回收站邮件 — includeSpamTrash、labelIds=["SPAM"] 与 in:spam 查询
• Gmail API 分类标签 — category: 运算符与 labelIds AND 过滤的陷阱
• 从终端列出 Gmail 邮件 — 涵盖 list、search、read、标签与 JSON 输出的 Gmail CLI 示例
• 2026 年 Gmail API 配额 — 各方法的配额成本、有边界的搜索循环与更安全的代理模式
• Gmail API 对 AI 代理的限制 — OAuth、MIME 解析、配额与工具设计风险
• 面向 AI 代理的邮件 API 对比 — 在 Gmail API、Graph、IMAP、MCP 和 CLI 工具之间做选择
• 邮件搜索命令 — 发件人、日期、附件、文件夹、limit 与 JSON 输出的确切标志
• 邮件读取命令 — 在有边界的搜索之后读取选定的那封邮件
• 完整命令参考 — 全部邮件、日历、联系人、webhook、MCP 与审计命令
• Gmail API 搜索与过滤指南 — Google 官方面向 messages.list、threads.list 和搜索查询的原生指南