Configuring the editor

We have a shiny, new BEE Plugin technical docs site.
You can find a new version of this page here.


Once you have initialized BEE Plugin, you can pass a series of configuration parameters to it.

Here is a brief description of the parameters:

Parameter What it does Required?

An alphanumeric string that identifies the user and allows the plugin to load resources for that user (e.g. images). Learn more about the UID parameter.

  • Min length: 3 characters
  • Can contain letters from a to z (uppercase or lowercase), numbers and the special characters "_" and "-"
container Identifies the id of div element that contains BEE Plugin Yes
autosave Integer that defines every how many seconds the message should be auto-saved. Minimum value: 15. No, defaults to "false"
language 4-letter language identifier (e.g. "en-US"). No, defaults to "en-US"
specialLinks An array of custom links that may be used in the message (e.g. unsubscribe). See example. No
mergeTags An array of merge tags that may be used in the message (e.g. first name of the recipient). See example. No
mergeContents An array of content elements that may be used in the message (e.g. small blocks of HTML). See example. No
preventClose Whether an alert should be shown when the user attempts to leave the page before saving. No, defaults to "false"
roleHash Identifies the user role (see roles & permissions).
  • Min length is 8
  • Max length is 30
  • Can contain letters and numbers
  • No white spaces
  • No special characters such as "_" and "-"
rowDisplayConditions An array of display conditions that the user will be able to select from to apply conditional statements to a row a content. See Display conditions.  No


In addition, you can specify functions to handle saving a message, saving the message as a template, sending a test, and handling errors.

The default configuration for BEE Plugin will therefore be something like the following:

beeConfig: {
uid: 'CmsUserName', // [mandatory] identifies the set of resources to load
container: 'bee-plugin-container', // [mandatory] the id of div element that contains BEE Plugin
autosave: 30, // [optional, default:false] in seconds, allowed min-value: 15
language: 'en-US', // [optional, default:'en-US'] if language is not supported the default language is loaded (value must follow ISO 639-1  format)
specialLinks: specialLinks, // [optional, default:[]] Array that defines special links
mergeTags: mergeTags, // [optional, default:[]] Array the defines merge Tags
rowDisplayConditions: rowDisplayConditions, // [optional, default:[]] Array that defines conditional statements mergeContents: mergeContents, // [optional, default:[]] Array of Object to specify merge content preventClose: false, // [optional, default:false] if true an alert is shown before browser closure onSave: function(jsonFile, htmlFile) { /* Implements function for save */ }, // [optional] onSaveAsTemplate: function(jsonFile) { /* Implements function for save as template (only JSON file) */ }, // [optional] onAutoSave: function(jsonFile) { /* Implements function for auto save */ }, // [optional] onSend: function(htmlFile) { /* Implements function to send message */ }, // [optional]
onLoad: function(jsonFile) { /* Implements function to perform an action once the template is loaded */}, // [optional] onError: function(errorMessage) { /* Implements function to handle error messages */ } // [optional] }


Events as callbacks

The top toolbar displayed by default within the BEE editor contains buttons that trigger certain actions. These are the callsbacks that are triggered when the buttons are clicked.

onSave: caught when the Save button is clicked. Returns JSON and HTML documents.

onSaveAsTemplate: caught when Save as template is clicked. Returns JSON document.

onAutoSave: called by BEE automatically based on beeConfig.autosave value. Returns JSON document.

onSend: caught when the Send a test button is clicked. Returns HTML document.

onError: caught every time an error occurs. Returns error message.


Controlling the editor from your UI

If you use a paid plan, you can hide the top toolbar and control the editor from your application's user interface. For example, it's up to you at that point to have buttons above or below the editor.

Here is what you can do with buttons located in your UI:

Display a preview. Use the beePluginInstance.preview() method to trigger the message preview behavior within the editor.

Show/hide the message structure. Use the beePluginInstance.toggleStructure() method to control the visibility of the structure outlines in the message editing portion of the editor.

Save the message. Use the method to trigger the "Save" action and invoke the onSave callback. The plugin will return two files:

  • A JSON file - the structure of the message. Store it to allow for later editing of the message.
  • An HTML file - the ready-to-send version of the message.

Save the JSON template. Use the beePluginInstance.saveAsTemplate() method to save the JSON of the message via the onSaveAsTempate callback. Since the JSON is not parsed to obtain the HTML, this is much quicker than the save() method.

Send. This is typically used to send a test message. Use the beePluginInstance.send() method to trigger the "Send test" action and invoke the onSend callback. It returns only the HTML version of the message, so you can display a "Send a test" user interface and send it.


Next: learn how you can extend the editor, loading custom merge tags, for example (e.g. to start a message with "Dear John," instead of "Dear customer").

Have more questions? Submit a request


  • Avatar

    Hi Guille,

    How do we notify bee builder that content is saved and stop showing alert that 'Changes you made may not be saved'.

  • Avatar
    Guillermo Padilla

    Hi anurag, you must unload the editor removing to from the DOM.

  • Avatar
    António Barroso

    Is there a way to get the html from json? i need the json and the html when saving as template

  • Avatar
    Guillermo Padilla

    Hi Antonio, the save as template method does not return the HTML, but you can use the other methods to receive both files.
    Check these articles for further info:

  • Avatar
    Kevin Lynch

    I am looking to purchase BEE Pro and also embed the editor in our app, but need to know if it's possible to customize the action of the Save button. We need to send the html and json to our app directly, rather than being downloaded to the local client. Is it possible to point the Save action to code on our servers?

  • Avatar
    Massimo Arrigoni

    Hi Kevin, no, that's not possible if you use BEE Pro. However, you can use BEE Plugin and embed the editor directly in your application. Learn more:

  • Avatar
    Jefferson Costa

    How to reload beeConfig in Bee Plugin without refresh?

  • Avatar
    Massimo Arrigoni

    Hi Jefferson, could you provide more information on the use case?

  • Avatar
    Jefferson Costa

    Estou utilizando o Bee Plugin em meu projeto. Preciso inserir mergeTags no momento em que eu estou editando um layout, mas pelo que entendi, o Bee Plugin não faz isso, apenas o Bee Pro, correto?

    Tenho um form que insere mergeTags via ajax, na minha base de dados. Portanto, gostaria de atualizar as configs do Bee sem ter que recarregar o layout e consequentemente o plugin, porque assim eu não perderia minhas edições no layout.

    Apenas preciso recarregar as mergeTags em meu layout sem dar refresh na tela. Pode ser que o Bee tenha algum componente que permita fazer isto, mas pesquisei e não encontrei. Apenas no Bee Pro.

  • Avatar
    Guillermo Padilla

    Hi Jefferson,
    Merge tags and other custom elements can be configured in BEE Plugin, just follow this article:

    BEE Pro uses the plugin itself, so all the editing capabilities are available for the plugin customers.

    Merge tags are passed to the editor when it starts and may change each time the editor is launched.

    If you're interested instead in adding new merge tags while the editor is running, this is an option that we plan to introduce soon with a 2 directions communication improvement that will allow an application to open selection dialogs for merge tags, links and more.