designing-email-templates

设计邮件模板

在创建或编辑 PostHog 工作流的邮件模板时使用此技能——群发活动和 function_email 工作流操作会发送渲染后的模板。

编写方式

编写设计 JSON（content.email.design），并使用 workflows-create-email-template 保存。服务端会使用与 PostHog 可视化编辑器相同的渲染器，根据设计渲染待发送的邮件，因此模板会以可供人工编辑的区块形式打开，发送的内容也会与设计描述完全一致。架构、所有邮件通用的原生区块和间距规则，以及一个可用示例，请参见 references/unlayer-design-json.md。

与用户交流时，称其为模板的设计——设计文档格式属于内部实现细节。创建或更新后，务必在回复中分享模板的 _posthogUrl 编辑链接，让用户可以直接在 PostHog 中打开模板。

撰写前请阅读 references/design-guidelines.md，其中介绍了如何确定设计方向、字体排版、颜色，以及让邮件看起来经过精心设计而非自动生成的模式。对于区块编辑器无法表达的某个片段，请在设计中使用 html 类型的内容区块。

使用 Liquid 个性化

邮件内容使用 Liquid 模板语法。Liquid 标签会以纯文本形式透传渲染器，因此可以在任何地方使用——区块文本、主题、链接：

Hi {{ person.properties.first_name | default: 'there' }},

营销邮件必须包含退订链接——使用内置变量生成链接：

<a href="{{ unsubscribe_url }}">Unsubscribe</a>

（{{ unsubscribe_url_one_click }} 也可用于一键列表退订流程。） 为 Customer.io 编写的模板可以保留其 {% unsubscribe_url %} 标签；该标签会渲染出与 {{ unsubscribe_url }} 相同的链接。

默认情况下，输出会进行 HTML 转义，因此即使值中包含标记，也会以文本形式呈现：

• 不要添加 | escape。这会进行二次转义，导致 & 在收件箱中显示为 &。
• 对于由你自己的后端生成的 HTML（例如摘要列表），请添加 | raw：{{ variables.summary_html | raw }}。切勿对用户输入的文本使用 raw。
• 使用 currency 格式化金额：{{ variables.amount | currency: "USD" }} 会渲染为 $1,234.50。非数字值会原样渲染。

点击跟踪与退出跟踪

每个链接都会自动改写为经过点击跟踪的重定向链接。这会破坏移动端通用链接／应用深层链接，因为只有当 href 保持在其自身域名下时，这些链接才能正常解析。若要让链接不受跟踪，请在其锚点（使用 html 区块）上添加 clicktracking="off" 或 data-ph-no-track：

<a href="https://app.example.com/deeplink" data-ph-no-track>Open in app</a>

标记必须添加在 <a> 标签本身，而不是子元素上。选择退出跟踪的链接不会产生点击指标。

图片

请先调用 media-images-list 并设置 purpose="email"——优先复用现有图片（如 logo、页眉横幅），而不是上传重复图片。

要添加新图片，请使用预签名流程上传，不要将字节嵌入设计：

1. 使用文件名和 purpose="email" 调用 media-image-upload-start——该工具会返回 id、upload_url 和 form_fields。
2. 在 shell 中将本地文件 POST 到 upload_url：curl -X POST <upload_url> -F key=value... -F file=@/path/to/image.png（使用响应中的 form_fields，并将 file 放在最后）。切勿将图片字节进行 base64 编码后放入工具调用——令牌翻转会损坏图片。
3. 使用 id 调用 media-image-upload-complete——该工具会返回永久 url。

将该 url 放入图片区块的 values.src.url（参见 references/unlayer-design-json.md）。区块还需要 values.src.width／height；媒体工具不会返回尺寸，因此如果可以通过 shell 访问本地文件，请自行测量，而不要猜测。

图片必须小于 4MB，并且能够解码为 PNG、JPEG、GIF、WebP、AVIF 或 BMP。

创建模板

调用 workflows-create-email-template，并传入：

{
  "name": "Welcome email",
  "description": "Sent to new signups on day 0",
  "type": "email",
  "content": {
    "templating": "liquid",
    "email": {
      "subject": "Welcome to {{ person.properties.company | default: 'our product' }}",
      "design": {
        "counters": { "u_row": 1 },
        "schemaVersion": 16,
        "body": { "rows": ["…"], "values": { "preheaderText": "Three short steps to get you set up" } }
      },
      "text": "Plain-text fallback of the same message"
    }
  }
}

