SendGrid模板插入动态HTML及嵌套变量不解析问题咨询

如何正确向SendGrid模板中插入动态HTML数据 #

• 明确变量渲染规则：如果要传入带HTML格式的富文本内容，模板中对应占位符必须使用三重大括号写法{{{变量名}}}，该写法会关闭SendGrid默认的HTML字符转义，直接渲染传入的HTML结构；如果使用双重大括号{{变量名}}}，所有HTML标签会被转义为普通字符直接展示，无法实现格式效果。
• 动态HTML数据统一通过发送API的dynamic_template_data字段传递，不要在业务侧做整段模板拼接后再传入。参数传递示例：

{
  "template_id": "对应模板的ID值",
  "to": [{"email": "收件人邮箱"}],
  "from": {"email": "发件人邮箱"},
  "dynamic_template_data": {
    "content": "<p>这是一段带<strong>加粗高亮</strong>的富文本内容</p>"
  }
}

• 传入的HTML片段不要包含<html>、<head>、<body>等顶层文档标签，只需要传正文结构片段即可，避免和模板本身的基础结构冲突导致渲染异常。

SendGrid变量嵌套问题说明与实现方案 #

SendGrid动态模板不支持变量嵌套解析：模板引擎只会对模板本身的占位符做单次渲染，不会二次解析变量值内部包含的模板标记，这也是传入hello {{{firstname}}}作为description变量值时，{{{firstname}}}直接以字面量形式输出的根本原因。

要实现静态文本+动态值的组合展示，有两种可落地的方案：

• 方案1：业务侧提前拼接好最终内容。在调用发送接口前，就在自己的服务代码里把静态文本和动态字段拼合成最终的字符串（包括需要的HTML格式），再赋值给对应变量传给模板。代码逻辑示例：

// 服务端逻辑示例
const firstname = "李明";
const description = `hello <span style="color:#2563eb">${firstname}</span>`;
// 将拼接完成的description传入dynamic_template_data即可

• 方案2：直接在模板内编写组合结构。如果内容结构固定，直接把静态文本和变量占位符都写在模板里即可，不需要通过变量传模板标记。比如要实现问候语效果，模板对应位置直接写：

<p>hello {{{firstname}}}</p>

如果存在多场景的内容切换需求，可以使用SendGrid模板内置的if/else条件语法实现分支渲染，不要尝试通过变量传模板标记的方式实现。

注意：不要试图通过自定义标签、特殊转义等方式强行实现嵌套变量解析，SendGrid渲染引擎没有提供二次解析变量值的能力，这类方案都无法稳定生效。

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