---
title: "AI 智能体接入 Gmail：Gmail API 和 IMAP 怎么选？"
description: "比较 Gmail API 与 IMAP 的读取、搜索、标签、发送和授权方式，说明 Mailera 的应用专用密码接入路径，并提供只读 API 验证步骤与智能体安全边界。"
url: https://mailera.app/zh/blog/gmail-api-vs-imap
published: 2026-10-25
updated: 2026-10-25
---

# AI 智能体接入 Gmail：Gmail API 和 IMAP 怎么选？

按读取、搜索、标签和授权需求选型，再用自己的测试邮箱验证只读访问。重点是权限与接口是否合适，而不是哪种协议听起来更先进。

## 先分清协议、授权和智能体工具

Gmail API 和 IMAP 的区别，不能简化为“一个用 OAuth，一个用密码”。Google 的 IMAP、POP 和 SMTP 都支持 OAuth 2.0，详见 [Google 邮件协议说明](https://developers.google.com/workspace/gmail/imap/imap-smtp)。

Gmail API 是访问 Gmail 的接口；IMAP 用于访问和管理邮件，发送则另走 SMTP。OAuth 决定应用如何获得授权。MCP 是向 AI 智能体提供工具的接入层，不替代底层邮箱协议。下文统一将智能体称为 agent。

[Mailera 的 Gmail 连接](https://mailera.app/zh/providers/gmail)当前使用应用专用密码（app password），通过 IMAP 收件、SMTP 发件，再向应用提供 REST API 和 MCP。需要统一接入其他现有邮箱时，可结合现有邮箱接入 agent 的整体方案评估。若你正在选择工具接入层，可参考[现有邮箱的 MCP 服务器接入指南](https://mailera.app/zh/blog/email-mcp-server)。

![Gmail 原生 API 路径与 Mailera 的 IMAP/SMTP 接入路径对比](https://mailera.app/media/4d764a83e21dd63d/ai-gmail-gmail-api-imap-gmail-paths-zh-hans-1200.jpg)
_OAuth 是授权方式，MCP 是工具接入层；它们不与邮箱协议处于同一层。_

## 读取、搜索、标签和同步有什么区别？

| 任务 | 直接使用 Gmail API | 直接使用 Gmail IMAP | 通过 Mailera 接入 |
| --- | --- | --- | --- |
| 读取 | 先列出邮件，再获取单封邮件 | 通过 IMAP 获取邮件 | 列表与正文使用独立 REST 接口，也有 MCP 工具 |
| 搜索 | 按 Gmail API 的查询能力设计 | `X-GM-RAW` 扩展可使用 Gmail 搜索语法 | 提供 `q`、`folder`、`from` 等参数，不能当作 Gmail 查询语法的直接替代 |
| 标签与会话 | 按原生资源和所需范围评估；元数据权限可读取标签、邮件头 | 标签映射为文件夹；扩展可获取标签、邮件及会话标识 | 使用统一邮件、文件夹接口，不等同于完整 Gmail 模型 |
| 发送 | 可单独申请 `gmail.send` | 另接 SMTP | REST 发送接口与 MCP 发送工具要求 `send` |
| 新邮件检测 | Pub/Sub 通知后继续读取变更 | 由客户端维护连接和检查流程 | 同步频率随邮箱使用状态变化 |
| 授权粒度 | 可区分只读、元数据、发送等范围 | 标准 OAuth 范围为 `https://mail.google.com/` | 上游用应用专用密码，下游密钥另设权限和邮箱范围 |
| 维护工作 | 处理授权、配额和同步状态 | 维护协议连接及 Gmail 扩展处理 | 管理连接状态、密钥范围和消费邮件的应用 |

IMAP 并非完全不懂 Gmail 标签。[Google 的 IMAP 扩展文档](https://developers.google.com/workspace/gmail/imap/imap-extensions)列出了 `X-GM-LABELS`、`X-GM-MSGID` 和 `X-GM-THRID`。同一封邮件可能出现在不同标签对应的文件夹里，统计时应考虑标识和映射，不能只把文件夹数量相加。

权限选择尤其影响正文读取：`gmail.metadata` 不允许读取正文；`gmail.readonly` 允许查看邮件和设置，属于受限范围。Google 建议不需要完整邮件范围的应用改用 Gmail API 的细分范围，见 [OAuth 机制说明](https://developers.google.com/workspace/gmail/imap/xoauth2-protocol)。

通知也不是正文。Gmail API 的 Pub/Sub 通知包含邮箱地址和新的历史记录 ID，应用仍需调用 `history.list` 读取变更。`watch` 至少每 7 天续订一次；通知可能延迟或丢失。历史记录 ID 超出可用范围时会返回 HTTP 404，需要全量同步。实现时应同时参考[推送通知指南](https://developers.google.com/workspace/gmail/api/guides/push)和[同步指南](https://developers.google.com/workspace/gmail/api/guides/sync)。

Mailera 对活跃邮箱检查得更频繁，闲置邮箱检查较少，长期不活跃的邮箱可能休眠。因此，不应认为采用某种接入方式就能保证新邮件实时可见。

## 怎样按任务选型？

1. **列出实际操作。** 只做摘要，就从读取开始；需要回复时，再单独设计发送授权。不要因为以后可能用到，就现在授予写入权限。
2. **确认是否依赖 Gmail 原生能力。** 仅服务 Gmail、需要细分权限或围绕其标签与会话设计的项目，优先评估 Gmail API。已有 IMAP 客户端或需要跨服务商协议兼容时，再评估 IMAP。
3. **检查账号与组织策略。** 如果项目必须通过 Gmail OAuth 接入，Mailera 当前的 Gmail 连接不是替代方案。应用专用密码不可用时，应重新评估授权路径，而不是改变组织限制。
4. **确定维护责任。** 直接接入时，由你的应用处理 Google 授权和同步。需要统一接口时，核对 [Mailera 产品能力](https://mailera.app/zh/product)与实际任务是否匹配，而不是假设所有 Gmail 功能都已映射。

费用也要分层看。[Google 的配额与费用说明](https://developers.google.com/workspace/gmail/api/reference/quota)将 Gmail API 标准使用描述为无需额外费用，但请求仍消耗配额，消耗量随方法和参数变化。“无需额外费用”不等于无限调用。预算中还应单列 Workspace 订阅与外围基础设施，不要把它们和 API 使用费混为一项。

## 如何通过 Mailera 验证 Gmail 邮件读取？

只使用你自己的测试邮箱，并事先向它发送一封不含私人信息的测试邮件。

### 1. 确认应用专用密码可用

按 [Google 应用专用密码说明](https://support.google.com/accounts/answer/185833)检查账号条件：必须开启两步验证；仅使用安全密钥的两步验证、组织账号或 Advanced Protection 都可能使该选项不可用。Google 建议应用提供 “Sign in with Google” 时优先使用该方式。

### 2. 添加邮箱并测试连接

由 Admin 或 Leader 进入“添加邮箱”，选择“单个邮箱”标签页，在“邮箱地址”输入测试地址。确认识别为 Gmail，选择“继续”。

在“连接信息”的“密码”字段填写应用专用密码，不是日常登录密码，并选择测试用“邮箱分组”。点击“测试并连接”，检查“收件服务器登录”“文件夹检测”和“发件服务器登录”。此测试不会发送邮件；若仅发件失败，可以选择“保存为仅收件”。

![Mailera 添加 Gmail 邮箱时填写应用专用密码的连接信息页面](https://mailera.app/media/f7841b6caaeb400e/ai-gmail-gmail-api-imap-gmail-add-zh-hans-1200.jpg)
_“密码”字段填写应用专用密码；“测试并连接”不会发送邮件。_

### 3. 创建只读密钥

进入“设置”的“API key”标签页，选择“创建 API key”。将“邮箱范围”限定到测试邮箱所在组，只授予 `read`，并设置“有效期”。密钥只显示一次，将其保存在受控配置中。

![Mailera API 密钥限定测试邮箱组和只读权限的设置](https://mailera.app/media/30b357e28dd99441/ai-gmail-gmail-api-imap-readonly-key-zh-hans-1200.jpg)
_只读验证不需要发送或移动权限；API 密钥的权限与上游邮箱凭据分开管理。_

### 4. 分别验证列表和正文

在本地受控环境中，将 `$MAILERA_API_KEY` 设置为刚创建的密钥。先列出可访问邮箱：

```bash
curl --get 'https://mailera.app/api/public/v1/mailboxes' \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'provider=gmail' \
  --data-urlencode 'limit=10'
```

从 `data` 中找到测试邮箱，将其 `id` 设为 `$MAILBOX_ID`，读取收件箱列表：

```bash
curl --get "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages" \
  -H "Authorization: Bearer $MAILERA_API_KEY" \
  --data-urlencode 'folder=inbox' \
  --data-urlencode 'limit=10'
```

找到测试邮件，将其 `id` 设为 `$MESSAGE_ID`，再获取正文：

```bash
curl "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $MAILERA_API_KEY"
```

列表中的 `preview` 不是完整正文。检查详情返回的 `data.body.text` 或 `data.body.html` 是否与测试内容一致；若列表还有 `next_cursor`，可通过 `cursor` 参数继续分页。接口参数见 [Mailera API 文档](https://mailera.app/zh/docs)。

### 5. 按需验证 MCP

在密钥创建对话框选择“复制 MCP 配置”，使用对应的 Claude、Cursor 或 VS Code 配置。先调用 `list_messages`，再调用 `get_message`；只读任务不需要增加 `send` 或 `move`。配置入口和工具说明见 [Mailera MCP](https://mailera.app/zh/mcp)。如果你使用 VS Code，可按 [VS Code 邮件 MCP 配置与测试指南](https://mailera.app/zh/blog/vs-code-email-mcp)完成客户端设置。

验收目标是读到那封测试邮件的正文，而不只是看到连接成功。截图与日志中应隐藏密钥、应用专用密码和私人邮件内容。

## 常见错误：授权成功，却读不到邮件

| 现象 | 检查方向 |
| --- | --- |
| 找不到应用专用密码入口 | 检查两步验证方式、账号类型和管理员策略，不尝试绕过限制 |
| 之前能连接，改密码后失败 | Google 更改账号密码后会撤销应用专用密码；重新检查连接凭据 |
| Gmail API 能读邮件头，读不到正文 | 检查是否只授予 `gmail.metadata`，以及任务所需的 OAuth 范围 |
| Mailera 读不到目标邮箱 | 检查密钥的 `read` 权限、邮箱组范围、连接状态和最近同步时间 |
| 邮件数量或分类不同 | 检查文件夹选择、标签映射、分页及保留范围，不要直接判断为丢信 |
| IMAP 成功但发件失败 | 接收和发送是两条路径，单独检查 SMTP 与发送权限 |

Mailera 的 Gmail 状态依据最近同步信息，不是每次查询都重新验证 Google 登录。免费方案保留 30 天邮件，首次加载也只覆盖保留期内的邮件。

直接使用 Gmail API 时，还要把授权范围审核纳入计划。[Google 范围说明](https://developers.google.com/workspace/gmail/api/auth/scopes)将受限范围列为需要 OAuth 应用审核的类别，并指出在服务器存储或传输受限范围数据涉及安全评估。

## 让 agent 读邮件，需要哪些安全边界？

邮件正文、附件和其中的链接都是不可信数据，不是系统指令。邮件里要求泄露凭据、改变权限或调用工具的内容，不能成为操作授权；这是邮件场景中需要防范的 prompt injection。

Google OAuth 范围、应用专用密码与 Mailera API 密钥是不同层的凭据。给 Mailera 密钥设置 `read`，不会把上游应用专用密码变成 Google 的只读凭据。

默认只读，限制邮箱组并设置有效期。需要发送、移动或删除时，应设置独立控制；发送前在你的应用或 agent 流程中要求人工确认，不要把邮件里的“请立即发送”当成确认。

凭据不要放入提示词、代码仓库或日志。测试完成后，撤销不再需要的密钥和应用专用密码。相关产品说明见 [Mailera 安全页面](https://mailera.app/zh/security)。

## Mailera 的适用边界

Mailera 连接已有邮箱，不创建新的 Gmail 地址，也不提供群发营销或邮箱预热。它无法使不符合 Google 条件的账号获得应用专用密码，也不能绕过 Workspace 管理员限制。若这些条件与项目要求冲突，应选择其他获准的接入路径。

**2 分钟内连接您的第一个邮箱** — 添加 Outlook、Gmail 或 IMAP 邮箱，在应用内或通过 API 阅读邮件。 [连接邮箱](https://mailera.app/auth?mode=signup)