@unitpost/email

The email template model + cross-client HTML renderer that powers Unitpost. It's the exact same engine that renders your templates in the dashboard and at send time — so what you build with this package is byte-for-byte what your recipients receive.

Works standalone. No Unitpost account, API key, or network access is needed to render email HTML — install it and use it with any sender.

• JSON document model (EmailDocument) validated with Zod.
• Hand-written, table-based renderer (renderToHtml) tuned for Outlook, Gmail, Apple Mail, and the rest — inline styles, MSO-tolerant buttons, hoisted media queries, mobile column stacking. No React runtime.
• Constrained-TSX codec (parseTsx / printTsx) for a friendly, React-flavored authoring dialect.
• Pre-built layouts (SECTION_LAYOUTS) — ready-made headers, heroes, content cards, split columns, CTAs, and footers.
• Component catalog (COMPONENT_CATALOG) and ready-made samples (SAMPLE_TEMPLATES).

Try it live (no install) in the playground, and browse every component + layout with live previews at unitpost.com/components.

Install

npm install @unitpost/email zod

zod is a peer dependency (v4). Node.js 18+.

Render an email

import { parseTsx, renderToHtml, resolveVariables } from "@unitpost/email";

const doc = parseTsx(`
  <Section padding-x={24} padding-y={32}>
    <Heading level={1}>Hi {{first_name}} 👋</Heading>
    <Text>Welcome to {{product_name}}.</Text>
    <Button href="{{cta_url}}">Get started</Button>
  </Section>
`);

const { values } = resolveVariables(doc, {
  first_name: "Ada",
  product_name: "Unitpost",
  cta_url: "https://unitpost.com",
});

const html = renderToHtml(doc, values);

resolveVariables also returns missing — the referenced {{tokens}} you didn't provide a value for. Tokens left unresolved render literally (the raw {{token}} stays in the HTML), so check missing before sending:

const { values, missing } = resolveVariables(doc, { first_name: "Ada" });
if (missing.length > 0) throw new Error(`Unresolved: ${missing.join(", ")}`);

Variable values are always HTML-escaped, URLs are scheme-checked (javascript: never survives), and values are never re-interpolated — a value containing {{other}} stays literal.

The TSX dialect is a small, fixed vocabulary — the components below — not arbitrary JSX. That constraint is what guarantees cross-client output and lets the same document power a visual editor.

Compose from pre-built layouts

Don't start from a blank canvas: SECTION_LAYOUTS ships ready-made section bands (grouped as Header, Hero, Content, Columns, Call to action, Footer), each buildable and printable back to TSX.

import { getSectionLayout, printFragmentTsx } from "@unitpost/email";

const hero = getSectionLayout("hero-simple");
const tsx = printFragmentTsx(hero!.build()); // ready-to-adapt TSX

Browse them all with live previews at unitpost.com/components#layouts.

Or build the JSON document directly

The TSX codec is optional — EmailDocument is plain, Zod-validated JSON you can construct, store, and diff yourself:

import { emptyDocument, createBlock, renderToHtml } from "@unitpost/email";

const doc = emptyDocument();
doc.blocks.push(
  createBlock("heading", { text: "Hello", level: 1 }),
  createBlock("text", { text: "Built as data, rendered as email." }),
);

const html = renderToHtml(doc, {});

Start from a sample

import { getSampleTemplate, renderToHtml } from "@unitpost/email";

const welcome = getSampleTemplate("welcome");
const html = renderToHtml(welcome!.design, {});

Ready-to-send full designs are also free to preview and copy in the template gallery.

API surface

The package root (@unitpost/email) exposes the supported public API:

| Area | Exports | | ------------- | ------- | | Document model | EmailDocument, EmailDocumentSchema, parseDocument, migrateDocument, COMPONENT_DEFAULTS, STYLE_TOKENS, TEMPLATE_CATEGORIES, block/type unions | | Rendering | renderToHtml, resolveVariables, resolveVariablesWithContact, collectVariables, documentHasPerRecipientVariables, RenderOptions | | Codec | parseTsx, printTsx, printFragmentTsx, TsxParseError | | Catalog | COMPONENT_CATALOG, COMPONENT_GROUPS, COMMON_PROPS, getComponentDoc, resolvePropDefault | | Layouts | SECTION_LAYOUTS, LAYOUT_GROUPS, getSectionLayout | | Samples | SAMPLE_TEMPLATES, getSampleTemplate | | Sanitizer | sanitizeEmailHtml, safeUrl, safeImageUrl, hasForbiddenHtml | | Helpers | createBlock, createRow, regenerateBlockIds, emptyDocument, safeParseDocument, BLOCK_LABELS, FONT_STACKS | | Styling | compileClasses, cssToUtilities (the Tailwind → inline-CSS compiler the renderer uses) |

Editor-only internals (the TipTap bridge, document tree-ops, editor diagnostics) are not part of the public API.

Using it with Unitpost (optional)

The same document is what the Unitpost dashboard's template editor edits and what the send API accepts as a template design — so anything you build here drops straight into a workspace when you want managed sending, or stays entirely in your own stack when you don't.

Docs & links

• Component + layout reference (live previews, props): https://unitpost.com/components
• Playground (render in the browser): https://unitpost.com/playground
• Template gallery: https://unitpost.com/templates/gallery
• Changelog: CHANGELOG.md

License

MIT