Spring Boot 应用集成 AWS SES SMTP 时出现 Mail health check failed 警告，根源常被误判为配置问题，实则多由 SMTP 协议握手失败（如 501 Syntax: HELO ）或 SES 账户健康状态异常（高退信/投诉率）导致，需分层定位。
spring boot 应用集成 aws ses smtp 时出现 `mail health check failed` 警告，根源常被误判为配置问题，实则多由 smtp 协议握手失败（如 `501 syntax: helo
在基于 Spring Boot + Docker + ECS 的 AWS 架构中，org.springframework.boot.actuate.mail.MailHealthIndicator 触发的 Mail health check failed 日志看似是健康检查失败，但其底层堆栈 javax.mail.MessagingException: 501 Syntax: HELO
? 根本原因分析：HELO 命令失效的两大主因
1. SMTP 客户端未正确设置 mail.smtp.localhost
JavaMail 默认使用 InetAddress.getLocalHost().getHostName() 生成 HELO 参数。在容器化环境中（尤其是 ECS Fargate 或精简镜像），该调用常返回 localhost、空字符串或非法主机名（如含下划线、以数字开头），违反 SMTP RFC 5321 对 HELO 域名格式的要求（必须是合法 DNS 主机名），导致 SES SMTP 服务器返回 501 Syntax 错误。
✅ 解决方案：显式配置合法 HELO 主机名
在 application.yml 中强制指定：
spring:
mail:
host: email-smtp.us-east-1.amazonaws.com # 替换为你的区域端点
port: 587
username: ${SES_SMTP_USERNAME}
password: ${SES_SMTP_PASSWORD}
properties:
mail:
smtp:
auth: true
starttls:
enable: true
# 关键修复：指定合规的 HELO 域名
localhost: ses-health-check.example.com # 必须是合法域名，无需真实解析
? 提示：localhost 值无需实际可解析，但必须符合 DNS 命名规范（如 a-z, 0-9, -, . 组成，不以 - 开头结尾）。避免使用 localhost、127.0.0.1 或容器 ID。
2. SES 账户健康状态受损（高退信/投诉率）
即使 SMTP 连接成功，SES 也可能在后续阶段静默拒绝邮件，触发健康检查超时或间接失败。AWS 会持续监控账户级指标：
- 硬退信率 > 5%（连续 24 小时）→ 自动暂停发送
- 投诉率 > 0.1%（连续 24 小时）→ 触发信誉降级
⚠️ 注意：此类限制不返回明确错误码，但会导致 MailHealthIndicator 因超时或空响应而报 WARN。
✅ 验证与修复步骤：
- 登录 SES 控制台 → Email Sending → Sending Statistics，检查 Bounces 和 Complaints 指标趋势；
- 使用 CloudWatch 查询 BounceRate 和 ComplaintRate 指标（命名空间：AWS/SES）；
- 立即清理无效邮箱（硬退信地址）、优化邮件内容（降低垃圾邮件标记风险）、启用反馈循环（Feedback Loop）接收投诉通知；
- 若已进入暂停状态，需提交 SES Sending Limits Increase 请求并附整改说明。
? 其他常见陷阱与规避建议
- 沙箱环境限制：新 SES 账户默认处于沙箱，仅允许向已验证邮箱发送。确保目标收件人已在 SES Verified Email Addresses 中列出；
- ECS 网络配置：确认 ECS 任务安全组放行出站 587 端口，且子网具备 NAT/IGW 访问公网能力；
- 健康检查频率：MailHealthIndicator 默认每 5 秒执行一次。高频失败可能加剧日志噪音，可通过 management.endpoint.health.show-details=never 临时抑制（生产环境建议保留并根治问题）。
✅ 总结：快速诊断流程图
graph TD
A[收到 Mail health check failed] --> B{检查堆栈是否含 '501 Syntax: HELO'}
B -->|是| C[配置 spring.mail.properties.mail.smtp.localhost]
B -->|否| D[检查 SES 控制台 Bounce/Complaint 率]
C --> E[重启应用验证]
D --> F[率＞阈值？→ 整改发送策略+申请解封]
F --> G[监控 24h 后指标回落]
切勿将此警告简单视为“可忽略的日志”。它既是 SMTP 协议合规性的警示灯，也是 SES 发送信誉的早期预警信号。从 HELO 配置入手快速修复协议层问题，再结合账户健康度审计，方能保障邮件服务的稳定性与 deliverability。
