Welcome to Topol Plugin

Topol Plugin is an embeddable, white-label email editor that drops into your application with a script tag and a configuration object. It gives your users a drag-and-drop email builder inside your product and returns the resulting template as JSON and HTML, ready to store wherever your application keeps it.

Topol never stores your templates. The editor loads a template you provide and returns the edited result through callbacks. Where that data lives, who may access it, and how it is versioned stays entirely on your side.

How it works

The plugin ships as a loader script that renders the editor inside an iframe. The iframe keeps the editor's CSS and JavaScript fully separate from your application, so neither can interfere with the other, and communication between the two runs over postMessage.

Setup is a container element, the loader script, and a TOPOL_OPTIONS object:

<div id="app" style="position: absolute; width: 100%; height: 100%"></div>

<script src="https://v3.email-assets.topol.io/loader/build.js"></script>
<script>
  const TOPOL_OPTIONS = {
    id: "#app",
    authorize: {
      apiKey: "YOUR_API_KEY",
      userId: "UserID",
    },
    callbacks: {
      onSave(json, html) {
        // Persist the template in your own system
      },
    },
  };

  TopolPlugin.init(TOPOL_OPTIONS);
</script>

The full walkthrough lives in Getting Started.

Authentication uses an API key restricted to the domains you register. The key is created in your Topol account and works only on the domains listed alongside it, so a copied key is useless elsewhere. A separate Secret Key exists for server-side calls to our API, sent as the X-Secret-Key header. See how to get a Secret Key.

Embedding the editor needs no backend work. Features that persist data do: autosaves, comments, product feeds, and self-hosted storage each read and write through endpoints you implement. How to work with your API lists them and covers the CORS configuration they need.

Framework integrations

The plugin runs in any frontend stack. Alongside the plain loader, we publish TypeScript-ready wrapper packages:

• JS/TS
• React
• Vue
• Svelte
• Angular

See JS frameworks for the details of each.

Controlling the editor

Two mechanisms connect the editor to your application, described in the docs as props down and callbacks up.

Options and methods send information in. Everything the editor does is configured through TOPOL_OPTIONS, and the TopolPlugin instance on window exposes methods for driving it at runtime: load and save for template data, updateOptions for reconfiguration, plus focused calls like setMergeTags, setActiveMembers, togglePreview, and undo. See Loading and Saving Template.

Callbacks send information back out. onSave and onSaveAndClose deliver the template as JSON and HTML, onInit and onLoaded report editor readiness, and onError surfaces failures. The complete list is in Callbacks.

Customization and white-labeling

The editor is meant to look like part of your product rather than a third-party embed. Through TOPOL_OPTIONS you can:

• Rebrand the interface with your own color palette, fonts, and themes, and replace the top bar with your own.
• Enable or disable content blocks and features, and add custom blocks of your own.
• Restrict what users can do through roles and permissions.
• Translate the interface using the i18n options.

Collaboration features

The editor supplies the interface for collaboration; your backend supplies the storage. Each of these features is built in and enabled through options, and each reads and writes through endpoints you implement:

• Active members display who else has the template open. Pass the current list to setActiveMembers from your own presence system. This is a presence indicator, not real-time co-editing.
• Comments add threads to sections and blocks, enabled with enableComments. The editor renders the threads and calls your conversation and comment endpoints to store them.
• Autosaves capture drafts on a timer, enabled with enableAutosaves (60 seconds by default, minimum 30). Drafts are posted to your autosave endpoints, so template history accumulates in your storage and you control how far back it goes.

INFO

Comments require the Plugin for Business plan or higher. Check the pricing page for what each plan includes.

Storage

Templates are always yours. Template JSON and HTML are never stored, logged, or indexed by us. Some operations, such as callbacks and the conversion API, pass template data through our backend for processing, where it is handled in memory and returned without being retained.

Images work differently, which is worth settling before you commit to a data policy. Assets uploaded through the File Manager are stored in Topol's storage by default, under a monthly data traffic allowance. To keep them on your own infrastructure instead, configure custom storage with AWS S3, Google Cloud Storage, Cloudflare R2, or DigitalOcean Spaces, or connect your own endpoints with self-hosted storage. Either way, uploads and retrieval then bypass our infrastructure entirely.

INFO

Custom storage requires the Plugin Expansion plan or higher; self-hosted storage requires Plugin for Business or higher.

Who uses it

The plugin suits products that need email design as a feature rather than as their core business:

• SaaS platforms that would otherwise build an editor from scratch. The userId option gives each user a separate asset bucket, which fits multi-tenant applications.
• CRM and sales tools where messages are composed without leaving the application.
• Marketing automation platforms that generate personalized content with merge tags and conditional content.
• Enterprises and agencies producing email at volume, using comments and permissions to manage review.

Next steps

Getting Started covers creating an API key and embedding the editor. Topol Plugin vs. Topol PRO explains which of our two products fits your situation.

To try it, sign up for a free trial. For questions about a specific integration, schedule a demo call.