配置Sendgrid为Firebase验证邮件SMTP中继时HTML内容不识别问题

问题现象 #

• 为Firebase Authentication配置SendGrid作为SMTP中继后，发出的邮件Content-Type为text/plain，邮件内嵌的HTML内容无法被正常识别渲染
• 切回Firebase默认SMTP服务时，邮件Content-Type为标准的multipart/alternative，HTML内容可正常展示
• 切换SMTP的原因：Firebase默认SMTP服务发件信誉较差，部分发出的邮件会被收件方判定为SPAM垃圾邮件
• 已查阅SendGrid官方文档，未找到对应问题的有效解决方案

分步排查方案 #

1. 核对Firebase控制台SMTP基础配置 #

• 展开SMTP配置页的高级选项栏，确认启用HTML格式邮件开关处于开启状态：该选项在自定义SMTP模式下默认关闭，是该问题最高发的诱因，使用Firebase默认SMTP时该开关默认开启，因此不会出现同类问题
• 核对连接参数：SendGrid SMTP服务需使用端口587搭配TLS加密，不要使用端口25；25端口为非加密通用发信端口，SendGrid会对该端口传入的邮件自动做纯文本转码，剥离所有HTML格式内容
• 确认配置的发件人对应域名已在SendGrid后台完成完整的域名认证（包含SPF、DKIM记录配置），未完成认证的发件人发出的邮件会被SendGrid安全规则自动降级为纯文本，规避钓鱼邮件风险

2. 检查Firebase邮件模板配置 #

• 不要在自定义邮件模板的头部手动添加Content-Type: text/plain字段，自定义SMTP场景下Firebase不会覆盖手动写入的错误头信息，会直接透传给SendGrid服务
• 排查模板内的HTML内容：不要出现未闭合标签、嵌入式脚本、违规跳转链接等被SendGrid安全规则判定为高风险的内容，触发安全拦截时SendGrid会自动剥离所有HTML标签，将内容转成纯文本发送
• 测试时重新触发全新的邮件（比如重新发起邮箱验证、密码重置请求），不要复用之前配置错误时生成的测试邮件，旧邮件已经是纯文本格式，不会随配置更新自动变更格式

3. 调整SendGrid后台设置 #

• 进入SendGrid后台的Mail Settings页面，找到Plain Content选项，确认该功能处于关闭状态：该功能开启时会自动将所有传入的多格式邮件转换为纯文本发送，常被用户误开作为垃圾邮件防控手段
• 检查SendGrid侧的出站过滤规则，确认没有配置规则将来自Firebase服务IP段的邮件强制设置为纯文本格式
• 核对SMTP鉴权使用的API Key权限，确保该Key拥有完整的邮件发送权限，权限不足时SendGrid会拒绝发送多格式HTML邮件，自动降级为纯文本做兜底发送

验证配置生效的方法：配置完成后发送测试邮件，查看邮件原始源码，确认头信息中Content-Type为multipart/alternative，且邮件正文同时包含text/plain和text/html两个分段，即代表配置正常。

内容的提问来源于stack exchange，提问作者Ivan Rene Rodriguez Escorcia