API

Everything exported, by entry point. All of it ships with TypeScript types.

@maildun/email-builder

No React, no DOM. Safe on servers, edge runtimes and in the browser.

Documents

Export	Description
createDocument({ settings?, theme?, blocks? })	A valid document from partial settings/theme and nested blocks. Throws on invalid input.
emptyDocument()	A blank document with default settings and theme.
DEFAULT_SETTINGS, DEFAULT_THEME	The defaults.
TEMPLATES, TemplateName, TemplateDefinition	Starter documents. See Templates.
SECTIONS, SECTION_NAMES, buildSection(name, params), SectionName, SectionDefinition	See Sections.
ROOT_ID	'root', the id of the document body.

Operations

Export	Description
applyOps(doc, ops, { customBlocks? })	Applies ops atomically. Returns { ok, document, changed, inserted, removed } or { ok: false, issues }.
applyOpsMaterialized(doc, ops, options?)	Same, one op at a time, and returns the ops with explicit ids.
materializeOp(doc, op)	One op with explicit ids for everything it creates.
OpSchema and InsertOpSchema … ReplaceDocumentOpSchema	Zod schemas for operations.
Op, InsertOp, UpdateOp, MoveOp, RemoveOp, DuplicateOp, ReplaceOp, UpdateSettingsOp, UpdateThemeOp, ReplaceDocumentOp, ApplyResult, ApplyOptions	Types.

See Operations.

Validation and lint

Export	Description
validateDocument(input)	{ ok: true, document } or { ok: false, issues }.
validateStructure(doc)	Tree checks only, for an already-typed document.
lintDocument(doc, options?)	Quality warnings. See Lint.
formatIssues(issues)	Issues as readable text.
issuesFromZod(error, options?), joinPath, aliasHint	Helpers for turning Zod errors into Issues, for hosts that validate their own input the same way.
Issue, LintWarning, LintOptions, ValidationResult	Types.

Schemas and types

Export	Description
DocumentSchema, SettingsSchema, ThemeSchema	Zod schemas.
BlockSchema, BlockInputSchema, HeadingBlockSchema …	Zod schemas for stored and nested input blocks.
BLOCK_DEFINITIONS, BLOCK_TYPES	Per-type schemas, defaults and docs.
canContain(parent, child), isContainerType(type), hasChildren(block)	Placement helpers.
documentJsonSchema(), blockInputJsonSchema(), opJsonSchema()	JSON Schemas.
FONT_FAMILIES, FONT_KEYS, resolveFontStack(font)	Font presets.
THEME_COLOR_TOKENS, resolveColor(color, theme), contrastRatio(fg, bg), mixColors(color, base, amount)	Colors.
DEFAULT_THEME_STYLES, resolveThemeStyles(theme), BUTTON_VARIANTS	Component styles.
resolvePadding(padding), isSafeUrl(url)	Value helpers.
ColorSchema, HexColorSchema, PaddingSchema, UrlSchema, BorderSchema, FontFamilySchema, FontWeightSchema, AlignSchema, VerticalAlignSchema, BlockIdSchema, the per-block *Props schemas, SocialLinkSchema	Zod schemas for the value types, to reuse in your own forms or custom blocks.
EmailDocument, Settings, Theme, Block, BlockOf<T>, BlockInput, BlockType, BlockProps<T>, BlockStyle<T>, BlockDefinition, ContainerBlock, FontKey, ThemeColorToken, ThemeStyles, ResolvedThemeStyles, ResolvedPadding	Types.

Tree

walk, findParent, childrenOf, descendantIds, ancestorIds, toBlockInput, normalizeBlockInputs (nested input to stored blocks; returns a NormalizeResult), the ParentInfo and ParentType types, and createId / createUniqueId for ids. See Reading the tree.

Custom blocks

Export	Description
defineBlock(definition)	Declares a custom block. See Custom blocks.
customBlockMap(list)	Definitions by name.
CUSTOM_BLOCK_NAME	The pattern a custom block name must match: lowercase letters, digits and dashes, starting with a letter, up to 64 characters.
validateCustomBlocks(doc, list, ids?)	Checks custom block data against the definitions.
CustomBlockDefinition, CustomBlockField, CustomRenderContext, CustomBlocks	Types.

Social and video

