SendGrid List-Unsubscribe未在Gmail显示取消订阅按钮问题排查

我正在按照SendGrid的List-Unsubscribe指南操作，指南明确说明：

即使您不想使用订阅跟踪，也可以使用List-Unsubscribe标头。这对于希望为收件人提供无需依赖SendGrid跟踪功能的便捷退订方式的用户很有用

但无论是否开启subscription-tracking，我在Gmail邮箱里始终看不到发件人名称旁的“取消订阅”按钮。我按常规流程构建请求并添加了额外标头，代码示例如下：

Mail mail = new Mail();
/* build mail... */
Request request = new Request();
request.setBaseUri(baseUri);
request.setMethod(Method.POST);
request.setEndpoint("/v3/mail/send");
request.setBody(mail.build());
/* set auth/accept/misc headers... */
request.addHeader("List-Unsubscribe", "<mailto:unsubscribeexampexample@example.com>, <http://www.unsubscribe.example.com>");
return sg.api(request);

我还试过用指南里的示例链接/mailto地址测试，结果还是一样。请问可能遗漏了什么配置？

• 核心错误：标头加错位置了
  你现在是给API请求的HTTP头添加了List-Unsubscribe，但这个字段是邮件本身的MIME头，不是API请求的HTTP头。正确的做法是给Mail对象添加头，而不是Request对象：

  Mail mail = new Mail();
  /* build mail... */
  // 把标头加到Mail对象里
  mail.addHeader("List-Unsubscribe", "<mailto:unsubscribe@example.com>, <http://www.unsubscribe.example.com>");
  
  Request request = new Request();
  request.setBaseUri(baseUri);
  request.setMethod(Method.POST);
  request.setEndpoint("/v3/mail/send");
  request.setBody(mail.build());
  /* set auth/accept/misc headers... */
  // 移除给Request加的List-Unsubscribe头
  return sg.api(request);
  

• 检查标头格式的严格合规性
  Gmail对List-Unsubscribe的格式要求非常严：

  • 尖括号和逗号之间必须有空格（比如<mailto:a@b.com>, <http://c.com>，不能写成<mailto:a@b.com>,<http://c.com>）
  • mailto地址必须是有效的邮箱（你代码里的unsubscribeexampexample明显是笔误，多了一个example，修正成正常邮箱）
  • HTTP链接必须是完整可访问的URL，带http/https前缀

• 确认邮件符合Gmail的退订按钮触发规则
  Gmail只会给识别为「批量营销邮件」的内容显示取消订阅按钮，测试邮件/个人邮件可能不会触发：

  • 用专门的批量发件邮箱发送（别用个人Gmail测试）
  • 邮件内容带上订阅相关的说明（比如底部标注“这是订阅邮件，点击退订取消”）

• 查看邮件原始头确认标头是否存在
  发送测试邮件后，在Gmail里打开邮件→右上角三个点→显示原始邮件，搜索List-Unsubscribe，确认这个标头是否存在、格式是否正确。如果还是没有，检查SendGrid的全局设置有没有覆盖自定义头的规则。

内容的提问来源于stack exchange，提问作者Hummus