Appearance

Lettr — the email API from the team behind Topol EditorThe email API that ships in an afternoonFrom the team behind Topol Editor

Options configurable in Topol Options ​

Topol options is the configuration object passed to TopolPlugin.init(), enabling or disabling editor features and registering the callbacks the editor fires back to the host. Callbacks live under the callbacks key of the options object (see the Callbacks Reference below); the full interface is at the bottom of this page.

Options Reference ​

authorizeobjectrequired

Required API key and user ID pair that initializes the editor. The token only works on domains listed in its configuration. Learn more

apiIAPI

Maps editor features to your own backend endpoint URLs; when omitted, the editor uses Topol's built-in endpoints. Learn more

apiAuthorizationHeaderstring | object

Authorization header attached to requests sent to your configured API endpoints. Learn more

apiBlocksobject

Definitions of Custom API Blocks that pull items from your own feed endpoints. Requires Plugin for Business plan or higher. Learn more

autosaveIntervalnumber default: 60

Interval in seconds between autosave attempts; values below 30 are raised to 30. Learn more

betaFeaturesobject default: all off

Opt-in flags for experimental content blocks (carousel, rating; the loop flag is accepted but currently not read). Options, styling and rendered HTML of beta blocks may change in future releases. Learn more

chatAIboolean default: false

Enables the conversational AI Chat panel that receives the whole template as context. Requires Plugin Expansion plan or higher, plus AI configured on the account. Learn more

chatAIOnSegmentboolean default: false

Adds an AI Chat icon to individual sections, scoping the conversation to that section. Read only when chatAI is set; requires Plugin Expansion plan or higher. Learn more

colorsstring[]

Custom palette shown in the editor's color picker; a non-empty array replaces the built-in swatches. Learn more

contentBlocksobject

Per-block flags that disable, hide, or annotate individual content blocks in the sidebar. Validated as a whole - one unrecognized block name discards the entire configuration. Learn more

currentUserIOptionsUser

Identity of the person using the editor, used for autosave and comment attribution. Learn more

customBlocksCustomBlockData[]

Your own block definitions added to the editor's block sidebar. Requires Plugin for Business plan or higher. Learn more

customFileManagerboolean default: false

Replaces the built-in File Manager with a callback into your own file-picking UI. Requires Plugin for Business plan or higher. Learn more

customFontsobject

Fonts offered in the editor's font dropdown, appended to the built-in list (or replacing it with override: true). Not stored in the template, so supply it on every init. Learn more

defaultTemplateSettingsobject

Preset widths, colors and typography applied to newly created templates; loading a saved template replaces them. Learn more

disableAiAssistantboolean default: false

Disables the per-block AI writing assistant, which is on by default when the account has AI configured; also hides the Translate button in the Top Bar. Learn more

disableAlertsboolean default: false

Stops the editor rendering its own notifications and routes them to the onAlert callback instead. Learn more

disableExtendedComparatorsboolean default: false

Removes the four numeric comparators from the conditional-content condition picker. Read only when enableSectionVariants is on. Learn more

emailServiceProvider"mailchimp" | "sparkpost"

Selects whether conditional and dynamic syntax is generated for Mailchimp or SparkPost. Dynamic product and API block modes require "sparkpost". Learn more

enableAutosavesboolean default: false

Turns on periodic draft saving of the template to your own API endpoints (needs the AUTOSAVES, AUTOSAVE and GET_AUTOSAVE api paths). Learn more

enableCommentsboolean default: false

Enables in-template commenting and conversation threads. Requires Plugin for Business plan or higher. Learn more

enableDarkModeboolean default: false

Adds a dark mode toggle to the preview screen. Learn more

enableFileManagerInGifboolean default: false

Exposes the custom file manager inside the GIF block's Custom Source tab; requires customFileManager: true. Learn more

enableImageToTextRatioboolean default: false

Shows the template's image-to-text ratio in the Top Bar during Preview mode. Learn more

enableMergeTagPreviewboolean default: false

Replaces merge tags with test values inside Preview mode. Learn more

enableSectionVariantsboolean default: false

Unlocks the UI for adding conditional variants to sections. Requires Plugin for Business plan or higher. Learn more

enableSubjectLineboolean default: false

Exposes a subject line field in the template settings tab. Learn more

fileManagerPreferencesobject

