---
title: "Topol Options"
description: "Complete Reference of all Topol Options that can be found in Topol email editor. Options are used to enable or disable certain functionality."
url: https://docs.topol.io/email-editor/reference/topol-options.html
---

# 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](#callbacks-reference) below); the full interface is at the [bottom of this page](#typescript-interface).

## Options Reference

#### `authorize` — type: `object`, required

Required API key and user ID pair that initializes the editor. The token only works on domains listed in its configuration. [Learn more](https://docs.topol.io/email-editor/guide/getting-started.html#step-2-add-the-plugin-to-your-application)

#### `api` — type: `IAPI`

Maps editor features to your own backend endpoint URLs; when omitted, the editor uses Topol's built-in endpoints. [Learn more](https://docs.topol.io/email-editor/guide/how-to-work-with-your-api.html#how-to-set-this-up)

#### `apiAuthorizationHeader` — type: `string | object`

Authorization header attached to requests sent to your configured API endpoints. [Learn more](https://docs.topol.io/email-editor/guide/security.html#setting-the-authorization-header)

#### `apiBlocks` — type: `object`

Definitions of Custom API Blocks that pull items from your own feed endpoints. Requires Plugin for Business plan or higher. [Learn more](https://docs.topol.io/email-editor/guide/custom-api-blocks.html#how-to-configure-a-custom-api-block)

#### `autosaveInterval` — type: `number`, default: `60`

Interval in seconds between autosave attempts; values below 30 are raised to 30. [Learn more](https://docs.topol.io/email-editor/guide/autosaves.html#setting-the-autosave-frequency)

#### `betaFeatures` — type: `object`, 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](https://docs.topol.io/email-editor/guide/beta-features.html#enabling-beta-features)

#### `chatAI` — type: `boolean`, 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](https://docs.topol.io/email-editor/guide/chat-ai.html#how-to-enable-ai-chat)

#### `chatAIOnSegment` — type: `boolean`, 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](https://docs.topol.io/email-editor/guide/chat-ai.html#chat-on-a-single-section)

#### `colors` — type: `string[]`

Custom palette shown in the editor's color picker; a non-empty array replaces the built-in swatches. [Learn more](https://docs.topol.io/email-editor/guide/custom-color-palette.html#set-custom-colors)

#### `contentBlocks` — type: `object`

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](https://docs.topol.io/email-editor/guide/content-block-options.html#configuration)

#### `currentUser` — type: `IOptionsUser`

Identity of the person using the editor, used for autosave and comment attribution. [Learn more](https://docs.topol.io/email-editor/guide/current-user.html)

#### `customBlocks` — type: `CustomBlockData[]`

Your own block definitions added to the editor's block sidebar. Requires Plugin for Business plan or higher. [Learn more](https://docs.topol.io/email-editor/guide/custom-block.html#creating-a-basic-custom-block)

#### `customFileManager` — type: `boolean`, 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](https://docs.topol.io/email-editor/guide/custom-filemanager.html#disable-the-built-in-file-manager)

#### `customFonts` — type: `object`

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](https://docs.topol.io/email-editor/guide/custom-fonts.html#how-to-set-custom-fonts-in-the-plugin)

#### `defaultTemplateSettings` — type: `object`

Preset widths, colors and typography applied to newly created templates; loading a saved template replaces them. [Learn more](https://docs.topol.io/email-editor/guide/default-settings.html#available-default-settings)

#### `disableAiAssistant` — type: `boolean`, 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](https://docs.topol.io/email-editor/guide/ai-assistant.html#how-to-enable-the-ai-assistant)

#### `disableAlerts` — type: `boolean`, default: `false`

Stops the editor rendering its own notifications and routes them to the `onAlert` callback instead. [Learn more](https://docs.topol.io/email-editor/guide/custom-notifications.html#disabling-built-in-alerts)

#### `disableExtendedComparators` — type: `boolean`, default: `false`

Removes the four numeric comparators from the conditional-content condition picker. Read only when `enableSectionVariants` is on. [Learn more](https://docs.topol.io/email-editor/guide/conditional-content.html#comparators)

#### `emailServiceProvider` — type: `"mailchimp" | "sparkpost"`

Selects whether conditional and dynamic syntax is generated for Mailchimp or SparkPost. Dynamic product and API block modes require `"sparkpost"`. [Learn more](https://docs.topol.io/email-editor/guide/conditional-content.html#conditional-syntax)

#### `enableAutosaves` — type: `boolean`, 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](https://docs.topol.io/email-editor/guide/autosaves.html#enabling-autosaves)

#### `enableComments` — type: `boolean`, default: `false`

Enables in-template commenting and conversation threads. Requires Plugin for Business plan or higher. [Learn more](https://docs.topol.io/email-editor/guide/comments.html)

#### `enableDarkMode` — type: `boolean`, default: `false`

Adds a dark mode toggle to the preview screen. [Learn more](https://docs.topol.io/email-editor/guide/dark-mode-preview.html#configuration)

#### `enableFileManagerInGif` — type: `boolean`, default: `false`

Exposes the custom file manager inside the GIF block's Custom Source tab; requires `customFileManager: true`. [Learn more](https://docs.topol.io/email-editor/guide/custom-filemanager.html#use-custom-file-manager-in-the-gif-block)

#### `enableImageToTextRatio` — type: `boolean`, default: `false`

Shows the template's image-to-text ratio in the Top Bar during Preview mode. [Learn more](https://docs.topol.io/email-editor/guide/image-to-text-ratio.html#enabling-the-ratio)

#### `enableMergeTagPreview` — type: `boolean`, default: `false`

Replaces merge tags with test values inside Preview mode. [Learn more](https://docs.topol.io/email-editor/guide/merge-tag-previews.html)

#### `enableSectionVariants` — type: `boolean`, default: `false`

Unlocks the UI for adding conditional variants to sections. Requires Plugin for Business plan or higher. [Learn more](https://docs.topol.io/email-editor/guide/conditional-content.html#enabling-conditional-content)

#### `enableSubjectLine` — type: `boolean`, default: `false`

Exposes a subject line field in the template settings tab. [Learn more](https://docs.topol.io/email-editor/guide/subject-line.html#configuration)

#### `fileManagerPreferences` — type: `object`

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](https://docs.topol.io/email-editor/guide/file-manager-preferences.html#how-to-set-your-preferences)

#### `fontSizes` — type: `number[]`

Font sizes offered in the size dropdown, as unitless pixel numbers; always replaces the default list (in the callout below). [Learn more](https://docs.topol.io/email-editor/guide/custom-fonts.html#font-sizes)

#### `googleApiKey` — type: `string`

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](https://docs.topol.io/email-editor/guide/custom-fonts.html#google-fonts-integration)

#### `helpdesk` — type: `IHelpdesk`

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

#### `hideControlPanel` — type: `boolean`, default: `false`

Starts the editor with the control panel collapsed. [Learn more](https://docs.topol.io/email-editor/guide/control-panel-settings.html#control-panel-visibility)

#### `showControlPanelExpand` — type: `boolean`, default: `false`

Renders the editor's built-in toggle for showing and hiding the control panel; used in combination with `hideControlPanel`. [Learn more](https://docs.topol.io/email-editor/guide/control-panel-settings.html#_2-built-in-editor-ui-toggle)

#### `hideSettingsTab` — type: `boolean`, default: `false`

Removes the template settings tab from the control panel. [Learn more](https://docs.topol.io/email-editor/guide/control-panel-settings.html#related-options)

#### `htmlMinified` — type: `boolean`, default: `false`

Outputs minified HTML on export.

#### `imageCompressionOptions` — type: `object`

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](https://docs.topol.io/email-editor/guide/image-resizing-and-compression.html)

#### `imageEditor` — type: `boolean`

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

#### `imageEditorOptions` — type: `object`

Names of Image Editor control-panel sections to hide. [Learn more](https://docs.topol.io/email-editor/guide/image-editor-options.html#configuration)

#### `imageMaxSize` — type: `number`, 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](https://docs.topol.io/email-editor/guide/max-image-size.html)

#### `language` — type: `string`, default: `"en"`

Two-letter ISO 639-1 code selecting the editor interface language; regional variants such as `pt-BR` are rejected. [Learn more](https://docs.topol.io/email-editor/guide/i18n.html#define-the-language)

#### `languageMergeTag` — type: `string`, default: `"TOPOL_TEMPLATE_LANG"`

Name of the merge tag used for language-based section variants. [Learn more](https://docs.topol.io/email-editor/guide/conditional-content.html#custom-language-merge-tag)

#### `light` — type: `boolean`, default: `false`

Switches the editor interface to the light preset instead of the default dark one. Keep it consistent with `theme.preset`. [Learn more](https://docs.topol.io/email-editor/guide/themes.html#built-in-themes)

#### `logicalOperatorsInsideVariant` — type: `boolean`

Allows chaining several conditions on one variant with AND or OR. Defaults on for SparkPost and off for Mailchimp. [Learn more](https://docs.topol.io/email-editor/guide/conditional-content.html#chaining-conditions)

#### `mainMenuAlign` — type: `"left" | "right"`, default: `"left"`

Places the control panel on the left or right side of the template. Does not switch the interface to RTL, which follows the `language` option. [Learn more](https://docs.topol.io/email-editor/guide/control-panel-settings.html#control-panel-position)

#### `mergeTags` — type: `array`

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](https://docs.topol.io/email-editor/guide/merge-tags.html#defining-merge-tags)

#### `mobileFirstEnabled` — type: `boolean`, default: `false`

Turns on the mobile/desktop canvas switch and per-device visibility controls. An editing aid only - generated HTML is unchanged. [Learn more](https://docs.topol.io/email-editor/guide/mobile-first.html)

#### `multilingual` — type: `boolean`, default: `false`

Enables multilingual template mutations and the language switcher; also switched on automatically when `defaultTemplateSettings.langs` is set. [Learn more](https://docs.topol.io/email-editor/guide/multilingual-templates.html#how-to-enable)

#### `premadeBlocks` — type: `array | object | false`

Collections of prepared sections users can insert in one click. When omitted, Topol's bundled examples load; `false` hides the tab entirely. The advanced object form takes `blocks` plus a required `override` flag. Inside `blocks`, a preset marker such as `{ preset: "footer" }` places one of Topol's default groups at that position. [Learn more](https://docs.topol.io/email-editor/guide/premade-blocks.html)

#### `premadeTemplates` — type: `boolean`, default: `false`

Shows the premade template picker when the editor opens on an empty template. [Learn more](https://docs.topol.io/email-editor/guide/premade-templates-in-editor.html#enabling-premade-templates)

#### `premadeTemplatesOptions` — type: `object`

Controls two elements of the premade template picker: the search input (`hideSearch`) and the per-template Delete button (`showDelete`). [Learn more](https://docs.topol.io/email-editor/guide/premade-templates-in-editor.html#picker-options)

#### `productMergetagTags` — type: `array`

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](https://docs.topol.io/email-editor/guide/products.html#dynamic-mode)

#### `role` — type: `"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](https://docs.topol.io/email-editor/guide/roles-and-permissions.html#how-to-set-a-role)

#### `permissions` — type: `object`

Individual permission flags applied on top of the selected role; ignored unless `role` is also set. [Learn more](https://docs.topol.io/email-editor/guide/roles-and-permissions.html#overriding-individual-permissions)

#### `savedBlocks` — type: `ISavedBlock[] | 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](https://docs.topol.io/email-editor/guide/saved-blocks.html#enabling-saved-blocks)

#### `syncedSectionsEnabled` — type: `boolean`, 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](https://docs.topol.io/email-editor/guide/saved-blocks.html#enabling-synced-sections)

#### `showUnsavedDialogBeforeExit` — type: `boolean`, default: `true`

Controls the browser confirmation shown when leaving the editor with unsaved changes. Only the literal value `false` disables it. [Learn more](https://docs.topol.io/email-editor/guide/disable-before-leaving-modal.html#disabling-the-default-dialog)

#### `smartMergeTags` — type: `object`

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](https://docs.topol.io/email-editor/guide/merge-tags.html#smart-merge-tags)

#### `teamUsers` — type: `IOptionsUser[]`

List of colleagues who can be @mentioned in comment threads; the current user is filtered out automatically. [Learn more](https://docs.topol.io/email-editor/guide/comments.html#identifying-users-and-the-template)

#### `templateId` — type: `number | string`

Identifier of the open template, sent with comment and autosave API requests. [Learn more](https://docs.topol.io/email-editor/guide/comments.html#identifying-users-and-the-template)

#### `testingEmails` — type: `boolean | 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](https://docs.topol.io/email-editor/guide/sending-a-test-email.html#sending-to-multiple-addresses)

#### `textEditor` — type: `"tinymce" | "tiptap"`, default: `"tinymce"`

Selects which rich-text engine powers text blocks. [Learn more](https://docs.topol.io/email-editor/guide/text-editor-configuration.html)

#### `theme` — type: `ITheme`, 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](https://docs.topol.io/email-editor/guide/themes.html#custom-theme)

#### `tinyConfig` — type: `unknown`

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](https://docs.topol.io/email-editor/guide/text-editor-configuration.html#tinymce-configuration)

#### `tiptapConfig` — type: `object`, 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](https://docs.topol.io/email-editor/guide/text-editor-configuration.html#tiptap-configuration-options)

#### `title` — type: `string`, default: `"E-mail editor 3.0"`

Template name displayed in the editor header. [Learn more](https://docs.topol.io/email-editor/guide/rename-template.html)

#### `topBarOptions` — type: `string[]`

List of which Top Bar buttons are shown; empty or unset shows everything, unknown values are ignored silently. [Learn more](https://docs.topol.io/email-editor/guide/top-bar.html#hide-or-show-specific-top-bar-elements)

#### `renameTemplate` — type: `boolean`, 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](https://docs.topol.io/email-editor/guide/rename-template.html)

#### `removeTopBar` — type: `boolean`, default: `false`

Removes the editor's default Top Bar entirely; saving and closing then become the host application's responsibility. [Learn more](https://docs.topol.io/email-editor/guide/top-bar.html#remove-the-top-bar)

#### `windowBar` — type: `string[]`

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](https://docs.topol.io/email-editor/guide/top-bar.html#additional-window-bar)

> **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` — type: `(json, html, mutations, syncedSections)`

Fires when Save is clicked or `TopolPlugin.save()` is called, handing over the template to store. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onsave-json-html-mutations-syncedsections)

#### `onSaveAndClose` — type: `(json, html, mutations, syncedSections)`

Fires when the Save and Close button in the Top Bar is clicked. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onsaveandclose-json-html-mutations-syncedsections)

#### `onTestSend` — type: `(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](https://docs.topol.io/email-editor/guide/callbacks.html#ontestsend-email-json-html)

#### `onOpenFileManager` — type: `()`

Fires when a user clicks "Choose a file" in image, video or GIF properties; answer it with `TopolPlugin.chooseFile()`. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onopenfilemanager)

#### `onImageDelete` — type: `(items)`

Fires after one or more files or folders are successfully deleted from the built-in File Manager. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onimagedelete-items)

#### `onLoaded` — type: `()`

Fires after `TopolPlugin.load()` finishes rendering the template. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onloaded)

#### `onBlockSave` — type: `(block)`

Fires when a user saves a section to the saved blocks library in local-array mode; never fires for synced sections. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onblocksave-block)

#### `onBlockRemove` — type: `(blockId)`

Fires when a user removes a saved block in local-array mode; stops firing once `api.SAVED_SECTIONS` is configured. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onblockremove-blockid)

#### `onBlockEdit` — type: `(blockId)`

Fires when a user edits an existing saved block in local-array mode; stops firing once `api.SAVED_SECTIONS` is configured. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onblockedit-blockid)

#### `onInit` — type: `()`

Fires when the editor is fully initialized. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#oninit)

#### `onUndoChange` — type: `(count)`

Fires when Undo is used, reporting how many steps have been undone. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onundochange-count)

#### `onRedoChange` — type: `(count)`

Fires when Redo is used, reporting how many steps have been redone. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onredochange-count)

#### `onPreview` — type: `(html)`

Fires when the user enters Preview mode, with the rendered HTML. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onpreview-html)

#### `onPreviewClose` — type: `()`

Fires when the user leaves the preview screen using the editor's preview toggle (not when the host exits preview programmatically). [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onpreviewclose)

#### `onAlert` — type: `(notification)`

Receives each editor notification in place of the built-in toast; fires only while `disableAlerts` is `true`. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onalert-notification)

#### `onClose` — type: `()`

Fires when a user closes the editor from the Top Bar close control. Closing does not save first. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onclose)

#### `onEdittedWithoutSaveChanged` — type: `(hasUnsavedChanges)`

Reports whether the template currently holds unsaved changes, on every transition in both directions. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onedittedwithoutsavechanged-hasunsavedchanges)

#### `onOpenCustomBlockDialog` — type: `(customBlock)`

Fires when a user clicks the dialog button on a custom block defined with `dialog: true`; answer it with `TopolPlugin.updateCustomBlockContent()`. [Learn more](https://docs.topol.io/email-editor/guide/custom-block.html#using-custom-html-with-a-custom-dialog)

#### `onTemplateRename` — type: `(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](https://docs.topol.io/email-editor/guide/callbacks.html#ontemplaterename-title)

#### `onTemplateUpdated` — type: `()`

Fires after a programmatic `TopolPlugin.updateTemplate()` call has successfully applied the new template JSON. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#ontemplateupdated)

#### `updateTestingEmailAddresses` — type: `(emails)`

Fires when a user edits the list of test email addresses in the preview screen; relevant when `testingEmails` is an array. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#updatetestingemailaddresses-emails)

#### `onError` — type: `(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](https://docs.topol.io/email-editor/guide/callbacks.html#onerror-type-message-responsebody)

#### `onLanguageCreated` — type: `(lang, mutations)`

Fires when a new language mutation is created from the UI or via `TopolPlugin.createLanguage()`. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onlanguagecreated-lang-mutations)

#### `onLanguageDeleted` — type: `(lang, mutations)`

Fires when a language mutation is deleted, after the confirmation modal. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onlanguagedeleted-lang-mutations)

#### `onLanguageSelected` — type: `(lang)`

Fires when the active editing language changes - including as a side effect of creating, deleting, or changing the primary mutation. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onlanguageselected-lang)

#### `onPrimaryLanguageChanged` — type: `(lang, mutations)`

Fires when the primary language mutation changes; creates the language first (also firing `onLanguageCreated`) if it does not exist. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#onprimarylanguagechanged-lang-mutations)

#### `onGetMutations` — type: `(mutations)`

Fires in response to `TopolPlugin.getMutations()`, returning the current list of language mutations. [Learn more](https://docs.topol.io/email-editor/guide/callbacks.html#ongetmutations-mutations)

## 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?: IOptionsPremadeBlock;
  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;
}
```

`premadeBlocks` accepts one of four shapes. In the advanced object form, each entry in `blocks` is either a custom collection or a preset marker standing in for one of Topol's default groups. The [Premade blocks guide](https://docs.topol.io/email-editor/guide/premade-blocks.html#placing-the-default-groups) covers how markers are resolved.

```ts
interface IPremadeBlock {
  name?: string;
  img?: string;
  definition: object | object[]; // one or more mj-section definitions
}

interface IPremadeGroup {
  id?: number;
  name: string;
  blocks: IPremadeBlock[];
}

interface IPremadePreset {
  preset: "header" | "content" | "ecommerce" | "footer";
}

type IOptionsPremadeBlock =
  | IPremadeGroup[] // basic structure
  | { blocks: Array<IPremadeGroup | IPremadePreset>; override: boolean } // advanced structure
  | { headers?: IPremadeBlock[]; content?: IPremadeBlock[]; ecomm?: IPremadeBlock[]; footers?: IPremadeBlock[] } // legacy keyed shape
  | false; // disables premade blocks entirely
```

See the [Callbacks guide](https://docs.topol.io/email-editor/guide/callbacks.html#onimagedelete-items) for a description of each field.