• 邮件模板必须提供 subject。
• 将大多数收件箱显示在主题后面的预览文本放在设计的 body.values.preheaderText 中。渲染后的 html 会包含这段文本，因此无论通过哪种发送路径发送，它都会到达收件箱。请将 content.email.preheader 留空，以确保邮件只携带一段预览文本。
• 始终编写 design，并省略 html——服务端会根据设计渲染 html。如果发送手写 html 而不提供设计，视觉编辑器就只能将邮件显示为一个原始代码块。
• 始终将 text 填写为邮件内容的真实纯文本版本——会屏蔽富内容的客户端只显示 text，因此像 "placeholder" 这样的填充文本会抵达真实收件箱；而与 html 不匹配的文本部分会损害送达率。
• 工具结果会返回指向 PostHog 库中该模板的编辑链接。
• 创建（或更新）后，调用 workflows-show-email-template——它会渲染内嵌预览，让用户查看结果。

载荷机制

在工具调用中直接传入设计——不要创建临时文件、运行预验证子进程或进行多轮载荷预览。Liquid 标签（{{ }}、{% %}）、撇号、单引号和表情符号都是 JSON 字符串中的普通字符；只需遵循标准 JSON 转义规则。切勿为了避开这些字符而改写内容——在标记属性中将 Liquid 的单引号改成双引号会破坏标记。如果工具调用因格式错误而被拒绝，请修正 JSON 转义，并原样重新发送相同内容。

转换现有 HTML 邮件

要将其他平台上的邮件迁移过来，请使用原生区块重新构建，而不要将其 HTML 粘贴到一个 html 区块中，这样用户仍可编辑邮件：

• 源邮件的每个部分都应转换为对应的原生区块：标题用 heading，每段文字用一个 text 区块，每个行动号召用一个 button，每张图片用一个 image。在每个区块中保留源邮件的颜色、字体大小和内边距。
• 通过媒体库重新托管每张图片（参见 Images）。将文件的实际尺寸填入 src.width 和 src.height，并将 src.maxWidth 设为内容宽度的百分比，以设置显示宽度。源 HTML 声明的高度通常与文件的实际高度不符。
• 源邮件中由 {% if %} 包裹的部分应转换为带显示条件的区块（参见 references/unlayer-design-json.md）。
• 将源平台的 Liquid 变量重命名为此发送方式提供的变量。事务型 API 发送会将调用方在 message_data 中传入的所有内容作为 {{ variables.* }} 提供。
• 按钮不支持 box-shadow。较深色的 3px 底边框（border.borderBottomWidth、borderBottomStyle、borderBottomColor）可以实现相同的凸起效果。
• social 区块只会绘制其自带的图标集。要保留自定义图标，请将图标行放入带有重新托管图片的 html 区块中。

编辑模板（读取–修改–写入）

更新时，content 会被整体替换，绝不会合并；而且自你上次查看以来，用户可能已在 PostHog 的视觉编辑器中修改了设计：

1. workflows-get-email-template — 始终获取最新内容；返回的 design 是当前的事实来源。
2. 修改 design（同时保留 subject/text）。
3. workflows-update-email-template — 将完整的 content 传回。服务端会根据编辑后的设计重新渲染发送的邮件。
4. workflows-show-email-template — 渲染更新后的模板，让用户查看更改；其响应中包含最终渲染的 html，因此请在描述结果前先阅读。

对现有设计进行小幅修改时，优先使用 workflows-patch-email-template：它针对 Unlayer 区块执行按 ID 定位的操作，因此只需发送编辑内容，而无需发送整个设计。

编辑工作流步骤中的邮件

function_email 步骤包含自己的邮件快照（config.inputs.email.value 中的 subject/text/html/design），独立于任何模板库模板。 使用 workflows-patch-action-email 编辑：它支持与 workflows-patch-email-template 相同的设计操作，此外还支持用于合并 subject、preheader、text 和收件人的 email_patch。

1. workflows-get——步骤当前的设计（及其区块 ID）位于 config.inputs.email.value.design 中。
2. 使用 workflows-patch-action-email，并提供工作流 ID、步骤的 action_id 以及操作和／或 email_patch。如果操作更改了文案，同一次调用中的 email_patch 需要设置匹配的 text。
3. HTML 会在服务端根据修改后的设计重新渲染，因此不会过时。
4. 对于处于活动状态的工作流，编辑会暂存为草稿——使用 workflows-test-run（use_draft=true）进行测试，并使用 workflows-publish 应用。

使用模板

• 使用 workflows-list-email-templates 查看现有模板（仅显示元数据；获取单个模板以查看其内容）。
• 用户要求查看模板时，调用 workflows-show-email-template——它会渲染内嵌预览。
• 在工作流的 function_email 操作中引用模板（其 UUID 位于 config.template_uuid 中），或在 PostHog UI 中以该模板为基础创建广播。保存时，该步骤会获取模板正文的快照——之后编辑模板库中的模板，不会更改已使用该模板的步骤。要更改步骤的邮件，请使用 workflows-patch-action-email 修改该步骤。
• 模板通过使用 workflows-update-email-template 设置 deleted: true 软删除。