UI preferences for the built-in File Manager: the default file view (list or tiles), the Pexels integration, and the batch upload cap. Learn more

fontSizesnumber[]

Font sizes offered in the size dropdown, as unitless pixel numbers; always replaces the default list (in the callout below). Learn more

googleApiKeystring

Google API key intended for Google Fonts in the image editor's text tool; its only consumer is a legacy component that is no longer mounted, so the option currently has no effect. Learn more

helpdeskIHelpdesk

Configures contextual help links shown in the editor's panel. Currently not covered by the guide.

hideControlPanelboolean default: false

Starts the editor with the control panel collapsed. Learn more

showControlPanelExpandboolean default: false

Renders the editor's built-in toggle for showing and hiding the control panel; used in combination with hideControlPanel. Learn more

hideSettingsTabboolean default: false

Removes the template settings tab from the control panel. Learn more

htmlMinifiedboolean default: false

Outputs minified HTML on export.

imageCompressionOptionsobject

Quality and toggle settings for the automatic resize and re-encode applied to uploaded images (defaults in the callout below). Custom file manager uploads bypass this pipeline. Learn more

imageEditorboolean

Legacy flag that is accepted but never read - the built-in image editor is always the current version.

imageEditorOptionsobject

Names of Image Editor control-panel sections to hide. Learn more

imageMaxSizenumber default: 2097152 (2 MB)

Maximum size in bytes of an image uploaded through the built-in File Manager, checked after resize and compression. Learn more

languagestring default: "en"

Two-letter ISO 639-1 code selecting the editor interface language; regional variants such as pt-BR are rejected. Learn more

languageMergeTagstring default: "TOPOL_TEMPLATE_LANG"

Name of the merge tag used for language-based section variants. Learn more

lightboolean default: false

Switches the editor interface to the light preset instead of the default dark one. Keep it consistent with theme.preset. Learn more

logicalOperatorsInsideVariantboolean

Allows chaining several conditions on one variant with AND or OR. Defaults on for SparkPost and off for Mailchimp. Learn more

mergeTagsarray

Groups and definitions of the merge tags users can insert into a template; passing the option replaces the built-in sample group (*|FIRST_NAME|*). Learn more

mobileFirstEnabledboolean default: false

Turns on the mobile/desktop canvas switch and per-device visibility controls. An editing aid only - generated HTML is unchanged. Learn more

multilingualboolean default: false

Enables multilingual template mutations and the language switcher; also switched on automatically when defaultTemplateSettings.langs is set. Learn more

premadeBlocksobject | boolean

Collections of prepared sections users can insert in one click. When omitted, Topol's bundled examples load; false hides the tab entirely. Learn more

premadeTemplatesboolean default: false

Shows the premade template picker when the editor opens on an empty template. Learn more

premadeTemplatesOptionsobject

Controls two elements of the premade template picker: the search input (hideSearch) and the per-template Delete button (showDelete). Learn more

productMergetagTagsarray

Merge tags offered in the product block's dynamic dropdown; label is shown to the user, value is used by the renderer. The dropdown appears only when the provider supports dynamic blocks (emailServiceProvider: "sparkpost"). Learn more

role"manager" | "editor" | "reader"

Predefined permission role for the user; when unset, the role system is off and nothing is restricted. Requires Plugin for Business plan or higher. Learn more

permissionsobject

Individual permission flags applied on top of the selected role; ignored unless role is also set. Learn more

savedBlocksISavedBlock[] | boolean default: false

Enables the saved blocks library, seeded with a local array of blocks (every block needs an id; one invalid block rejects the whole array). Learn more

syncedSectionsEnabledboolean default: false

Enables sections that stay synchronized across every template using them. Requires api.SAVED_SECTIONS; synced sections must be resolved server-side before rendering final HTML. Learn more

showUnsavedDialogBeforeExitboolean default: true

Controls the browser confirmation shown when leaving the editor with unsaved changes. Only the literal value false disables it. Learn more

smartMergeTagsobject

Makes inserted merge tags clickable and swappable, and defines the merge tag syntax (default delimiters *| and |*). The enabled key is mandatory whenever the object is passed. Learn more

teamUsersIOptionsUser[]

List of colleagues who can be @mentioned in comment threads; the current user is filtered out automatically. Learn more

templateIdnumber | string

