Node环境下Sendgrid API Section标签无法渲染问题求助

我之前也碰到过一模一样的坑！邮件能正常发送，但模板里的动态标签就是不替换，折腾了好一会儿才摸清楚几个关键问题，给你梳理下排查方向：

1. 确认标签类型与API参数匹配 #

SendGrid模板有两种核心标签格式，对应不同的API参数，搞混了就会导致内容不填充：

• 替换标签（Substitution Tags）：格式为%tag_name%，需要在personalizations里用substitutions参数传递值
• Handlebars模板标签：格式为{{tag_name}}，需要用dynamic_template_data参数传递值，同时必须指定template_id

举个正确的示例：
如果你的模板用的是Handlebars标签，请求体应该是这样：

{
  method: 'POST',
  path: '/v3/mail/send',
  body: {
    personalizations: [{
      to: [{ email: params.sendTo }],
      subject: params.subject,
      dynamic_template_data: { // 注意这个参数
        username: "张三",
        order_number: "20240501001",
        total_amount: "99.9"
      }
    }],
    from: { email: params.sendFrom },
    template_id: "你的模板ID" // 必须添加这个字段
  }
}

2. 检查参数嵌套位置是否正确 #

不管是substitutions还是dynamic_template_data，都必须嵌套在personalizations数组的每一个对象里面，不能放在外层。比如下面这种写法就是错误的：

// 错误示例：参数位置不对
body: {
  personalizations: [{ to: [...], subject: ... }],
  substitutions: { "%username%": "张三" }, // 这里放错位置了！
  ...
}

3. 验证模板状态与ID正确性 #

• 确保SendGrid平台上的模板处于激活状态，草稿模板无法正常渲染动态内容
• 核对请求里的template_id和平台上的模板ID完全一致，别出现拼写错误或复制漏字符的情况

4. 避免冲突：不要同时指定模板和普通内容 #

如果用了template_id，就不要再在请求体里添加content字段（比如html或text类型的内容），否则普通内容会覆盖模板内容，导致动态标签失效。

5. 用SendGrid日志排查细节 #

去SendGrid后台的「邮件日志」里查看具体的发送记录，里面会显示请求的完整参数和模板渲染情况，有时候能直接看到标签不匹配的提示信息，帮你快速定位问题。

我当时就是把Handlebars模板误用了substitutions参数，改成dynamic_template_data后马上就正常了，你可以先从标签类型匹配这块入手排查！

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