先分清协议、授权和智能体工具
Gmail API 和 IMAP 的区别，不能简化为“一个用 OAuth，一个用密码”。Google 的 IMAP、POP 和 SMTP 都支持 OAuth 2.0，详见 Google 邮件协议说明。
Gmail API 是访问 Gmail 的接口；IMAP 用于访问和管理邮件，发送则另走 SMTP。OAuth 决定应用如何获得授权。MCP 是向 AI 智能体提供工具的接入层，不替代底层邮箱协议。下文统一将智能体称为 agent。
Mailera 的 Gmail 连接当前使用应用专用密码（app password），通过 IMAP 收件、SMTP 发件，再向应用提供 REST API 和 MCP。需要统一接入其他现有邮箱时，可结合现有邮箱接入 agent 的整体方案评估。若你正在选择工具接入层，可参考现有邮箱的 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 扩展文档列出了 X-GM-LABELS、X-GM-MSGID 和 X-GM-THRID。同一封邮件可能出现在不同标签对应的文件夹里，统计时应考虑标识和映射，不能只把文件夹数量相加。
权限选择尤其影响正文读取：gmail.metadata 不允许读取正文；gmail.readonly 允许查看邮件和设置，属于受限范围。Google 建议不需要完整邮件范围的应用改用 Gmail API 的细分范围，见 OAuth 机制说明。
通知也不是正文。Gmail API 的 Pub/Sub 通知包含邮箱地址和新的历史记录 ID，应用仍需调用 history.list 读取变更。watch 至少每 7 天续订一次；通知可能延迟或丢失。历史记录 ID 超出可用范围时会返回 HTTP 404，需要全量同步。实现时应同时参考推送通知指南和同步指南。
Mailera 对活跃邮箱检查得更频繁，闲置邮箱检查较少，长期不活跃的邮箱可能休眠。因此，不应认为采用某种接入方式就能保证新邮件实时可见。
怎样按任务选型？
- 列出实际操作。 只做摘要，就从读取开始；需要回复时，再单独设计发送授权。不要因为以后可能用到，就现在授予写入权限。
- 确认是否依赖 Gmail 原生能力。 仅服务 Gmail、需要细分权限或围绕其标签与会话设计的项目，优先评估 Gmail API。已有 IMAP 客户端或需要跨服务商协议兼容时，再评估 IMAP。
- 检查账号与组织策略。 如果项目必须通过 Gmail OAuth 接入，Mailera 当前的 Gmail 连接不是替代方案。应用专用密码不可用时，应重新评估授权路径，而不是改变组织限制。
- 确定维护责任。 直接接入时，由你的应用处理 Google 授权和同步。需要统一接口时，核对 Mailera 产品能力与实际任务是否匹配，而不是假设所有 Gmail 功能都已映射。
费用也要分层看。Google 的配额与费用说明将 Gmail API 标准使用描述为无需额外费用，但请求仍消耗配额，消耗量随方法和参数变化。“无需额外费用”不等于无限调用。预算中还应单列 Workspace 订阅与外围基础设施，不要把它们和 API 使用费混为一项。
如何通过 Mailera 验证 Gmail 邮件读取？
只使用你自己的测试邮箱，并事先向它发送一封不含私人信息的测试邮件。
1. 确认应用专用密码可用
按 Google 应用专用密码说明检查账号条件：必须开启两步验证；仅使用安全密钥的两步验证、组织账号或 Advanced Protection 都可能使该选项不可用。Google 建议应用提供 “Sign in with Google” 时优先使用该方式。
2. 添加邮箱并测试连接
由 Admin 或 Leader 进入“添加邮箱”，选择“单个邮箱”标签页，在“邮箱地址”输入测试地址。确认识别为 Gmail，选择“继续”。
在“连接信息”的“密码”字段填写应用专用密码，不是日常登录密码，并选择测试用“邮箱分组”。点击“测试并连接”，检查“收件服务器登录”“文件夹检测”和“发件服务器登录”。此测试不会发送邮件；若仅发件失败，可以选择“保存为仅收件”。
3. 创建只读密钥
进入“设置”的“API key”标签页，选择“创建 API key”。将“邮箱范围”限定到测试邮箱所在组，只授予 read，并设置“有效期”。密钥只显示一次，将其保存在受控配置中。
4. 分别验证列表和正文
在本地受控环境中，将 $MAILERA_API_KEY 设置为刚创建的密钥。先列出可访问邮箱：
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，读取收件箱列表：
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，再获取正文：
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 文档。
5. 按需验证 MCP
在密钥创建对话框选择“复制 MCP 配置”，使用对应的 Claude、Cursor 或 VS Code 配置。先调用 list_messages，再调用 get_message；只读任务不需要增加 send 或 move。配置入口和工具说明见 Mailera MCP。如果你使用 VS Code，可按 VS Code 邮件 MCP 配置与测试指南完成客户端设置。
验收目标是读到那封测试邮件的正文，而不只是看到连接成功。截图与日志中应隐藏密钥、应用专用密码和私人邮件内容。
常见错误：授权成功，却读不到邮件
| 现象 | 检查方向 |
|---|---|
| 找不到应用专用密码入口 | 检查两步验证方式、账号类型和管理员策略，不尝试绕过限制 |
| 之前能连接，改密码后失败 | Google 更改账号密码后会撤销应用专用密码；重新检查连接凭据 |
| Gmail API 能读邮件头，读不到正文 | 检查是否只授予 gmail.metadata，以及任务所需的 OAuth 范围 |
| Mailera 读不到目标邮箱 | 检查密钥的 read 权限、邮箱组范围、连接状态和最近同步时间 |
| 邮件数量或分类不同 | 检查文件夹选择、标签映射、分页及保留范围，不要直接判断为丢信 |
| IMAP 成功但发件失败 | 接收和发送是两条路径，单独检查 SMTP 与发送权限 |
Mailera 的 Gmail 状态依据最近同步信息，不是每次查询都重新验证 Google 登录。免费方案保留 30 天邮件，首次加载也只覆盖保留期内的邮件。
直接使用 Gmail API 时，还要把授权范围审核纳入计划。Google 范围说明将受限范围列为需要 OAuth 应用审核的类别，并指出在服务器存储或传输受限范围数据涉及安全评估。
让 agent 读邮件，需要哪些安全边界？
邮件正文、附件和其中的链接都是不可信数据，不是系统指令。邮件里要求泄露凭据、改变权限或调用工具的内容，不能成为操作授权；这是邮件场景中需要防范的 prompt injection。
Google OAuth 范围、应用专用密码与 Mailera API 密钥是不同层的凭据。给 Mailera 密钥设置 read，不会把上游应用专用密码变成 Google 的只读凭据。
默认只读，限制邮箱组并设置有效期。需要发送、移动或删除时，应设置独立控制；发送前在你的应用或 agent 流程中要求人工确认，不要把邮件里的“请立即发送”当成确认。
凭据不要放入提示词、代码仓库或日志。测试完成后，撤销不再需要的密钥和应用专用密码。相关产品说明见 Mailera 安全页面。
Mailera 的适用边界
Mailera 连接已有邮箱，不创建新的 Gmail 地址，也不提供群发营销或邮箱预热。它无法使不符合 Google 条件的账号获得应用专用密码，也不能绕过 Workspace 管理员限制。若这些条件与项目要求冲突，应选择其他获准的接入路径。
