Spring Boot 应用集成 AWS SES SMTP 时出现 Mail health check failed 警告，根源常被误判为网络或配置问题，实则多由 SMTP 协议握手失败（如 501 Syntax: HELO ）或账户发信健康度异常（高退信/投诉率）导致，需分层定位。
spring boot 应用集成 aws ses smtp 时出现 `mail health check failed` 警告，根源常被误判为网络或配置问题，实则多由 smtp 协议握手失败（如 `501 syntax: helo
在 Spring Boot 应用中启用邮件健康检查（MailHealthIndicator）是良好的运维实践，但当它在 AWS ECS 环境中频繁报出如下警告：
{
"message": "Mail health check failed",
"exceptionClass": "MessagingException",
"stackTrace": "javax.mail.MessagingException: 501 Syntax: HELO <hostname>"
}</hostname>
这并非简单的“邮件发送失败”，而是健康探针在尝试建立 SMTP 连接时即被拒绝——关键线索在于 501 Syntax: HELO
? 一、优先排查：SMTP 协议层握手失败（最常见原因）
AWS SES 的 SMTP 端点严格要求 HELO 或 EHLO 命令携带合法、可解析的主机名（非空字符串、非 IP、非 localhost）。而 Spring Boot 默认的 JavaMail 实现（com.sun.mail.smtp）在容器化环境中（尤其是 ECS Task）常因以下原因生成非法 HELO 值：
- Docker 容器 hostname 默认为随机长 ID（如 a1b2c3d4e5f6），不符合 DNS 规范；
- JVM 未显式设置 mail.smtp.localhost 参数，JavaMail 自动调用 InetAddress.getLocalHost().getHostName()，结果可能为 localhost 或解析失败；
- ECS Task 所在 EC2 实例或 Fargate 平台未正确配置 /etc/hosts 或 DNS 解析。
✅ 解决方案：强制指定合法 HELO 主机名
在 application.yml 中显式配置 JavaMail 属性：
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
mail.smtp.starttls.enable: true
mail.smtp.starttls.required: true
# ? 关键修复：覆盖默认 HELO 值，使用符合 RFC 的域名
mail.smtp.localhost: ses-health-check.example.com
# 可选：禁用自动探测，避免 fallback 到非法 hostname
mail.smtp.ehlo: true
mail.smtp.helo: true
⚠️ 注意：mail.smtp.localhost 的值必须是一个合法的、可解析的域名（无需真实存在，但格式需合规，如 app.example.com），不能是 IP、localhost 或空字符串。该值将作为 HELO/EHLO 命令的参数发送给 SES SMTP 服务器。
验证方式：可在本地或调试容器中运行 telnet email-smtp.us-east-1.amazonaws.com 587，手动输入 HELO ses-health-check.example.com，确认返回 250 响应。
? 二、同步检查：SES 账户健康状态（隐性拦截原因）
即使 SMTP 握手成功，若 SES 账户因高退信率（Bounce Rate）或高投诉率（Complaint Rate）被标记为“不健康”，SES 也可能静默拒绝健康检查连接（尤其在沙箱环境或新账户初期），表现为类似超时或协议错误。
根据 AWS 官方规范：
- 硬退信率 > 5% 或 投诉率 > 0.1% 将触发账户健康度降级；
- 沙箱账户仅允许向已验证邮箱发送，且对退信极其敏感；
- 向废弃邮箱、spam trap（垃圾邮件陷阱）地址发送会直接损害信誉。
✅ 自查步骤：
- 登录 SES 控制台 → Email Sending → Sending Statistics；
- 查看近 24 小时的 Bounces 和 Complaints 数值及比率；
- 检查是否收到 AWS 发送的 "Your Amazon SES sending limits have been reduced" 邮件；
- 确认所有测试收件人均为真实、活跃、已验证的邮箱（避免使用一次性邮箱或已失效地址）。
? 若发现指标异常：
- 立即暂停批量发送，清理收件人列表（移除无效/退订地址）；
- 使用 SES Mailbox Simulator 进行安全测试；
- 提交 SES 发送限额提升申请 并说明已优化发信实践。
✅ 总结：双轨排查清单
| 排查维度 | 关键动作 | 验证方式 |
|---|---|---|
| SMTP 协议层 | 设置 spring.mail.properties.mail.smtp.localhost 为合规域名 | Telnet 手动 HELO 测试 |
| 容器环境 | 确保 ECS Task Role 具备 ses:VerifyEmailIdentity 权限（如需动态验证） | CloudWatch Logs 检查 IAM 错误 |
| SES 健康度 | 检查控制台 Bounce/Complaint 率；停用可疑收件人；启用邮件反馈通知（SNS） | SES Sending Statistics 页面 |
| 应用配置 | 确认 spring-boot-starter-mail 版本 ≥ 2.7.x（修复部分 HELO 行为） | mvn dependency:tree 查看版本 |
? 提示：健康检查失败不会影响实际业务邮件发送（只要 sendEmail() API 调用正常），但它暴露了基础设施配置隐患。建议将 MailHealthIndicator 与自定义 HealthEndpoint 结合，加入 SES 发信配额、验证状态等维度，构建更全面的邮件服务可观测性。
通过以上两层精准干预，90% 以上的 Mail health check failed 警告可被根治，既保障 Spring Boot 健康探针稳定运行，也守护您的 SES 账户长期发信信誉。