Identifier of the open template, sent with comment and autosave API requests. Learn more

testingEmailsboolean | string[]

Switches test sends to multi-recipient mode: true keeps the address list in local storage, an array (capped at five) seeds it directly. In this mode the onTestSend email argument is always an array. Learn more

textEditor"tinymce" | "tiptap" default: "tinymce"

Selects which rich-text engine powers text blocks. Learn more

themeITheme default: dark preset

Custom overrides for the editor interface colors, border radius and font - the editor UI, not the emails. Requires Plugin Expansion plan or higher. Learn more

tinyConfigunknown

Configuration object passed through to the TinyMCE text editor; merged only one level deep, so any key you set replaces Topol's default for that key outright. Learn more

tiptapConfigobject default: { light: true }

Configuration for the Tiptap editor: a light-toolbar flag and a merge-tag-name display flag. Passing the object replaces the default wholesale, so include light explicitly. Effective only when textEditor: "tiptap". Learn more

titlestring default: "E-mail editor 3.0"

Template name displayed in the editor header. Learn more

topBarOptionsstring[]

List of which Top Bar buttons are shown; empty or unset shows everything, unknown values are ignored silently. Learn more

renameTemplateboolean default: false

Adds a pencil icon next to the template name that fires the onTemplateRename callback. The editor does not rename anything itself - call TopolPlugin.setTemplateName() to reflect the new name. Learn more

removeTopBarboolean default: false

Removes the editor's default Top Bar entirely; saving and closing then become the host application's responsibility. Learn more

windowBarstring[]

Controls shown in the optional Window Bar (fullscreen, close); the bar is hidden when unset. close requires an onClose callback and does not save first. Learn more

Defaults worth knowing

  • fontSizes default list: 11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 24, 30, 36, 48, 64.
  • imageCompressionOptions defaults: qualityJpeg: 0.95, qualityPng: 0.8, enableAutoResize: true, enableCompression: true.
  • When theme is not set, the editor uses the dark preset (light: true switches it to light); unknown presets fall back to dark.
  • Plan gating is silent: on plans below the required tier, gated options (role, permissions, enableComments, apiBlocks, customBlocks, customFileManager, enableFileManagerInGif, enableSectionVariants, self-hosted api file endpoints, chatAI, chatAIOnSegment, theme) are ignored with only a console warning.
  • A few schema-accepted options currently do nothing: imageEditor, betaFeatures.loop, and googleApiKey.

Callbacks Reference ​

Callbacks are registered under the callbacks key inside the options object (unlike the Landing Page Editor, where they sit next to config):

js
TopolPlugin.init({
  authorize: { apiKey: "YOUR_API_KEY", userId: "user-123" },
  callbacks: {
    onSave(json, html, mutations, syncedSections) {
      /* ... */
    },
  },
});
onSave(json, html, mutations, syncedSections)

Fires when Save is clicked or TopolPlugin.save() is called, handing over the template to store. Learn more

onSaveAndClose(json, html, mutations, syncedSections)

Fires when the Save and Close button in the Top Bar is clicked. Learn more

onTestSend(email, json, html)

Fires when a user sends a test email from the preview screen. email is a single address unless testingEmails is set, in which case it is always an array. Learn more

onOpenFileManager()

Fires when a user clicks "Choose a file" in image, video or GIF properties; answer it with TopolPlugin.chooseFile(). Learn more

onImageDelete(items)

Fires after one or more files or folders are successfully deleted from the built-in File Manager. Learn more

onLoaded()

Fires after TopolPlugin.load() finishes rendering the template. Learn more

onBlockSave(block)

Fires when a user saves a section to the saved blocks library in local-array mode; never fires for synced sections. Learn more

onBlockRemove(blockId)

Fires when a user removes a saved block in local-array mode; stops firing once api.SAVED_SECTIONS is configured. Learn more

onBlockEdit(blockId)

Fires when a user edits an existing saved block in local-array mode; stops firing once api.SAVED_SECTIONS is configured. Learn more

onInit()

Fires when the editor is fully initialized. Learn more

onUndoChange(count)

Fires when Undo is used, reporting how many steps have been undone. Learn more

onRedoChange(count)

Fires when Redo is used, reporting how many steps have been redone. Learn more

onPreview(html)

Fires when the user enters Preview mode, with the rendered HTML. Learn more

onPreviewClose()

