Email builder
Build email templates visually with 12 email-safe Puck components and render them to client-compatible HTML.
Build email templates in Puck with 12 email-safe components. Every component renders table-based HTML with inline styles, for the widest email client compatibility.
Quick start
Edit with the email editor config, and render the saved data to an HTML string on the server:
// Visual editor: use emailEditorConfig
import { emailEditorConfig } from '@delmaredigital/payload-puck/email'
<PuckEditor config={emailEditorConfig} /* ...other props */ />// Server-side rendering: produce the email HTML string
import { renderToEmailHtml } from '@delmaredigital/payload-puck/email'
// subject / previewText / backgroundColor / fontFamily / maxWidth
// are read from the email's root props (edited in the builder).
const puckData = {
root: { props: { subject: 'Welcome!', previewText: 'Thanks for signing up', backgroundColor: '#f4f4f4' } },
content: [/* ... */],
}
// Optional second argument: { config } to override the email Puck config.
const html = renderToEmailHtml(puckData)Server and editor configs
Email configs follow the same split as page configs:
| Config | Import | Use it for |
|---|---|---|
emailBaseConfig | @delmaredigital/payload-puck/email | Server-side rendering with EmailRenderer or renderToEmailHtml() |
emailEditorConfig | @delmaredigital/payload-puck/email | The Puck editor, with interactive fields |
Email components
| Component | Description |
|---|---|
| EmailWrapper | Full-width outer container with background colour or image, and VML Outlook support |
| EmailSection | Centered content area with max-width, padding and background colour |
| EmailColumns | Two- or three-column table layout with a configurable gap |
| EmailHeading | Heading text (H1 to H4 sizes) with colour, alignment and font family |
| EmailText | Rich text through TipTap, converted to inline-styled email HTML on render |
| EmailButton | Bulletproof button (table plus anchor) for Outlook compatibility |
| EmailImage | Responsive image with optional link, from the Payload media library |
| EmailSpacer | Vertical spacing with configurable height |
| EmailDivider | Horizontal rule with colour and thickness options |
| EmailHeader | Logo image with optional title text |
| EmailFooter | Company name, address and unsubscribe link |
| EmailSocial | Social media icon links with configurable platforms |
Individual component configs (server, editor and types) are exported from @delmaredigital/payload-puck/email/components.
Rendering
Three levels of rendering, depending on what you need:
| Export | Returns | Use it for |
|---|---|---|
renderToEmailHtml(data, options?) | A complete HTML document string | Sending through an email API (Resend, SendGrid and so on) |
EmailRenderer | A React element | Embedding in a larger React email component |
getEmailDocumentParts(options) | { before, after } HTML strings | Your own wrapping around rendered content |
Root fields
The email editor config has root fields that control the whole email:
| Field | Type | Description |
|---|---|---|
subject | text | Email subject line |
previewText | textarea | Preview text shown in the inbox before opening |
backgroundColor | colour picker | Body background colour |
fontFamily | select | Web-safe font family |
maxWidth | number | Maximum content width (400 to 900px, default 600) |
Design constraints
Email components are deliberately more limited than page components, because of how email clients render:
- Table-based layouts only: no flexbox, grid or div layouts.
- Inline styles only: email clients strip CSS classes and
<style>blocks. - Web-safe fonts only: no custom font loading.
- No JavaScript: all interactivity is removed.
- VML fallbacks: background images use conditional comments for Outlook.
The plugin handles all of these for you. You design visually in Puck, and the server renderer produces compatible HTML.
Custom email components
Follow the same server/editor split, with three files per component:
MyEmail.types.ts: the props interface.MyEmail.server.tsx: the table-based render. Every<table>must have a<tbody>.MyEmail.editor.tsx: extends the server config and adds the field definitions.
Server components use inline styles only. @delmaredigital/payload-puck/email exports the helpers the built-in components use: TABLE_ATTRS, FULL_WIDTH_TABLE_STYLE, centeredTableStyle, emailAlign, alignmentToMargin, WEB_SAFE_FONTS, tiptapHtmlToEmailHtml, vmlBackgroundOpen and vmlBackgroundClose. The email CSS converters (colorValueToEmailCSS, paddingValueToEmailCSS, backgroundValueToEmailCSS) come from @delmaredigital/payload-puck/fields.