API Reference

Complete API documentation for Email.md.

`render(markdown, options?)`

Renders markdown to email-safe HTML. Async since v0.3.0 — returns a Promise.

Returns Promise<{ html, text, meta, warnings? }>

html — complete HTML email document
text — plain text version for the text/plain MIME part
meta — extracted frontmatter metadata
warnings — non-fatal issues encountered while rendering (e.g. invalid frontmatter YAML). Omitted when empty. See RenderWarning.

import { render } from "emailmd";

const { html, text, meta } = await render("# Hello");

`RenderOptions`

{
  theme?: Partial<Theme>;
  wrapper?: 'default' | WrapperFn;
  minify?: boolean;
  fonts?: Record<string, string>;
  validationLevel?: 'skip' | 'soft' | 'strict';
  templateSyntax?: Array<{ prefix: string; suffix: string }>;
  sanitizeStyles?: boolean;
  beautify?: boolean;
}

Option	Type	Description
`theme`	`Partial<Theme>`	Override default theme values
`wrapper`	`'default' \| WrapperFn`	Custom email wrapper function
`minify`	`boolean`	Minify output HTML. Default `false`.
`fonts`	`Record<string, string>`	Custom web fonts: `{ [family]: url }` rendered as `<mj-font>`.
`validationLevel`	`'skip' \| 'soft' \| 'strict'`	MJML validation level. Default `'soft'`.
`templateSyntax`	`Array<{ prefix: string; suffix: string }>`	Template delimiters preserved during compilation. Default `[{{...}}, [[...]]]`.
`sanitizeStyles`	`boolean`	Sanitize template variables inside CSS before minification. Requires `minify: true`.
`beautify`	`boolean`	Pretty-print output HTML. Ignored when `minify: true`. Default `false`.

`RenderResult`

{
  html: string;
  text: string;
  meta: { preheader?: string; [key: string]: unknown };
  warnings?: RenderWarning[];
}

Property	Type	Description
`html`	`string`	Complete email-safe HTML document
`text`	`string`	Plain text version
`meta`	`object`	Extracted frontmatter metadata
`warnings`	`RenderWarning[]?`	Non-fatal issues (e.g. invalid frontmatter YAML). Omitted when empty.

`RenderWarning`

{
  stage: 'frontmatter';
  message: string;
  cause?: Error;
}

Property	Type	Description
`stage`	`'frontmatter'`	Which render stage produced the warning
`message`	`string`	Human-readable message
`cause`	`Error?`	Original thrown error, when one is available

When render() encounters an invalid frontmatter block, it returns empty meta and appends a warning instead of throwing. The html/text output still contains the rendered body, so UIs can keep the preview alive and surface the warning alongside it.

`Theme`

The full theme interface with all customizable properties:

interface Theme {
  brandColor: string;       // Links, highlights, accents
  headingColor: string;     // Heading text
  bodyColor: string;        // Body text
  backgroundColor: string;  // Outer background
  contentColor: string;     // Content area background
  cardColor: string;        // Callout / code block background
  buttonColor: string;      // Primary button background
  buttonTextColor: string;  // Button text
  secondaryColor: string;   // Secondary button border
  secondaryTextColor: string; // Secondary button text
  successColor: string;     // Success button background
  successTextColor: string; // Success button text
  dangerColor: string;      // Danger button background
  dangerTextColor: string;  // Danger button text
  warningColor: string;     // Warning button background
  warningTextColor: string; // Warning button text
  fontFamily: string;       // Font stack
  fontSize: string;         // Base font size (e.g. "16px")
  lineHeight: string;       // Base line height (e.g. "1.6")
  contentWidth: string;     // Email width (e.g. "600px")
}

Pass a Partial<Theme> to render() to override any subset of values. See Theme for defaults.

`darkTheme`

A pre-built dark theme object. Import and pass directly or spread with overrides:

import { render, darkTheme } from "emailmd";

// Use as-is
await render(md, { theme: darkTheme });

// Override specific values
await render(md, { theme: { ...darkTheme, brandColor: "#e11d48" } });

`buildHead(theme, preheader?)`

function buildHead(theme: Theme, preheader?: string): string;

Generates the MJML <mj-head> element containing global styles, font imports, and the hidden preheader text. Used when building custom wrappers.

`segmentsToMjml(segments, theme)`

function segmentsToMjml(segments: Segment[], theme: Theme): string;

Converts parsed content segments into MJML body elements (sections, columns, text, buttons, images, tables, etc.). Used when building custom wrappers.

`Segment`

interface Segment {
  type: 'text' | 'callout' | 'centered' | 'highlight' | 'header' | 'footer'
      | 'button' | 'button-group' | 'image' | 'hr' | 'table' | 'hero';
  content: string;
  attrs?: Record<string, string>;
  buttons?: Array<Record<string, string>>;
}

Represents a parsed block of content from the markdown. The segments array is what gets passed to segmentsToMjml and to custom wrapper functions.

`WrapperFn`

type WrapperFn = (
  segments: Segment[],
  theme: Theme,
  meta?: Record<string, unknown>,
) => string;

A function that receives parsed segments, the resolved theme, and frontmatter metadata, and returns a complete MJML string. See Wrappers for usage examples.

API Reference

On this page