Fires when the user leaves the preview screen using the editor's preview toggle (not when the host exits preview programmatically). Learn more

onAlert(notification)

Receives each editor notification in place of the built-in toast; fires only while disableAlerts is true. Learn more

onClose()

Fires when a user closes the editor from the Top Bar close control. Closing does not save first. Learn more

onEdittedWithoutSaveChanged(hasUnsavedChanges)

Reports whether the template currently holds unsaved changes, on every transition in both directions. Learn more

onOpenCustomBlockDialog(customBlock)

Fires when a user clicks the dialog button on a custom block defined with dialog: true; answer it with TopolPlugin.updateCustomBlockContent(). Learn more

onTemplateRename(title)

Fires when a user clicks the rename icon in the editor header (requires renameTemplate: true). title is the current template name - the editor has no rename input of its own, so collect the new name in your UI and apply it with TopolPlugin.setTemplateName(). Learn more

onTemplateUpdated()

Fires after a programmatic TopolPlugin.updateTemplate() call has successfully applied the new template JSON. Learn more

updateTestingEmailAddresses(emails)

Fires when a user edits the list of test email addresses in the preview screen; relevant when testingEmails is an array. Learn more

onError(type, message, responseBody?)

Fires when the editor hits an unrecoverable error, with type one of templateLoad, network, authorize or updateTemplate. responseBody is undefined for network errors with no response. Learn more

onLanguageCreated(lang, mutations)

Fires when a new language mutation is created from the UI or via TopolPlugin.createLanguage(). Learn more

onLanguageDeleted(lang, mutations)

Fires when a language mutation is deleted, after the confirmation modal. Learn more

onLanguageSelected(lang)

Fires when the active editing language changes - including as a side effect of creating, deleting, or changing the primary mutation. Learn more

onPrimaryLanguageChanged(lang, mutations)

Fires when the primary language mutation changes; creates the language first (also firing onLanguageCreated) if it does not exist. Learn more

onGetMutations(mutations)

Fires in response to TopolPlugin.getMutations(), returning the current list of language mutations. Learn more

TypeScript Interface ​

