designing-email-templates

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.

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, the native blocks and spacing rules every email follows, 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.

Personalization with Liquid

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

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

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

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

({{ unsubscribe_url_one_click }} is also available for one-click list-unsubscribe flows.) A template written for Customer.io can keep its {% unsubscribe_url %} tag, which renders the same link as {{ unsubscribe_url }}.

Output is HTML-escaped by default, so a value renders as text even when it contains markup:

• Don't add | escape. It escapes a second time, and & reaches the inbox as &.
• For HTML your own backend builds, such as a summary list, add | raw: {{ variables.summary_html | raw }}. Never use raw on text a person typed.
• Format money with currency: {{ variables.amount | currency: "USD" }} renders $1,234.50. A value that isn't a number renders unchanged.

Click tracking and opt-out

Every link is automatically rewritten through a click-tracking redirect. This breaks mobile universal links / app deeplinks, which only resolve when the href stays on their own domain. To keep a link untracked, mark its anchor (use an html block) with clicktracking="off" or data-ph-no-track:

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

The marker must be on the <a> tag itself, not a child element. Opted-out links get no click metrics.

Images

Call media-images-list with purpose="email" first — reuse an existing image (a logo, a header banner) instead of uploading a duplicate.

To add a new image, upload it with the presigned flow rather than embedding bytes in the design:

1. media-image-upload-start with the file's name and purpose="email" — returns id, upload_url, and form_fields.
2. From a shell, POST the local file to upload_url: curl -X POST <upload_url> -F key=value... -F file=@/path/to/image.png (the form_fields from the response, file last). Never base64-encode image bytes into a tool call — a flipped token corrupts the image.
3. media-image-upload-complete with the id — returns the permanent url.

Put that url in the image block's values.src.url (see references/unlayer-design-json.md). The block also takes values.src.width/height; the media tools don't return dimensions, so if you have shell access to the local file, measure it yourself rather than guessing.

Images must be under 4MB and decode as PNG, JPEG, GIF, WebP, AVIF or BMP.

Creating a template

Call workflows-create-email-template with:

{
  "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 is required for email templates.
• Put the preview text that most inboxes show after the subject in the design's body.values.preheaderText. The rendered html carries it, so it reaches the inbox on every send path. Leave content.email.preheader unset, so the email carries one preview text.
• Always author the design and omit html - the server renders html from the design. Sending hand-written html without a design produces an email the visual editor can only show as one raw block.
• Always provide text as a real plain-text rendering of the message - clients that block rich content show only text, so filler like "placeholder" reaches real inboxes, and a text part that doesn't match the html hurts 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.

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.

Converting an existing HTML email

To move an email from another platform, rebuild it from native blocks instead of pasting its HTML into one html block, so people can still edit it:

• Each part of the source becomes the native block it shows: a heading, a text block per paragraph, a button per call to action, an image per picture. Keep the source's colors, font sizes, and padding on each block.
• Re-host every image through the media library (see Images). Put the file's real dimensions in src.width and src.height, and set the displayed width with src.maxWidth as a percentage of the content width. Source HTML often declares a height that doesn't match the file.
• A section the source wraps in {% if %} becomes a block with a display condition (see references/unlayer-design-json.md).
• Rename the source platform's Liquid variables to the ones this send provides. A transactional API send provides everything the caller passes in message_data as {{ variables.* }}.
• Buttons have no box-shadow. A 3px bottom border in a darker shade (border.borderBottomWidth, borderBottomStyle, borderBottomColor) gives the same raised look.
• The social block draws only its own icon sets. To keep custom icons, put the icon row in an html block with the re-hosted images.

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:

1. workflows-get-email-template — always fetch fresh; the returned design is the current source of truth.
2. Modify the design (keep subject/text alongside it).
3. workflows-update-email-template — send the complete content back. The server re-renders the sent email from the edited design.
4. 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.

For small changes to an existing design, prefer workflows-patch-email-template: id-addressed operations over the Unlayer blocks, so you send only the edit instead of the whole design.

Editing the email inside a workflow step

A function_email step carries its own email snapshot (config.inputs.email.value with subject/text/html/design), independent of any library template. Edit it with workflows-patch-action-email: the same design operations as workflows-patch-email-template, plus an email_patch merge for subject, preheader, text, and recipients.

1. workflows-get — the step's current design (and its block ids) is in config.inputs.email.value.design.
2. workflows-patch-action-email with the workflow id, the step's action_id, and your operations and/or email_patch. When the operations change the copy, the same call's email_patch sets a matching text.
3. The HTML is re-rendered server-side from the patched design, so it never goes stale.
4. On an active workflow the edit stages a draft — test with workflows-test-run (use_draft=true) and apply it with workflows-publish.

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 (its UUID in config.template_uuid), or start a broadcast from it in the PostHog UI. The step takes a snapshot of the template's body at save - editing the library template later does not change steps that already used it. To change a step's email, patch that step with workflows-patch-action-email.
• Templates are soft-deleted by setting deleted: true via workflows-update-email-template.