Export	Description
SOCIAL_NETWORKS, SOCIAL_LABELS, detectNetwork(url)	Supported networks.
socialIconUrl(assetsUrl, network, variant), DEFAULT_ASSETS_URL	Icon URLs.
SOCIAL_STARTER_URLS	The placeholder link a new icon starts with; lint flags it until it points at a profile.
SocialNetwork, SocialVariant	Types.
youtubeId(url), videoThumbnail(props)	Video helpers.

Renderer

Export	Description
renderEmail(doc, options?)	{ html, text, warnings }. See Rendering.
renderPlainText(doc, options?)	Only the plain-text version.
renderMarkdown, renderInlineMarkdown, markdownToPlainText	The restricted markdown renderer.
escapeHtml, safeUrl, protectMergeTags	Escaping helpers.
createRenderContext(doc, { annotate?, customBlocks?, assetsUrl? }), renderDocumentHtml, renderBlock, box, boxDeclarations, typeDeclarations, columnWidths, innerWidth	Building blocks for custom renderers.
RenderOptions, RenderResult, RenderWarning, RenderContext, BoxStyle, TypeStyle	Types.

@maildun/email-builder/editor

React 19. Marked 'use client'.

Export	Description
EmailEditor	The editor, with .Root, .TopBar, .Sidebar, .Stage, .Inspector, .Layout. See Editor props.
EditorRoot, EditorTopBar, EditorSidebar, EditorPalette, EditorStage, EditorInspector, EditorLayout, EditorProposalBar, Canvas	Parts.
useEditorStore, useEditorState, useVisibleDocument, useEditorOptions, useMessages	Hooks. See Custom layouts.
EditorProvider	Context provider, for advanced compositions.
EditorStore	The state store.
EN_MESSAGES, resolveMessages, EditorMessages	UI text. See Translations.
describeProposal(proposal, messages)	A short description of a proposal's changes, in the given UI language.
EmailEditorProps, EmailEditorHandle, EditorRootProps, EditorOptions, EditorState, Proposal, MergeTag, ImageResult, EditorView, Viewport, EditorSlot, EditorClassNames, PaletteGroup, PaletteGroupItem, EditorIcons, EditorIconName, ApplyOptions, EditorPanel, Toast, DeepPartial, LabelledItem, BlockCategory, PaddingSide	Types. See Editor props.

@maildun/email-builder/agent

Export	Description
createAgentSession(doc, options?)	In-memory document with tools.
createAgentTools(store, options?)	Tools bound to your own store.
runTool(tools, name, input)	Runs a tool call: { ok, content, data? }.
buildSystemPrompt(options?)	The system prompt.
blockCatalog(), customBlockCatalog(list), sectionCatalog(), templateCatalog()	Just the catalogs.
blockReference(type), sectionReference(name)	One block type or section in full, as get_reference returns it.
toAnthropicTools, toOpenAITools(tools, { simpleSchemas? }), toMcpTools	Provider adapters. toMcpTools includes titles and annotations.
simplifySchema(schema)	A tool schema without $refs and keywords strict APIs reject (Gemini, xAI).
isReadOnlyTool(tool)	True for tools that only read (annotations.readOnlyHint).
outlineDocument(doc), summarizeBlock(block)	The outline get_document returns.
AgentTool, AgentSession, AgentToolsOptions, DocumentStore, ToolResult, ToolAnnotations, SystemPromptOptions, OpenAIToolsOptions, JsonSchema	Types.

See Agent tools.

@maildun/email-builder/mcp

Node only (reads and writes files).

Export	Description
EmailMcpServer	The MCP server over a folder of email files. handle(message) answers one JSON-RPC message; instructions() and tools expose what it sends; dir is the resolved folder.
serveStdio(options?)	Runs the server on stdin/stdout, like email-builder mcp, and returns it. Logs the version and folder to stderr.
PROTOCOL_VERSIONS	MCP revisions it speaks, newest first.
McpServerOptions, JsonRpcMessage	Types.

See MCP server.

@maildun/email-builder/compat

Export	Description
EmailBuilderJsDocument, ImportResult	Types.
fromEmailBuilderJs(input)	{ document, warnings }. Throws when the input isn't an EmailBuilder.js document.
isEmailBuilderJsDocument(value)	Type guard.
escapeMarkdown(text)	Escapes markdown syntax so text renders literally.

See Migrating from EmailBuilder.js.

Stylesheets

Import	Use
@maildun/email-builder/styles.css	Precompiled, scoped. Any React app. Also available as editor.css.
@maildun/email-builder/core.css	For Tailwind CSS 4 + shadcn/ui apps.

See Styling and theming.