/designing-email-templates

name: designing-email-templates
description: 'Author, save, and edit email templates in the PostHog workflows library — compose email design JSON with Liquid personalization and create and round-trip-edit templates over MCP. Use when asked to design, build, update, or fix an email template for workflows, broadcasts, or campaigns.'

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](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](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](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 subp