designing-email-templates

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Designing email templates

设计邮件模板

Use this skill when creating or editing email templates for PostHog workflows — broadcast campaigns and

function_email

workflow actions send the rendered template.

当你为PostHog工作流创建或编辑邮件模板时使用此技能——广播活动和

function_email

工作流操作会发送渲染后的模板。

How authoring works

创作机制

You author the design JSON (

content.email.design

) and save it with

workflows-create-email-template

. The server renders the sent email from your design with the same renderer PostHog's visual editor uses, so the template opens as editable blocks for humans and sends exactly what the design describes. Schema and a working example in references/unlayer-design-json.md.

When talking to the user, call it the template's design — the design document format is an internal implementation detail. Always share the template's

_posthogUrl

edit link in your reply after creating or updating, so the user can open it in PostHog directly.

Read references/design-guidelines.md before composing — it covers committing to a design direction, typography, color, and the patterns that make an email look designed rather than generated. For one fragment the block editor can't express, use an

html

-type content block inside the design.

你需要编写设计JSON（

content.email.design

）并通过

workflows-create-email-template

保存。服务器会使用与PostHog可视化编辑器相同的渲染器，根据你的设计渲染待发送邮件，因此模板会以可编辑区块的形式供人工编辑，且发送内容与设计完全一致。相关Schema和可用示例请查看references/unlayer-design-json.md。

与用户沟通时，将其称为模板的设计——设计文档格式属于内部实现细节。创建或更新模板后，务必在回复中分享模板的

_posthogUrl

编辑链接，方便用户直接在PostHog中打开。

编写设计前请阅读references/design-guidelines.md——其中涵盖了设计方向确定、排版、色彩，以及让邮件看起来更具设计感而非自动生成的模式。对于区块编辑器无法实现的内容片段，可在设计中使用

html

类型的内容区块。

Personalization with Liquid

使用Liquid实现个性化

Email content uses Liquid templating. Liquid tags pass through the renderer as plain text, so use them anywhere — block text, subject, links:

liquid

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

Marketing emails must include an unsubscribe link — render it with the built-in variables:

html

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

(

{{ unsubscribe_url_one_click }}

is also available for one-click list-unsubscribe flows.)

邮件内容采用Liquid模板语法。Liquid标签会以纯文本形式通过渲染器，因此可在任意位置使用——包括区块文本、主题、链接：

liquid

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

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

html

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

（

{{ unsubscribe_url_one_click }}

也适用于一键退订流程。）

Creating a template

创建模板

Call

workflows-create-email-template

with:

json

{
  "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": ["…"] } },
      "text": "Plain-text fallback of the same message"
    }
  }
}

```
subject
```
is required for email templates.
Always provide
```
text
```
— it's the fallback for clients that block rich content and improves deliverability.
The tool result returns an edit link into the PostHog library.
After creating (or updating), call
```
workflows-show-email-template
```
— it renders an inline preview so the user sees the result.

调用

workflows-create-email-template

时传入以下参数：

json

{
  "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": ["…"] } },
      "text": "Plain-text fallback of the same message"
    }
  }
}

```
subject
```
是邮件模板的必填项。
务必提供
```
text
```
内容——这是针对屏蔽富内容客户端的降级方案，同时可提升邮件送达率。
工具返回结果会包含PostHog库的编辑链接。
创建（或更新）后，调用
```
workflows-show-email-template
```
——它会生成内嵌预览，方便用户查看结果。

Payload mechanics

负载机制

Pass the design directly in the tool call — no scratch files, no pre-validation subprocesses, no payload preview rounds. Liquid tags (

{{ }}

{% %}

), apostrophes, single quotes, and emoji are ordinary characters inside JSON strings; only standard JSON escaping applies. Never rewrite content to avoid them — converting Liquid's single quotes to double quotes inside markup attributes breaks the markup. If the tool call is rejected as malformed, fix the JSON escaping and resend the same content unchanged.

直接在工具调用中传入设计内容——无需临时文件、预验证子流程或负载预览环节。Liquid标签（

{{ }}

{% %}

）、撇号、单引号和表情符号在JSON字符串中均为普通字符；仅需遵循标准JSON转义规则。切勿为了规避这些字符而重写内容——将标记属性内Liquid的单引号转换为双引号会破坏标记结构。若工具调用因格式错误被拒绝，只需修复JSON转义问题，重新发送原内容即可。

Editing a template (read–modify–write)

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

content

is replaced as a whole on update, never merged — and humans may have edited the design in PostHog's visual editor since you last saw it:

```
workflows-get-email-template
```
— always fetch fresh; the returned
```
design
```
is the current source of truth.
Modify the
```
design
```
(keep subject/text alongside it).
```
workflows-update-email-template
```
— send the complete
```
content
```
back. The server re-renders the sent email from the edited design.
```
workflows-show-email-template
```
— render the updated template so the user sees the change; its response carries the final rendered html, so read it before describing the result.

更新时会整体替换

content

，而非合并——且自你上次查看后，人工可能已在PostHog可视化编辑器中修改过设计：

```
workflows-get-email-template
```
——始终获取最新版本；返回的
```
design
```
是当前的可信数据源。
修改
```
design
```
（同时保留主题/文本内容）。
```
workflows-update-email-template
```
——将完整的
```
content
```
回传。服务器会根据编辑后的设计重新渲染待发送邮件。
```
workflows-show-email-template
```
——渲染更新后的模板供用户查看变更；其响应会包含最终渲染的HTML，因此在描述结果前请先阅读该内容。

Using templates

使用模板

List what exists with
```
workflows-list-email-templates
```
(metadata only; fetch one for its content).
When the user asks to see a template, call
```
workflows-show-email-template
```
— it renders an inline preview.
Reference a template from a workflow's
```
function_email
```
action, or start a broadcast from it in the PostHog UI.

Templates are soft-deleted by setting

deleted: true

via

workflows-update-email-template

通过
```
workflows-list-email-templates
```
列出所有模板（仅返回元数据；需单独获取模板内容）。
当用户要求查看模板时，调用
```
workflows-show-email-template
```
——它会生成内嵌预览。
在工作流的
```
function_email
```
操作中引用模板，或在PostHog UI中基于模板启动广播。

通过

workflows-update-email-template

设置

deleted: true

可实现模板软删除。