邮件配置
邮件配置用于在 RuoYi Office 中统一维护 SMTP 邮箱账号、邮件模板和发送日志。它适合审批抄送、账号通知、报表推送、业务提醒等需要留存内容的通知场景。
本地实现位置
| 层 | 位置 |
|---|---|
| 邮箱账号页面 | ruoyi-office-vben/apps/web-antd/src/views/system/mail/account |
| 邮件模板页面 | views/system/mail/template |
| 邮件日志页面 | views/system/mail/log |
| 后端 Controller | MailAccountController.java、MailTemplateController.java、MailLogController.java |
| 发送服务 | MailSendService |
发送链路
邮箱账号
邮箱账号保存 SMTP 服务接入配置，页面支持新增、编辑、删除、批量删除和分页查询。
| 操作 | 接口 | 权限标识 |
|---|---|---|
| 创建账号 | POST /system/mail-account/create | system:mail-account:create |
| 更新账号 | PUT /system/mail-account/update | system:mail-account:update |
| 删除账号 | DELETE /system/mail-account/delete | system:mail-account:delete |
| 账号分页 | GET /system/mail-account/page | 页面查询使用 |
| 精简列表 | GET /system/mail-account/list-all-simple、/simple-list | 模板页面下拉使用 |
配置时重点确认 SMTP host、port、用户名、密码/授权码、SSL/TLS 设置和发件邮箱是否匹配。
邮件模板
邮件模板绑定一个邮箱账号，并维护模板 code、主题、正文和参数。页面支持新增、编辑、删除、批量删除和测试发送。
| 操作 | 接口 | 权限标识 |
|---|---|---|
| 创建模板 | POST /system/mail-template/create | system:mail-template:create |
| 更新模板 | PUT /system/mail-template/update | system:mail-template:update |
| 删除模板 | DELETE /system/mail-template/delete | system:mail-template:delete |
| 模板分页 | GET /system/mail-template/page | 页面查询使用 |
| 精简列表 | GET /system/mail-template/list-all-simple、/simple-list | 业务下拉或选择使用 |
| 测试发送 | POST /system/mail-template/send-mail | system:mail-template:send-mail |
测试发送支持 toMails、ccMails、bccMails 和模板参数。后端通过当前登录管理员 ID 调用 sendSingleMailToAdmin，便于日志追踪操作者。
邮件日志
邮件日志用于查询实际发送结果，页面支持分页和详情查看。日志中会显示用户类型、用户编号、收件人、模板、账号、发送状态和异常信息。
| 操作 | 接口 | 说明 |
|---|---|---|
| 日志分页 | GET /system/mail-log/page | 按模板、账号、邮箱、状态等条件查询 |
| 日志详情 | GET /system/mail-log/get | 查看收件人、抄送、密送、内容和异常 |
接入建议
- 使用授权码而不是登录密码：多数邮箱服务商要求 SMTP 授权码。
- 生产环境单独账号：建议为系统通知创建专用邮箱，避免个人邮箱权限和风控问题。
- 模板 code 保持稳定：业务代码通常通过 code 触发邮件，线上不要随意修改。
- 大批量邮件要评估限流：SMTP 服务商通常有限频，批量通知建议配合异步任务或队列。
排查清单
| 现象 | 排查方向 |
|---|---|
| 测试发送失败 | 检查 SMTP 地址、端口、SSL、授权码和发件邮箱 |
| 收件人未收到 | 检查垃圾箱、服务商限流、收件地址和日志状态 |
| 模板参数未替换 | 检查模板变量名与测试参数 key 是否一致 |
| 日志无记录 | 检查是否真正调用 MailSendService，或发送前是否抛出异常 |
