#准备邮箱接入

Mail 接入分为两件事：管理员让应用能够连接邮箱服务，用户再关联自己有权使用的邮箱。已有应用能正常关联账户时，直接按快速开始搭建页面，不必重复准备服务商。

#谁需要准备什么

#配置入口在哪里

当前 Mail 接入方式将服务商凭据和服务器信息作为应用级配置维护，管理员在应用服务端配置的 mail.providers 中设置；这不是普通用户在 Settings 页面填写的个人设置。密钥应按部署环境的安全方式管理，不要提交到代码仓库。用户在应用的 Mail 账户页面关联自己的邮箱并完成授权。

#让 Agent 带你完成配置

把下面的提示词交给应用 Agent，并替换邮箱服务商和部署信息：

请为当前 NocoBase 3 应用准备 Mail 邮箱接入，邮箱服务商是 [Gmail / Microsoft 365 / IMAP/SMTP]，应用访问地址是 [应用地址]。

先检查 Mail Pro 插件是否已安装并启用，阅读当前安装版本随附的 Mail Skill，并检查现有配置。先告诉我：
1. 服务商配置由管理员在哪里维护，普通用户在哪里关联个人邮箱；这是否涉及 Settings 页面。
2. 还缺少哪些信息，分别需要由应用管理员、邮箱管理员或邮箱用户提供。
3. OAuth 回调地址或 IMAP/SMTP 服务器信息应如何确认，以及如何验证填写正确。

请根据当前安装版本完成应用侧可安全完成的配置，并把必须由我在服务商平台操作的步骤逐步列出。密钥和邮箱密码不得要求我粘贴到对话中；请指出安全的本地或部署密钥填写位置。不要猜测回调地址、权限范围或配置项。

配置完成后，指导我关联一个测试邮箱，并确认授权能返回应用、首次同步正常、邮件可以阅读和发送。若插件或当前邮箱类型不支持某项能力，请先说明限制，不要用自建收发逻辑替代。

Agent 应该先说明准备清单和操作者，再协助配置；需要登录 Google、Microsoft 或邮箱服务商平台、批准组织权限的步骤仍由有权限的人完成。

#选择邮箱接入方式

• Gmail 或 Microsoft 365：通常通过 OAuth 登录授权。管理员需要准备服务商 OAuth 应用，并将 Agent 根据当前应用生成的回调地址登记到服务商平台。
• IMAP/SMTP：适用于提供标准 IMAP 收信和 SMTP 发信服务的邮箱。管理员提供服务器地址、端口和安全连接方式；用户关联邮箱时使用服务商要求的登录凭据。

Gmail 和 Microsoft 365 支持的同步与邮箱整理能力较完整。IMAP/SMTP 主要用于收取新邮件和发送邮件，不完整同步其他客户端中的已读、删除和移动操作，也不支持服务商草稿、发件别名、推送同步或移动到服务商文件夹。具体能力以当前安装版本和邮箱服务商为准。

#常见问题

#应用里找不到 Mail 或关联邮箱入口

先确认当前部署是否提供并启用了 NocoBase Pro Mail 插件。随后请 Agent 按当前版本检查 Mail 页面是否已接入应用；插件已启用不代表邮件入口已自动添加到业务导航。

#OAuth 登录后没有回到应用

请管理员核对服务商平台登记的回调地址与当前应用对外访问地址是否完全一致，包括协议、域名、端口和应用路径。让 Agent 根据当前部署配置重新确认回调地址，不要照抄其他环境的示例。

#邮箱关联成功，但没有看到邮件

检查首次同步选择的起始日期、同步状态和邮箱授权是否有效。首次导入大量邮件需要时间；应用后台任务或队列未运行时，同步也可能无法完成，请让 Agent 检查应用服务状态和同步记录。

#在其他邮箱客户端整理的邮件没有同步

IMAP/SMTP 当前主要发现新增邮件，不保证同步其他客户端的已读、删除和移动状态，也不支持移动邮件到服务商文件夹。需要这些能力时，优先确认 Gmail 或 Microsoft 365 是否适用。

#邮件发送结果显示不确定

先查看应用的发送记录并在收件邮箱确认邮件是否已到达，再决定是否重试。不要因为页面超时就立即新建邮件重发，以免重复发送。

如果要把邮件放进客户、项目等业务页面，继续看进一步使用。