newsletter-builder
  • Type to search the documentation.

API Reference

Compiler and linting

compileNewsletter, the plain-text generator, sanitisation and the deliverability linter.

compileNewsletter

signature
function compileNewsletter(
  doc: NewsletterDocument,
  options?: {
    variables?: Record<string, string>
    previewData?: Record<string, string>
    forceColorMode?: 'light' | 'dark'
  },
): CompiledEmail

interface CompiledEmail {
  html: string
  text: string
  subject: string
  preheader: string
  byteSize: number
  warnings: LintIssue[]
}

The output uses nested <table> layout and inline CSS only: no Flexbox, Grid or external stylesheets. It includes a hidden preheader, <meta name="color-scheme">, a prefers-color-scheme block for dark mode, a responsive stacking rule for columns, and VML for Outlook buttons.

Linter

using the linter
import { lintNewsletter } from 'newsletter-builder-react'

const issues = lintNewsletter(doc, html)
const blockers = issues.filter((issue) => issue.severity === 'error')
  • Empty subject or preheader
  • Images without alt text, with no source, or using relative or data: URLs
  • Buttons without a link
  • Missing unsubscribe link or postal address in the footer
  • HTML larger than 102 KB, which Gmail clips with a "View entire message" link

Sanitisation

Rich text is reduced to b, strong, i, em, u, a and br when it is compiled. Links are limited to http, https, mailto and tel; anything else (including javascript:) is dropped. Colours and numbers are validated before being written into inline styles.

utilities
import { sanitizeInlineHtml, sanitizeUrl, htmlToPlainText } from 'newsletter-builder-react'

sanitizeUrl('javascript:alert(1)') // ''
sanitizeInlineHtml('<b onclick="x()">Hi</b><script>x()</script>') // '<b>Hi</b>x()'