Documentation Reference
SDK reference
Look up mount options, live settings, methods, callbacks and document fields.
On this page
mount(target, options)
mount(target, options) returns an EditorInstance synchronously. target is an existing HTMLElement or CSS selector. Invalid configuration throws.
| Option | Use |
|---|---|
| editorKey | Required public editor key. Resolves the customer workspace and saved editor configuration. |
| userId / organizationId | Stable host namespaces. Prefer an explicit userId; organizationId is optional. |
| emailDocument | Complete versioned envelope for initial content, subject and preheader. |
| document / subject / preheader | Raw initial content and metadata; use instead of emailDocument. |
| draftId | Resume an existing hosted draft; do not combine with initial content or metadata. |
| editorConfig | Base configuration under explicit top-level preferences. Service restrictions still apply. |
| mode | edit, readonly, preview, previewDesktop or previewMobile. Requires SDK 0.1.7 and a compatible hosted editor. |
| theme / locale | Editor appearance and interface language. |
| mergeTags | Placeholder definitions: id, label, token, kind (text or url); optional description and sampleValue. |
| allowedBlocks | Insertion palette block IDs. Omit for dashboard defaults; [] hides every entry. |
| customBlocks | Array of versioned definitions: id, version, label, defaultProps, controls, render; optional iconSvg. Supported at mount, in editorConfig, in the React wrapper and through live updates. |
| displayConditions | Named layout rules: id, label, before, after; optional description and category. |
| enableTestEmail | Defaults to true. Set false to hide the toolbar test button; supports editorConfig and live updates. Your application can keep its own delivery flow. |
| Feature flags | See the feature preferences below. Dashboard restrictions still apply. |
updateConfig(config)
Live settings: mode, theme, locale, mergeTags, displayConditions, customBlocks, allowedBlocks, enableTemplates, enableAutosave, enableOrganizationBlocks, enableEmailAudit, enableTestEmail, enableAi.
Editor key, identity, initial content and draftId require a new mount. React follows the same rules.
Editor modes
| Mode | Behavior |
|---|---|
| edit | Normal editing (default). |
| readonly | Editor panes and toolbar visible; all controls disabled. |
| preview | Email preview with desktop/mobile switcher. |
| previewDesktop / previewMobile | Only the selected email preview, without editor controls. |
Instance methods
| Member | Result |
|---|---|
| ready | Promise<void>; resolves when the application accepts methods. |
| exportHTML() | Promise<EditorExport>: html, text, document, subject, preheader, mergeTags, mergeTagIssues; optional displayConditions, displayConditionIssues, requiresConditionEvaluation. Does not save or send. |
| previewTemplate() | Promise<EmailDocument>; envelope with an optional previewHtml snapshot. |
| flushAutosave() | Promise<{ draft }>; waits for hosted save acknowledgement. May return draft: null before a draft exists. |
| updateConfig(config) | void; updates supported live preferences. |
| destroy() | void; removes the iframe/listeners and cancels pending requests. Safe to call again. |
Callbacks
| Callback | When to use it |
|---|---|
| onReady() | Enable actions once the application-ready SDK has initialized the editor. |
| onError(error) | Show a useful integration error. Catch synchronous mount errors and method rejections separately. |
| onChange(document) | Observe raw content only; excludes the complete subject/preheader envelope. |
| onDocumentChange(email) | Observe the versioned envelope for host-managed persistence. Not a hosted save acknowledgement. |
| onDraftChange({ draftId, revision }) | Associate the hosted draft with a record in your application. |
| onSaveStatusChange(value) | Observe status, draftId and revision for hosted persistence. |
| onTestEmail(request) | Submit to your own backend. Return a promise that rejects on delivery-submission failure. |
EmailDocument
Save schemaVersion, content, subject and preheader together. Schema 1 is the base document; schema 2 supports display conditions; schema 3 adds custom-block references, props and validated HTML snapshots. previewHtml is an optional display snapshot. Reopen with emailDocument.
{
"schemaVersion": 1,
"content": { "type": "doc", "content": [] },
"subject": "Your next announcement",
"preheader": "A short preview for the inbox"
}Theme values
| Theme setting | Accepted values |
|---|---|
| mode | light or dark |
| Colors | primaryColor, backgroundColor, surfaceColor, shellColor, inputColor, textColor, mutedColor, borderColor: six-digit hex colors. |
| cornerRadius / density | 0–24 pixels; comfortable or compact. |
| fontFamily | Inter, Arial, Georgia or system-ui. |
Feature preferences
| Option | Controls |
|---|---|
| enableTemplates | Template chooser. |
| enableAutosave | Hosted drafts, saving and version history. |
| enableOrganizationBlocks | Organization block saving and reuse. |
| enableEmailAudit | Live content checks and rating. |
| enableTestEmail | Toolbar test-email button. |
| enableAi | AI actions, subject to paid access and dashboard settings. |
Custom blocks
Define host-rendered blocks with editable fields, automatic layout outlines or an optional iconSvg. Replacing customBlocks updates the registry without rewriting saved props or snapshots. See the guide for the definition contract, controls, SVG policy, versioning and schema-3 persistence.
Block IDs
allowedBlocks accepts: text, heading, button, image, video, gif, timer, menu, social, unsubscribe, list, html, space, divider, section, columns. This filters insertion tools; it does not validate or delete existing content. Include custom:<id> for each registered custom block you want to insert.
Save states and error codes
Hosted save status is one of idle, unsaved, saving, saved, failed, conflict or read-only. Preserve the current editor when a save fails; a callback describing a content change does not mean a save succeeded.
EditorError extends Error and exposes code. Handle not_ready, destroyed, reloaded, timeout, config_failed, invalid_config, autosave_disabled, export_failed and incompatible_editor. Retain the accompanying message for actionable feedback.
SDK readiness waits up to 15 seconds, export/template preview up to 20 seconds, and autosave flush up to 45 seconds. A timeout does not prove a server-side write failed.