不要一报错就重新生成密码
Zoho 邮箱应用专用密码是供外部邮件客户端使用的凭据，不是 IMAP 使用资格。密码生成成功，也不代表套餐或组织策略允许连接。
还没确认资格，先看下面的检查表；已有凭据但连接失败，可以直接看排障表。Mailera 的 Zoho 连接使用应用专用密码连接已有邮箱，不创建新的 Zoho 邮箱，也不能替你开通套餐未包含或管理员未允许的 IMAP 访问。
你的 Zoho 邮箱能使用 IMAP 吗？
Zoho 官方 IMAP 指南明确写明：新注册的免费套餐用户不能使用 IMAP。免费套餐也只在部分数据中心提供。因此，不要仅凭“免费账户”就判断历史账户的权限，应核对自己的账户资格。
| 检查项 | 在哪里确认 | 通过后做什么 | 未通过怎么办 |
|---|---|---|---|
| 套餐与账户类型 | 账户套餐信息及官方 IMAP 说明 | 继续查组织策略 | 核对套餐资格，不必先重置密码 |
| 组织访问策略 | 向组织管理员确认邮件策略 | 检查邮箱开关 | 请管理员处理访问限制 |
| 邮箱 IMAP 开关 | Zoho Mail 的“Settings”→“Mail Accounts”→主邮箱地址 | 在 IMAP 区域勾选“IMAP Access”，点击“Save” | 先启用，再配置外部客户端 |
| 数据中心与服务器 | 账户内的“Server Configurations Details” | 记录本账户的服务器参数 | 按账户显示的配置填写 |
组织策略与邮箱开关是两项检查：自己打开开关，不能替代管理员授权。
如何生成 Zoho 应用专用密码？
Zoho 要求启用两步验证的账户在 IMAP 客户端中使用应用专用密码；使用 SAML 认证的组织也需要使用这类密码。Mailera 的 Zoho 连接同样要求填写应用专用密码，而不是网页登录密码。
按 Zoho 的两步验证与应用专用密码说明操作：
- 登录该邮箱对应的 Zoho Accounts。
- 进入“Security”，选择“App passwords”。
- 点击“Generate New Password”。
- 输入便于识别的应用名称，例如
Mailera-test，然后点击“Generate”。应用名称只是备注，不是登录用户名。 - 保存生成的密码。Zoho 只显示一次；填入邮件客户端时，不要带空格。
应用名称的用途也可参照 Zoho 应用专用密码生成说明。
三种凭据不要混用：网页登录密码用于登录 Zoho；Zoho 应用专用密码用于这次邮箱连接；Mailera API 密钥用于应用调用 Mailera API，不能填进邮箱连接的密码框。通用说明见供 AI 智能体使用的邮箱应用专用密码指南。如果你还要连接 Yahoo 邮箱，可另看 Yahoo 的 IMAP 与 SMTP 应用专用密码设置。
只用自己的测试邮箱操作，截图时遮盖完整地址和全部密码，不把凭据放进日志或提示词。不再使用这条连接时，可在 Zoho 删除对应的应用专用密码，撤销应用访问。
IMAP 服务器、端口和加密方式怎么填？
以账户内的“Server Configurations Details”为准。 Zoho 按账户类型和数据中心提供具体配置。下表列出英文官方指南中的配置，并非所有账户都适用。
| 字段或适用账户 | 配置 | 使用条件 |
|---|---|---|
| 个人用户、免费组织用户 | imap.zoho.com，端口 993，启用 SSL | 仍须具备 IMAP 资格，并核对账户服务器 |
| 使用自定义域邮箱的付费组织用户 | imappro.zoho.com，端口 993，启用 SSL | 核对所属数据中心的实际配置 |
| Mailera 的 Zoho 默认收件配置 | imap.zoho.com，端口 993，TLS | 不能代替账户专属配置 |
| 密码 | Zoho 应用专用密码 | 输入时去掉空格 |
| Mailera 自定义 IMAP 的用户名 | 按账户登录信息填写 | 与邮箱地址相同时，界面允许留空 |
需要手动指定服务器时，使用 Mailera 自定义 IMAP 连接，在“安全性”选择“SSL/TLS”。“检测设置”只能在域名存在公开配置时填入参数，仍要与 Zoho 账户内的信息核对。
只有需要发件时才配置 SMTP。Zoho 官方 SMTP 指南列出的个人及免费组织用户服务器为 smtp.zoho.com，付费自定义域组织用户为 smtppro.zoho.com，均列有端口 587、TLS 配置。Mailera 的 Zoho 发件预设为 smtp.zoho.com:587、STARTTLS；也应核对账户适用配置。SMTP 认证用户名使用完整邮箱地址。
如何连接到 Mailera 并确认可用？
添加邮箱需要 Admin 或 Leader 角色。
- 进入“邮箱列表”→“添加邮箱”，选择“单个邮箱”。
- 在“邮箱地址”输入自己的测试邮箱，检查识别结果。自定义域没有被正确识别时，在“或选择服务商”中选择 Zoho；需要手动填写服务器参数时，选择“自定义 IMAP”。
- 点击“继续”，在“连接信息”的“密码”中填入应用专用密码。自定义 IMAP 还需填写“收件服务器（IMAP）”的“服务器”“端口”和“安全性”；“发件服务器（SMTP）”为选填。
- 点击“测试并连接”，依次查看“收件服务器登录”“文件夹检测”，以及配置了 SMTP 时的“发件服务器登录”。测试还会检查“实时监控”是否可用，整个过程不会发送邮件。
- 如果只有发件失败，选择“保存为仅收件”，或通过“修改信息”更正发件配置后“重新测试”。不要为 SMTP 失败反复修改已通过的 IMAP 设置。
- 连接后回到“邮箱列表”检查状态，再向自己的测试邮箱发送一封不含敏感内容的邮件，打开邮箱确认主题和正文可见。
首次连接后，Mailera 按从新到旧的顺序加载保留期内的邮件。收件测试成功不代表发件已通过，也不代表所有历史邮件都会导入。
常见错误：为什么密码正确仍然连接失败？
| 现象 | 优先检查 | 下一步 | 验证方式 |
|---|---|---|---|
| 新注册免费账户无法连接 | 套餐是否提供 IMAP | 核对资格，不反复生成密码 | 确认账户已获得 IMAP 访问资格 |
| 组织邮箱无法连接 | 管理员邮件策略 | 请管理员确认允许 IMAP | 策略允许后重新测试 |
| 收件服务器登录失败 | “IMAP Access”是否启用并保存 | 开启 IMAP | 重新运行收件测试 |
| 使用默认地址仍失败 | 账户类型与数据中心 | 按账户服务器配置更正地址 | 收件登录和文件夹检测通过 |
| 填了网页登录密码，或密码含空格 | 凭据类型与输入内容 | 改用无空格的应用专用密码 | 重新测试连接 |
| 应用专用密码已删除 | Zoho 中的应用密码记录 | 为仍需使用的连接生成新密码 | 更新凭据后重新测试 |
| 收件成功，只有发件失败 | SMTP 服务器及发件凭据 | 修改发件设置，或保存为仅收件 | 单独查看发件测试结果 |
| 连接成功，但缺少文件夹 | Zoho 的 IMAP 文件夹选择 | 选中需要提供给客户端的文件夹 | 再检查可见文件夹 |
看不到“App passwords”入口时，检查当前登录账户、安全设置及组织政策，向管理员确认；不要为了连接而关闭两步验证。
Zoho 只向 IMAP 客户端提供已选中的文件夹。缺少文件夹时，应先查这个设置，而不是马上更换密码。
对 Zoho，Mailera 的邮箱状态接口依据最近一次同步报告登录状态，并不是每次查询都会重新验证密码。判断是否恢复时，要结合最近同步信息和测试邮件；闲置邮箱的后台检查频率可能降低，不应把状态正常理解为邮件绝对实时到达。
交给 AI 智能体读取邮件时，怎样控制风险？
邮件正文是不可信数据，不是给 AI 智能体的指令。不要让智能体照做邮件中要求泄露凭据、调用工具或转发内容的指示。
只读场景只授予 read 权限，并将“邮箱范围”限制到所需分组，不默认开放发送或管理权限。确需发件时，在智能体流程中要求用户确认收件人和正文，不要假定系统会自动替你确认。
已有邮箱如何通过 MCP 接入智能体，见现有邮箱的邮件 MCP 服务器指南；使用 VS Code 时，可参照在 VS Code 中配置并测试邮件 MCP。
不再使用时，撤销对应的 Mailera API 密钥及 Zoho 应用专用密码。权限与凭据管理可参照 Mailera 安全说明。