ts
export default interface IPluginOptions {
  authorize: {
    apiKey: string;
    userId: string | number;
  };
  api?: IAPI;
  apiAuthorizationHeader?: IAuthHeaderConfig | string;
  apiBlocks?: Record<string, IAPIBlockProperties>;
  autosaveInterval?: number;
  betaFeatures?: {
    carousel?: boolean;
    loop?: boolean;
    rating?: boolean;
  };
  chatAI?: boolean;
  chatAIOnSegment?: boolean;
  colors?: Array<string>;
  contentBlocks?: IContentBlockOptions;
  currentUser?: IOptionsUser;
  customBlocks?: CustomBlockData[];
  customFileManager?: boolean;
  customFonts?: {
    override?: boolean;
    fonts: Array<IFont>;
  };
  defaultTemplateSettings?: {
    emailWidth?: number;
    emailBackgroundColor?: string;
    blockBackgroundColor?: string;
    buttonsBackgroundColor?: string;
    hyperlinkColor?: string;
    h1?: {
      [key in TopolTagAttribute]?: string;
    };
    h2?: {
      [key in TopolTagAttribute]?: string;
    };
    h3?: {
      [key in TopolTagAttribute]?: string;
    };
    p?: {
      [key in TopolTagAttribute]?: string;
    };
    button?: {
      [key in TopolTagAttribute]?: string;
    };
    "line-height"?: number;
    "structure-margin"?: string;
  };
  disableAiAssistant?: boolean;
  disableAlerts?: boolean;
  disableExtendedComparators?: boolean;
  emailServiceProvider?: "mailchimp" | "sparkpost";
  enableAutosaves?: boolean;
  enableComments?: boolean;
  enableDarkMode?: boolean;
  enableFileManagerInGif?: boolean;
  enableImageToTextRatio?: boolean;
  enableMergeTagPreview?: boolean;
  enableSectionVariants?: boolean;
  enableSubjectLine?: boolean;
  fileManagerPreferences?: {
    defaultTilesView?: boolean;
    hidePexelsIntegration?: boolean;
    maxUploadingFiles?: number;
  };
  fontSizes?: Array<number>;
  googleApiKey?: string;
  helpdesk?: IHelpdesk;
  hideControlPanel?: boolean;
  showControlPanelExpand?: boolean;
  hideSettingsTab?: boolean;
  htmlMinified?: boolean;
  imageCompressionOptions?: {
    qualityJpeg?: number;
    qualityPng?: number;
    enableAutoResize?: boolean;
    enableCompression?: boolean;
  };
  imageEditor?: boolean;
  imageEditorOptions?: {
    hideControls?: Array<string>;
  };
  imageMaxSize?: number;
  language?: string;
  languageMergeTag?: string;
  light?: boolean;
  logicalOperatorsInsideVariant?: boolean;
  mainMenuAlign?: "left" | "right";
  mergeTags?: Array<IMergeTagGroup | IMergeTag>;
  mobileFirstEnabled?: boolean;
  multilingual?: boolean;
  premadeBlocks?: Object | boolean;
  premadeTemplates?: boolean;
  premadeTemplatesOptions?: {
    hideSearch?: boolean;
    showDelete?: boolean;
  };
  productMergetagTags?: Array<{
    label: string;
    value: string;
  }>;
  role?: "manager" | "editor" | "reader";
  permissions?: {
    canLockBlocks?: boolean;
    canLockSections?: boolean;
    canEditLockedSections?: boolean;
    canEditLockedBlocks?: boolean;
    canRemoveFiles?: boolean;
  };
  savedBlocks?: Array<ISavedBlock> | boolean;
  syncedSectionsEnabled?: boolean;
  showUnsavedDialogBeforeExit?: boolean;
  smartMergeTags?: {
    enabled: boolean;
    patterns?: Record<string, SmartMergeTagPattern>;
    syntax?: {
      start: string;
      end: string;
    };
  };
  teamUsers?: IOptionsUser[];
  templateId?: number | string;
  testingEmails?: boolean | string[];
  textEditor?: "tinymce" | "tiptap";
  theme?: ITheme;
  tinyConfig?: unknown;
  tiptapConfig?: {
    light?: boolean;
    showMergeTagText?: boolean;
  };
  title?: string;
  topBarOptions?: Array<string>;
  renameTemplate?: boolean;
  removeTopBar?: boolean;
  windowBar?: Array<string>;
  callbacks: {
    onSave?(
      json: JSON,
      html: HTMLDocument,
      mutations: { lang: string; primary: boolean }[],
      syncedSections: number[]
    ): void;
    onSaveAndClose?(
      json: JSON,
      html: HTMLDocument,
      mutations: { lang: string; primary: boolean }[],
      syncedSections: number[]
    ): void;
    onTestSend?(email: string | string[], json: JSON, html: HTMLDocument): void;
    onOpenFileManager?(): void;
    onImageDelete?(items: IDeletedItem[]): void;
    onLoaded?(): void;
    onBlockSave?(block: ISavedBlock): void;
    onBlockRemove?(blockId: Number): void;
    onBlockEdit?(blockId: Number): void;
    onInit?(): void;
    onUndoChange?(count: Number): void;
    onRedoChange?(count: Number): void;
    onPreview?(html: HTMLDocument): void;
    onPreviewClose?(): void;
    onAlert?(notification: INotification): void;
    onClose?(): void;
    onEdittedWithoutSaveChanged?(hasUnsavedChanges: boolean): void;
    onOpenCustomBlockDialog?(customBLock: unknown): void;
    onTemplateRename?(title: string): void;
    onTemplateUpdated?(): void;
    updateTestingEmailAddresses?(emails: string[]): void;
    onError?(type: string, message: string, responseBody?: unknown): void;
    onLanguageCreated?(
      lang: string,
      mutations: { lang: string; primary: boolean }[]
    ): void;
    onLanguageDeleted?(
      lang: string,
      mutations: { lang: string; primary: boolean }[]
    ): void;
    onLanguageSelected?(lang: string): void;
    onPrimaryLanguageChanged?(
      lang: string,
      mutations: { lang: string; primary: boolean }[]
    ): void;
    onGetMutations?(mutations: { lang: string; primary: boolean }[]): void;
  };
}

The onImageDelete callback receives an array of IDeletedItem entries, one per deleted file or folder:

ts
interface IDeletedItem {
  name: string;
  type: "file" | "folder";
  path: string;
  url?: string;
  key: string | null;
}

See the Callbacks guide for a description of each field.