Stripo Plugin Reference

Developer Guide

Getting Started

Hi! Welcome to the Plugin documentation. We are glad that you are interested in our service and we will be happy to help you out with all your questions.

The Stripo Plugin is written in native Javascript and designed as a component in a way to be easily configured and extended within any web application.

If you want to see how it works, the easiest way is to use our code samples from GitHub repository or follow the instructions from the video.

By using this simple client-side example, you can try out the Stripo Plugin:

  • Get Plugin_ID and SECRET_KEY values by signing up here and creating a new application under the Plugin menu.
  • Download the client-side code example.
  • Open index.html with the code editor.
  • Replace YOUR_Plugin_ID and YOUR_SECRET_KEY with your values.
  • Save the file.
  • Open it in your browser and enjoy email creation.

Please be advised that client-side examples are created just for demo purposes only and should NOT be used in production. It is insecure and your SECRET_KEY can be stolen. Keep your SECRET_KEY on your backend and do not share it with anyone. See the authentication process in detail to implement authentication correctly.

If you're ready to discover more, let’s move to the technical part that describes how to easily integrate the Stripo Plugin with your own web application.

Displaying the Plugin

The Plugin contains 2 parts: the setting panel and the preview area where your users work.

The great news is that you can independently choose where they should be displayed inside your application and what size to set:

  • you may set the width of each container according to your preferences;
  • the height of stripoPreviewContainer, by default, stretches from the place where it was inserted to the bottom of the screen. To set another value, you need to set the max-height inline style for this container;
  • the height of stripoSettingsContainer is, by default, stretched to the height of the content and limited to the bottom of the screen. To set another value, you need to set the max-height inline style for this container;

For example, max-height: calc (100vh - 100px); where 100px is the total height of the top and bottom panels. The max-height style must be specified for each panel separately, if not specified, the height will be adjusted by default, from the insertion point to the bottom of the screen.

Please be advised that the features above these two containers, that you see in the demo application or in the Stripo account, are not related to the Plugin, so to get the same controls you have to implement them inside your application independently.

To install the Plugin you need to:

  1. Define 2 containers for the Stripo settings panel (where controls will be located) and the Stripo preview area (the area where the rendered email template will be displayed).

    <div id="stripoSettingsContainer"></div>
    <div id="stripoPreviewContainer"></div>
  2. Include the script taken from the application details page of the Stripo Plugin Integration menu of your Stripo account.

    To check the available versions of Stripo Plugin, please go to Release Notes.

    If you want to host Stripo Plugin assets on your end you can download them from Stripo Github repo: https://github.com/ardas/stripo-plugin.

  3. Initialize the Plugin by using the window.Stripo.init function with its own JSON configuration described below.

Done! :) Once you have initialized the Stripo Plugin, you can pass a series of configuration parameters to it.

Initialization & Configuration

To initialize the Plugin you should create your own logic for your application. For example, you can display the templates on your interface and relate them with the initialization process so when a user clicks on one of them your application calls the initialization function and passes the HTML and CSS code of the selected template to it from your server. Or you can choose to simply add a button named “Create template” and upon a click on it, your application calls the same initialization function but passes the HTML and CSS code of the default empty template to it.

The general point is to start the initialization process and pass the list of needed parameters.

Once you have added the Stripo Plugin assets on your web page you need to initialize the Plugin:

window.Stripo.init({[put here your plugin JSON configuration]});

The default initialization script for Stripo Plugin should look like this:

window.Stripo.init({
   settingsId: '[put here ID of your settings container]',
   previewId: '[put here ID of your preview container]',
   html: '[put here HTML code of your email]',
   css: '[put here CSS code of your email]',
   apiRequestData: {
      emailId: '[put here ID of email in your external application]'
   },
   getAuthToken: function(callback) {
      //put here get Auth Token logic
   }
});

Let’s look at each parameter to understand why we need them.

settingsId
previewId
These should be the same IDs as you defined in the divs to display the Plugin.
html
css
Please place it in two rows: HTML and CSS separately and escape if needed during the initialization. Find the example here.
Please note that we have requirements for the code. It won't be displayed without tags <head> and <body>.
Please, find more details here.
apiRequestData
You have to specify here at least one mandatory emailId parameter (for these HTML and CSS) which we will serve as a Unique ID.
Additionally, you can specify all other parameters you have that will be sent from the Plugin to its server with each request. They may be used to identify a path to the Image storage documents and modules. You can use any parameter you want (like userId,accountId, tenantId, etc.), just make sure that it passed to the apiRequestData parameter during Plugin initialization.
getAuthToken
The last important part of the Plugin initialization is the getAuthToken function which is required for authentication. The Plugin calls this function (this parameter value) each time a token is expired in order to get a new one. You have to implement this method on your side as described here and it will be an automatic process.

Additionally, you can add other parameters to the initialization script. It allows you to get more opportunities for your users according to their category. For example, you can show them different social networks, modules, or merge tags.

As a result, you can independently determine all these parameters for each user (so they can be the same or different) every time during initialization.

Find the full list of them here:

Parameter
Required
Description
Default
locale
No
2-letter language identifier.
Available Languages:
English: “en”
Spanish: “es”
French: “fr”
German: “de”
Italian: “it”
Portuguese: “pt”
Slovenian: “sl”
Russian: “ru”
Ukrainian: “uk”
Dutch: “nl”
Czech: “cs”
Turkish: “tr”
“en”
previewId
Yes
ID of preview container.
settingsId
Yes
ID of settings container.
apiRequestData
Yes
These parameters will be passed to the backend with every request. Refer to “the Plugin request parameters” section for details.
getAuthToken
Yes
Please implement this function to get the auth token from the backend. See the “Plugin authentication” section for details.
html
Yes
The HTML code of the email template has to be open.
css
Yes
The CSS code has to be applied to email.
userFullName
No
A full name of the user that uses the editor. Will be displayed in the Version History section of the editor.
codeEditorButtonId
No
ID of the open/close code editor button.
undoButtonId
No
ID of the undo button.
redoButtonId
No
ID of the redo button.
unSubscribeLink
No
This value will be applied to the link if the “Unsubscribe” link type is chosen.
viewInBrowserLink
No
This value will be applied to the link if the “View In Browser” link type is chosen.
ignoreClickOutsideSelectors
No
List of selectors of elements, click on which does not start the clickOutsidePreview event and as a result does not reset the block selection in the preview area.
notifications
No
Set of methods that will be called when any message needs to be visible for the user. See the “Plugin notifications” section for details.
{ info: message => console.log(message), error: message => console.error(message), success: message => console.log(message), warn: message => console.log(message), loader: message => console.log(message), hide: message => console.log(message) }
onTemplateLoaded
No
This parameter helps to notify the external application when the plugin initialization is completed.
onTemplateLoaded: function() {console.log('Loaded')}
socialNetworks
No
List of social networks to be included in the “Social Networks” block. See the “Social Networks" section for details
mergeTags
No
List of the merge tags to be included in the Text Editor panel. See the “Merge Tags” section for details.
See the “Merge Tags” section for default values
specialLinks
No
List of the special links to be included in the Link selector component in the editor.
See the “Special Links” section for default values
editorFonts
No
List of fonts to be included in the Text Editor panel and the Settings panel for basic blocks. See the “Сustom Font Sizes list” section for details.
See the “Fonts Management” documentation for default values
editorFontSizes
No
List of font sizes to be included in the Text Editor panel and the Settings panel for basic blocks. See the “Сustom Font Sizes list” section for details.
See the “Сustom Font Sizes list” section for default values
customColorPalette
No
List of colors to display in the color palette for the Text Editor panel and the Settings panel for every basic block. See the “Custom Color Palette” section for details.
See the “Custom Color Palette” section for default values
customColorPaletteTextOnly
No
Set up your desired colors for the text available only in the side menu and the CKEditor menu. See the “Custom Color Palette” section for details.
viewOnly
No
Set to TRUE if you want to disable email modifications by a user.
false
apiBaseUrl
No
The Stripo Plugin main backend entrypoint.
/pluginapi/api/v1
bankImagesDefaultSearchString
No
Default search string for images from the “Image Bank” if it is enabled.
Depends on current season: “spring” / “summer” / “autumn” / “winter”
draft
No
The Stripo Plugin supports auto-save that makes calls to the server. In order to be notified in JavaScript when the content is changed and saved, you can rely on this parameter as described in the examples.
draft: { showAutoSaveLoader: function() {console.log('Auto save in process')}, hideAutoSaveLoader: function(error) {console.log('Auto save completed')} }
allDataSaved
No
This parameter helps to identify whether all changes are saved or not.
If something was not saved it returns False, if everything saved - True.
externalSmartElementsLibrary
No
This parameter is used to display your own component with an external data list in a pop-up window. See the “Advanced parameters” section for details
enableXSSSecurity
No
BOOL Specifies if meta tag with Security Policy will be applied to the edited document.
false
allowedScriptSourceDomains
No
Specifies a list of domains allowed as sources for script tags in the edited document. Example:
https://domain1.com
http://doman2.net
‘’
conditionsEnabled
No
Set to True if you want to enable the Conditions tab. See the “Display Conditions” section for details
False
ampFormServices
No
This parameter is used to fetch a list of services (endpoints) used for collecting data gathered by the Form block. See the “AMP-Form Services" section for details.
False
onToggleCodeEditor
false
This parameter helps to notify the external application when the plugin code editor changes its state (opened/closed).
onToggleCodeEditor: function(codeEditorVisible) {}
canBeSavedToLibrary
false
This function depending on the result enable or disable 'save as module' functionality for individual containers/structures/stripes.
canBeSavedToLibrary: function(moduleHtml) {return true}

If the editor is closed by the user in your web application, we recommend calling the following function to stop all processes and improve the performance of your application:

window.StripoApi.stop();

Please try out our example with the basic parameters to initialize the Plugin — https://github.com/ardas/stripo-Plugin-samples/tree/master/client-side-code-sample

Just create 2 text files on your device and rename them as in the example, then copy/paste all information from our files into the created ones, and don’t forget to add your own Plugin ID and Secret Key from the Stripo account in the index.html file.

Then you should double-click the Index.html file to get the initialization started.

Authentication Process

Authentication allows us to get an understanding of details concerning your account and the opportunities/limitations that you have. From the user's side, it allows them to have a real-time connection with our server and the understanding that everything works as it should.

The Stripo Plugin can't perform any operation without an authentication token. To authenticate your instance of the Stripo Plugin, call the endpoint shown in the sample code below with your Plugin Id and Secret Key, which are available on the Plugin details page. The Plugin calls the function each time a token is expired in order to get a new one.

Please pay attention that we show only the example of the Authentication process and the real call has to be implemented from your server based on the example below.

https://github.com/ardas/stripo-Plugin-samples/tree/master/server-side-auth-sample

So let's take a closer look at how Authentication works:

  1. The Plugin configuration contains a parameter named getAuthToken. To get a new token the Plugin calls the getAuthToken function defined in Customer Application UI.
  2. Customer Application UI sends the GET requests to the Customer Application Backend (for example, the "/token" request without any parameters).
  3. Based on it the Customer Application Backend loads the "Plugin Id" and "Secret Key" values from the storage/database/file system.
  4. After that, the Customer Application Backend sends the "/auth" POST request to the Stripo Plugin Backend with PluginId, secretKey, and role parameters.
  5. As a response, the Stripo Backend generates the Plugin authentication token and
  6. sends this token back to the Customer Application backend.
  7. Finally, the Customer Application Backend sends a token back to the Customer Application UI, and there the Customer Application UI calls the callback(token) method from the getAuthToken method params to load this token to the Stripo Plugin.

Sounds confusing? Please note that once the configuration is completed all this process will take a few seconds and your users wouldn’t even notice it.

To make it more clear please find the example of the getAuthToken implementation below:

getAuthToken: function(callback) {
   $.ajax({
  type: 'GET',
  url: '/backend/plugin/token',
  contentType: 'application/json; charset=utf-8',
  dataType: 'json',
  success: data => callback(data.token),
  error: error => callback(null)
   });
}

To get a token on your Backend, please call an endpoint from it, as shown in the sample code below, with your PluginId and Secret Key, which are available on the Plugin details page.

POST: /api/v1/auth
Host: https://plugins.stripo.email
Content-Type: application/json
Accept: application/json
Body: {pluginId:YOUR_PLUGIN_ID,secretKey:YOUR_SECRET_KEY,role:PLUGIN_EDITOR_USER_ROLE}
Response: {token:YOUR_AUTH_TOKEN}

AUTH REQUEST PARAMS:

Parameter
Required
Description
YOUR_PLUGIN_ID
Yes
The value from your plugin configuration page.
YOUR_SECRET_KEY
Yes
The value from your plugin configuration page.
PLUGIN_EDITOR_ROLE
No
String value of a user role in the editor. For example, “ADMIN” or “USER”.

Template requirements

The email templates that may be created/edited with Stripo editor, consist of two separate parts: the HTML code and the CSS code.

These parts of one template should be stored in your own database separately and passed simultaneously (see the initialization parameters) when the user decides to edit the template.

To check and compare the Stripo layout of the templates you can use our basic code from the repository.

In order to activate the editor's drag-n-drop feature for an imported email template, it is required the template has particular Stripo classes, which are used by the editor to parse the HTML layout correctly. In case you have a list of email templates created with another builder and you want to edit them with the Stripo editor, please make sure you have converted the HTML code of those templates correctly (with specific classes included in their HTML code) to activate Stripo editing features. Please, refer to this article from our blog with the list of all specific classes and examples of how to convert the HTML code — https://stripo.email/blog/advanced-option-email-templates-adaptation-stripo-builder/

To show the Stripo free email templates and display them in your application for your users for inspirational purposes, you can download them from here.

Please note that you will find only a few templates there, to get all the pre-built templates from our library, please contact our support at support@stripo.email.

To provide your users with an option to create new email templates from scratch, please use the pre-built HTML and CSS code of an empty (scratch) email template which you can find here

It is required that the email template’s HTML code has at least one stripe with one structure in it.

How to Upgrade the Plugin?

We are glad that you decided to go further and upgrade your Plugin subscription plan! To do so, please open the Plugin tab in your Stripo account.

and choose Settings of a necessary application (if you have only one app, please choose it).

In the settings menu, you will get the opportunity to upgrade the subscription on a monthly basis.

If you want to get the invoice with the annual subscription, please email us at support@stripo.email.

UI Configuration

Interface Appearance in paid subscriptions only

In this section, you can configure the appearance of the Stripo Plugin to make it in the same style as your application.

How can you do that?

Just choose needed controls here and remove our Stripo branding.

If you need more options for managing styles (appearance), then the Enterprise plan is what you need. There you can host the entire front-end on your side and add your own CSS-file that will prevail over our standard styles.

Sometimes connecting the editor to applications that are also using Bootstrap CSS styles can cause a distorted look of the Plugin styles: components, alignment, etc.

This happens because the styles of your application affect the editor's styles. In this case, you need to isolate the influence of your application styles on our editor by connecting it to iframe or you should independently detect (using dev tools) which styles of your application affect the editor and change their scope (so that they do not work globally, but only for specific components).
If you have any questions on how to solve this problem, please feel free to contact our support team at support@stripo.email.

Image Storage

With the Stripo Plugin, you independently choose where all your images should be stored and it’s free for all pricing plans.

We are glad to provide our storage for your integration ー it’s actually specified as the default one in the settings.

Please be advised that there might be a limitation to the use of the Stripo storage depending on the selected Plugin subscription plan. In order to have full control over the images used by your users in newsletters, we do recommend keeping them on your own file storage servers.

Don’t want to store pictures on our end? No problem! Please choose any other preferable option and connect your own server to the image gallery.

Please, see the example of a configuration for Custom AWS S3 bucket, Azure Blob storage, or even your own server with the Other storage tab below.

Custom AWS S3 bucket

Custom AWS S3 bucket is a Plugin application configuration feature that allows you to easily connect your own Amazon Web Services S3 bucket to our Plugin for storing images.

If you choose this option, you’ll have to fill out a form to establish a connection with your storage. Please take a look at the image above to see the description of the form fields with specifications regarding the information required for each of them.

Parameter
Required
Description
S3 bucket name
Yes
The name you assigned to the bucket when creating it.
Access key
Yes
You can provide AWS Root Account Credentials or IAM User Credentials (we recommend the second option for security reasons). The provided account must have the “Read” and “Write” access to the given bucket. More about AWS credentials.
Secret access key
Yes
You can provide AWS Root Account Credentials or IAM User Credentials (we recommend the second option for security reasons). The provided account must have the “Read” and “Write” access to the given bucket. More about AWS credentials.
Region
Yes
AWS region where you created the bucket.
Base download url
Yes
Define the path that will be specified at the beginning of each URL to the images hosted in your S3 bucket. For example, it may be your CDN domain name or any other address, depending on your server configuration.

Please make sure that the provided account has the Read and Write access to the given bucket.

For more details on how to configure your AWS S3 storage please refer to this manual.

Azure Blob storage

Azure Blob storage is a Plugin application configuration feature that allows you to easily connect your own Azure storage account to our Plugin for storing images.

To do so, you need to generate a connection string in your Azure portal account:

If you choose the “Azure Blob Storage” option, you will have to fill out the form to establish a connection with your storage. Please take a look at the image above to see the description of the form field with specification regarding the information that you will need to enter there:

Parameter
Required
Description
Azure connection string
Yes
Connection string from your azure portal account.

Other storage

This option may be the best choice for you if you’re using another storage type or want to build a more custom and flexible solution to host your images. We created a way to connect the Plugin to a custom file system provider (via HTTP protocol), allowing you to use the Stripo editor with your own file storage, no matter which technology you use.
It is required to support the set of the methods described below to provide successful communication between the two systems: the Stripo server and yours.

The Basic Authentication is used to send these requests, so please make sure that you have specified the correct Login, Password, and Base API URL on the Stripo Plugin details page of your Stripo account (if you don’t have an account, please sign up).

So, once the “Other storage” option is selected, make sure your server supports all the 4 types of requests with the exact specifications described below — GET LIST OF FILES, UPLOAD FILE TO STORAGE, DELETE/REMOVE FILE FROM STORAGE, GET FILE INFO.

GET LIST OF FILES

This method is used when the image gallery is opened inside the editor.

GET: /?keys=KEY_FOLDER_1,KEY_FOLDER_2,...
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Response: [{key: KEY_FOLDER_1, documents: [{url:DOC_URL,originalName:DOC_NAME,uploadTime:DOC_UPLOAD_TIME,size:DOC_SIZE_IN_BYTES,height:DOC_HEIGHT,width:DOC_WIDTH,thumbnailUrl:DOC_PREVIEW_URL}]}, {key: KEY_FOLDER_2, documents:[]}]
The Copy button may not work, it could be caused by special syntax inside the code. Please try to copy it manually.
Parameter
Description
key
It is generated automatically from the Plugin Id and the value specified in the Folder path field (please see the Folder configuration section) of the folder to which the image is loaded. For example, key=0000000_99999, where 0000000 is the Plugin Id and 99999 is the value set to the Folder path.
documents
An array of the uploaded documents grouped by Key.
url
Mandatory. Absolute URL to the document.
originalName
Optional. Document name.
uploadTime
Optional. Document upload time in milliseconds.
size
Optional. Document size in bytes.
height
Optional. Document height in pixels (px).
width
Optional. Document width in pixels (px).
thumbnailUrl
Optional. The absolute url of document preview thumbnail.

UPLOAD FILE TO STORAGE

This method is used when the user uploads an image to the image gallery.

POST: /
Host: YOUR_BASE_URL
Content-Type: multipart/form-data
Accept: application/json
Body: 
    key:KEY_FOLDER,
    file: MULTIPART_FILE
Response: {url:DOC_URL,originalName:DOC_NAME,uploadTime:DOC_UPLOAD_TIME,size:DOC_SIZE_IN_BYTES,
height:DOC_HEIGHT,width:DOC_WIDTH,thumbnailUrl:DOC_PREVIEW_URL}
The Copy button may not work, it could be caused by special syntax inside the code. Please try to copy it manually.
Parameter
Description
key
It is generated automatically from the Plugin Id and the value specified in the Folder path field (please see the Folder configuration section) of the folder to which the image is loaded. For example, key=0000000_99999, where 0000000 is the Plugin Id and 99999 is the value set to the Folder path.
file
Multipart file.

DELETE/REMOVE FILE FROM STORAGE

This method is used to remove the system images only from the storage: like thumbnails of the modules, etc.

POST: /delete
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Body: {url:DOC_URL}
The Copy button may not work, it could be caused by special syntax inside the code. Please try to copy it manually.
Parameter
Description
url
Absolute URL to the document.
key
It is generated automatically from the Plugin Id and the value specified in the Folder path field (please see the Folder configuration section) of the folder to which the image is loaded. For example, key=0000000_99999, where 0000000 is the Plugin Id and 99999 is the value set to the Folder path.

Please be advised that the Plugin never removes the user’s images uploaded to the image gallery. If a user removes an image, the Plugin simply marks it as a removed one and doesn’t display it in the image gallery anymore. This approach prevents cases when the user accidentally removes the image that is already sent in the email to the recipients. Because if the image is actually removed from the storage, the opened email template may be broken.

GET FILE INFO

This method is used for reading the specific information displayed on the Settings Panel about the selected image

GET: /info?src=DOC_URL
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Response:{"originalName":DOC_ORIGINAL_NAME,"size":DOC_SIZE_IN_BYTES}
The Copy button may not work, it could be caused by special syntax inside the code. Please try to copy it manually.
Parameter
Description
src
Absolute url of the document.

Please be advised that the key of the system images (used for a banner block, a video block, and module thumbnails) have the types of the Keys that are different from the described above.

Thus, the key for the system images are as follows:

  • for the video block — pluginId_[application_id]_video
  • for the banner block — pluginId_[application_id]_banner
  • for the module thumbnail — pluginId_[application_id]_modules

where [application_id] is the Plugin Id of you application.

You can see the image gallery at that time when you or your users choose an image for the “Image” block. You independently decide how many folders it contains and whether the user can only use it as drag-n-drop or also upload images to it for future usage.

For example, below you may see 3 folders in the image gallery named “Email”, “Project”, and “Common”.

These folders were created and configured on the Plugin details page this way:

In this section, you can manage:

  • the number of folders;
  • their names. You have the option to specify what names a created folder should have in every supported language;
  • the path to images that should be stored in each folder;
  • and also you can grant respective permissions.

You can specify the dynamic folder path to the repository and insert into it the variables that may be taken from your end when the Stripo editor is initialized.

For example, if you want to separate the images of one email template from another, you can create the "Emails" folder and specify its path as ${templateId}. When initializing the Plugin, you have to pass the templateId value (e.g., 00000) among the parameters in the apiRequestData and, as a result, the Plugin will get the images from the “00000” folder (this folder will be automatically created on a configured server if it does not exist yet).

Please be advised that by default the Stripo plugin also creates the technical folders to store generated banners and image previews for the “Video” basic block, etc. This folder cannot be managed from the Stripo Plugin details page.

If you have any questions on this matter, please contact our support team at support@stripo.email.

Limits

Below, you can specify the maximum size of one image uploaded to the gallery. The maximum value cannot exceed 20 Mb per one document.

Stock image configuration

If you want to provide your users with an option to search for and use free stock images within the image gallery while creating an email, you need to simply activate the "Stock images configuration" option.

Once it is activated, please specify the stock folder name, choose an available stock images provider, and specify the configuration according to the provided instructions.

The list of providers may be extended in the future.

If you want to display your own UI component with an existing hierarchy of images and folders we have a great solution for you. The file with the example of the code describes how it may work.

When users want to use an image, instead of our gallery they will see an external gallery in the modal window. In that window, it’s up to you to define which images should be displayed and how, depending on a user that is currently working with the email in the editor.

To do so, you should initialize the Plugin with the parameter externalImagesLibrary and put your logic there. We expect that with the image that your user chose you will pass to the Plugin in callback parameters like original name, resolution, size and URL.

Please find the example of the code below:
window.Stripo.init({
   ...,
   externalImagesLibrary: {
        openLibrary(onImageSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onImageSelectCallback({
                     originalName: 'YOUR_FILE_NAME.png',
                     resolution: '600 x 410 px',
                     size: '169.20 kb',
                     url: 'https://YOUR_STORAGE_URL/YOUR_FILE.png'
                  })
               when user select the image from external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }
    }
});

You can also find the real example here and try it out on your side.

Modules Library

If you want to offer your users some interesting structures with a non-standard layout or provide the opportunity to save particular elements separately from the whole email (structures, containers, stripes) for future use and the easy drag-and-drop functionality you can fulfill it with modules.

Similar to the image gallery, a user may see as many folders (tabs) in the Modules tab as you've created and configured for your Plugin application.

In this section, you can manage:

  • the number of folders;
  • their names. You have the option to specify what names a created folder should have in every supported language;
  • the storage key ID that will be assigned to modules and will be used as an identifier.
  • and can even grant respective permissions.

You can specify the Storage Key ID as a static value or a variable (use braces, e.g. ${UserId}).

For example, if you want to restrict the access to one user’s modules from another user, you can create the ‘My modules’ folder and specify its path as ${UserId}. When initializing the Plugin, you have to pass the userId value (e.g., 00000) to apiRequestData parameter and, as a result, the Plugin will get the modules from the DB by the key “00000”.

Please be advised that you can turn off this feature so the Library section won’t display in the editor at all.

In this case, there won’t be an option to save selected elements from the context menu.

Important to note: At this stage, custom modules can be saved only to the first folder, so please set User permissions for this folder only. We do not yet have the option for you to choose which folder you would like to save modules to. This is something that is on our road map so this will be definitely implemented a bit later due to other urgent things we are working on now.

Workaround on how to save modules to different folders.

This works in case you want to display your pre-built modules within the second tab (or third, etc.) but the first one is for the User’s usage only.

Let’s say you have 2 tabs: the first one is for users’ custom modules (let’s name it “My modules” and the second one is for pre-built modules (let’s name it “Pre-built”).

On the Plugin details page, for the first tab place the module_${userId} value into the field ”Storage key ID”. For the second tab ー ”module_000000” value respectively. Also, please set the Admin role to the “Write permission” field for the second tab and the User role for the first one.

Now, every time you initialize the Plugin please pass to the apiRequestData parameter the user’s unique identifier (in our case, userId) and its value. For example, if you passed the user’s identifier as userId=123456, the final Storage key ID for the modules would look like “module_123456”. In this case, the Plugin will make a query to its server to get all the modules with this Storage key ID. The same is applicable to saving new modules to the library (they will be saved with “module_123456” Storage key ID).

But how to save modules to the second tab? During the Plugin initialization, please pass the “userId=000000” value to the apiRequestData parameter as a user’s unique identifier. In this case, the final Storage key ID for the modules would look like “module_000000”. So all the saved modules will have this key and this is exactly what we set to the second tab (Pre-built) to field ”Storage key ID” ー”module_000000”.

If you have any questions, please contact our support team at support@stripo.email.

Merge Tags

You can personalize all emails based on your own variables connected to your platform. Merge tags (variables for personalization) help dynamically insert text templates into a text, like very common scripts (e.g., “Dear {first_name}” ). When you send the created email from your platform the variable from the tag will be changed automatically in accordance with the information from your database for a particular recipient.

Merge tags can be inserted from a text formatting panel of the ”Text” basic block by clicking on the “Merge tags” button in the expanded toolbar.

If you have activated this option while configuring the Plugin, the Stripo Plugin will handle all the transferred merge tags correctly, otherwise, this option won’t be displayed on the text formatting panel at all.

Here is the example of creation of mergeTags that you can pass with Plugin initialization:

{
    "mergeTags": [
        {
            "category": "MailChimp",
            "entries": [
                {
                    "label": "First Name",
                    "value": "*|FNAME|*"
                }
            ]
        }
    ]
}
Parameter
Required
Description
category
Yes
Used to group similar merge tags under one label.
entries
No
Array of merge tags for category.
label
Yes
This label will be displayed as a merge tag name in the Text Editor.
value
Yes
This value will be inserted into HTML code after clicking on merge tag.

You can add more personalized links like Unsubscribe from sending or View in browser link in case if your customer wants to see email in web-browser. Special links option helps dynamically insert correct variables into an email. When you send the created email from your platform the variable from the tag will be changed automatically in accordance with the information from your database for a particular recipient.

Special link will be visible in a settings panel by clicking on the Link control.

If you have activated this option while configuring the Plugin, the Stripo Plugin will handle all the transferred special links correctly, otherwise, this option won’t be displayed in the settings panel at all.

Here is the example of creation of Special links that you can pass with Plugin initialization:

"specialLinks": [
{
    "category": "eSputnik",
    "entries": [
        {"label": "Unsubscribe", "value": "https://esputnik.com/unsubscribe"},
        {"label": "View in browser", "value": "https://esputnik.com/viewInBrowser"}
    ]
},
{
    "category": "Other",
    "entries": [
        {"label": "Some special link", "value": "https://some.special.link.url"}
    ]
}
]

Please find the descriptions of the parameters below:

Parameter
Required
Description
category
Yes
Used to group similar special links under one label.
entries
No
An array of special links for a category.
label
Yes
This label will be displayed as a special link name in the list in setting panel
value
Yes
This value will be inserted into the HTML code after clicking on the special link.

Fonts management in paid subscriptions only

With this option, you can independently choose which fonts your users should see in the editor.

Font management helps you implement a variety of scenarios on your end. For example:

  • you want your users to customize the list of fonts loaded in the editor when they edit emails. For this purpose, you can create an interface in your app, and configure the editor accordingly;
  • you are a digital marketing agency and you want to customize the list of fonts in the editor according to a client’s brand for whom the email template is being created.

The list of fonts that should display in the editor must be defined each time the Plugin is initialized.
This helps you to:

  • expand the list of available fonts displayed in the editor by adding own web fonts from popular services, like Google fonts and others;
  • reduce the list of fonts to a limited number of options by removing the default fonts.

Please find the example of the code below:

{
    "editorFonts": {
        "showDefaultStandardFonts": true,
        "showDefaultNotStandardFonts": true,
        "customFonts": [
            {
                "name": "Oswald",
                "fontFamily": "'Oswald', 'helvetica neue', helvetica, arial, sans-serif",
                "url": "https://fonts.googleapis.com/css?family=Oswald"
            },
            {
                "name": "Barriecito",
                "fontFamily": "'Barriecito', cursive",
                "url": "https://fonts.googleapis.com/css?family=Barriecito&display=swap"
            }
        ]
    }
}

Please find the descriptions of parameters below:

Parameter
Required
Description
showDefaultStandardFonts
No
This boolean parameter specifies whether to display the entire standard fonts list. The default value is true.
showDefaultNotStandardFonts
No
This boolean parameter specifies whether to display the entire non-standard fonts list. The default value is true.
customFonts
No
If this parameter contains indicated fonts they will appear on the Custom fonts list. This parameter may include an array with many elements, each of them can have the following properties:
name — this line will be shown in the drop-down fonts list. Long lines could distort the interface, thus we recommend using short ones. Do not enter the following characters: {} []: "/ \ |?;
fontFamily — describes a set of CSS fonts that will be applied to the final HTML. It is important to provide at least one fallback font so that the text is not displayed in any font of an unsupported font family on a user's device. It is important to use single quotes with font names instead of double quotes to maintain the correct JSON syntax;
url — this parameter is used only when working with web fonts. It is important to make the URL point at a CSS file with @font-face properties, and not directly at font files. Make sure CSS is hosted on the HTTPS protocol.

Please be advised that Stripo accepts only the CSS font embedding method, and the CSS file must be hosted in HTTPS protocol. You can use services like Google fonts that provide host font stacks and a well-formatted CSS file.

If you want to change the default set of fonts, you need to disable them and use custom fonts to indicate a new set, including the URL parameter for web fonts. In this case you don’t have to pass the URL parameter to the fonts from the “Standard fonts” list.

Сustom Font Sizes list

You can display the font sizes in accordance with your brand identity and needs. It can be our standard or your own non-standard list with sizes.

The list of font sizes that should be displayed in the editor may be defined each time the Plugin is initialized. This helps you to achieve one of these scenarios:

  • expanding the list of available font sizes displayed in the editor by adding own values of font sizes;
  • reducing the list of font sizes to a limited number of options by removing the default sizes (standard and non-standard ones).

Here is the example of a font size object that you can pass with Plugin initialization:

"editorFontSizes": {
    "showDefaultStandardFontsSizes": false,
    "showDefaultNotStandardFontsSizes": true,
    "customFontsSizes": [17, 27, 32, 45]
}

In this case,

  1. a default section (Non standard sizes) is loaded, and
  2. 4 custom font sizes are added to the list (to the Custom sizes section).

Please find the descriptions of the parameters below:

Parameter
Required
Description
showDefaultStandardFontsSizes
No
This boolean parameter specifies whether to display the entire standard font sizes list. The default value is true.
showDefaultNotStandardFontsSizes
No
This boolean parameter specifies whether to display the entire non-standard font sizes list. The default value is true.
customFontsSizes
No
If this parameter contains the indicated values, they will be displayed in the Custom font sizes list. This parameter may include an array with many values represented in the integer type of data.

Please note that if you want to change the default set of font sizes, you need to disable them and use custom ones to indicate a new set.

Custom Color Palette

This feature helps you to decrease or increase the number of color options that appear on the color palette in the editor. These colors can be applied to text or other elements to make them more interesting and highlight important information.

The list of custom colors that should be displayed in the editor must be defined each time the Plugin is initialized. This approach helps you to implement a variety of scenarios on your end like:

  • you want your users to customize a list of colors loaded in the editor when they edit emails;
  • you can create an interface in your app to do so, and instruct the editor accordingly.

Here is an example of a custom color palette object that you can pass with Plugin initialization:

"customColorPalette": [
    "#882724",
    "#35882C",
    "#FFD351",
    "#1924FF",
    "#B621EC",
    "#95C4EC"
]

Please find the descriptions of the parameters below:

Parameter
Required
Description
customColorPalette
No
This is an array of color values that should be given in the Hex format only. The format is a hash (#) followed by 6 figures or letters. Please find the details on the Hex Color Codes here.
customColorPaletteTextOnly
No
Set up the needed colors for the text available on the side menu and CKEditor menu. The format is a hash (#) followed by 6 figures or letters. Please find the details on the Hex Color Code here.

Please be advised that in this case instead of the standard color palette list, only the specified values will be displayed for selection. The input fields connected to colors will be disabled in order to prevent entering incorrect color values.

Display Conditions

Display conditions allow you to change the content of emails displayed to recipients, depending on whether the specified condition on your end is met or not.

Users can set conditions manually in the editor (Custom) or select them from a list of predefined conditions set earlier (Predefined).

Below you can see the Conditions tab with the custom condition category for the selected container.

Let’s have a look at the following use-case ー you’re preparing a sales newsletter for your eCommerce project. You’d like to show different banners for men and women in a single newsletter. In your user database, you are able to detect users’ gender.

So here how you can use this information to prepare customized newsletters. After the initial set up you’ll get the following result.

This is how women will see the email:

This is how men will see the email:

Now let’s go through the initial process of activating and customizing the Display Conditions for the editor users.

The very first thing to do is to activate the Display Conditions during Plugin initialization:

{
 ...
 conditionsEnabled: boolean = false; //activation of the Display Conditions tab in the Editor
 customConditionsEnabled: boolean = true; //ability to create Local Display Conditions inside the Editor
 conditionCategories: (PredefinedCategory | ExternalCategory)[] = []; //List of Condition categories
 ...
}

This activates the Conditions tab in the editor:

You may have some predefined categories that you want to apply to conditions and use them in the editor. In our example, this is Gender — Male & Female.

To pass the predefined conditions, please use the PredefinedCategory type which has the following configurations:

PredefinedCategory {
 type: string = 'PREDEFINED';
 category: string; //Category name
 conditions: PredefinedCondition[]; //conditions array with PredefinedCondition type
}

This is the configuration of predefined conditions:

PredefinedCondition {
 id: number; // unique ID of the Condition
 name: string;
 description: string;
 beforeScript: string;
 afterScript: string;
}

And this is the example of a predefined category with one condition:

{
 type: 'PREDEFINED',
 category:'Gender'
 conditions:[
  {
   id:1;
   name: 'Gender - female',
   description:'Only female customers will see this part of the email.',
   beforeScript:'{% if contact.gender === \"Female\" %}',
   afterScript:'{% endif %}';
  }
 ]
}

In the editor, we get the following:

The same could be set up for any condition, for example, Gender — male:

Instead of providing a list of predefined conditions, you can specify an External category which will allow you to implement your own condition selecting functionality. After the user selects the condition by the means you will provide to them, the latter will be sent back to the Plugin via a callback function.

Here is the type of external category:

ExternalCategory{
 type: string = 'EXTERNAL',
 category: string, //Category name
 openExternalDisplayConditionsDialog: (callback: ExternalDisplayConditionSelectedCB) => void; // callback that accepts a condition with type ExternalCondition
}

type ExternalDisplayConditionSelectedCB = (condition: ExternalCondition) => void;

ExternalCondition{
 name: string;
 description: string;
 beforeScript: string;
 afterScript: string;
}

Please see an example of an external category below:

{
 type: 'EXTERNAL',
 category:'Gaming platform'
 openExternalDisplayConditionsDialog: function(cb){
  // your code goes here
  cb({
   {
      name: 'Console',
      description:'Only console gamers will see this part of the email.',
      beforeScript:'{% if contact.gamingPlatform=== \"peasant\" %}',
      afterScript:'{% endif %}';
   }
  });
 }
}


Please see a full example of the Display Condition configuration:

{
 "conditionsEnabled": true,
 "customConditionsEnabled": true,
 "conditionCategories": [
   {
    "type": "PREDEFINED",
    "category":"Gender",
    "conditions":[
     {
      "id":1,
      "name": "Gender - female",
      "description":"Only female customers will see this part of the email.",
      "beforeScript":"{% if contact.gender === \"Female\" %}",
      "afterScript":"{% endif %}"
     }
    ]
   }
 ]
}

Undo-redo actions in paid subscriptions only

You can activate this feature to enable users to undo/redo their actions in the editor. Please be advised that you need to implement the undo/redo buttons by yourself outside the Stripo Plugin Editor, and pass their IDs during the Plugin initialization (see the “Plugin initialization and configuration” section). This allows you to place these buttons anywhere on your web page and design them the way you like.

Social Networks

If your users want to share any data about their organization or site to the social networks they could use our basic “Social Networks” block for these purposes. They can choose a lot of icons and different styles for them. If needed your users can even upload their own images to the “Social Networks” block and then apply a necessary link.

You can add your favorite social networks in the “Social Networks” block, too. Your users will see it this way:

This block also supports the Share links, so anyone can share the email to his/her social network.

To include your favorite (predefined) social networks, add a config parameter in the initialization script, as you can see in the example below:

{
    "socialNetworks": [
        {
            "name": "twitter",
            "href": ""
        },
        {
            "name": "facebook",
            "href": ""
        }
    ]
}

Please see the full list of supported network names or icons:

Ask.fm
Behance
Dribbble
Facebook
Flickr
Foursquare
Google-plus
Instagram
Last.fm
Linkedin
Livejournal
Myspace
Odnoklassniki
Pinterest
Soundcloud
Tumblr
Twitter
Vimeo
Vkontakte
Weibo
Youtube
Hangouts
ICQ
Mail.Ru Agent
Messenger
Skype
Snapchat
Telegram
Viber
Wechat
Whatsapp
Slack
Blogger
Email
Website
Map Marker
World
Address
Share
RSS
AppStore
Playmarket
Windows Store
Medium

Basic blocks management

The general menu with blocks can be configured and displayed for end users in accordance with your preferences and/or needs.

For example, if you don’t want to display AMP blocks because your service doesn't support them, you can just hide it in the Plugin for the end user.

In this case, once the Plugin is initialized users will see the blocks this way:

Advanced Controls in paid subscriptions only

In this section, we gathered some advanced controls that can help your users create their email templates in the most powerful way. The list of these controls with their explanations is as follows:

Image Rollover Effect

This feature is also known as a mouseover. When you place a mouse cursor over an image, the latter is replaced with another one.
The image rollover effect works on desktop devices only. Other users will see the primary image. It can be applied to any image you add in email except for the banner one.
How to implement an image rollover effect with Stripo:

  1. Upload your first image.
  2. In the settings panel, toggle the “Rollover effect” button.
  3. Upload the second image — edit it if necessary.
  4. Insert a URL link — it will be tied to both images.
  5. Enter the “Alternate text”.
  6. Set alignment and size of the images.

To learn more about how image rollover effect can be used read this article.

Mobile Padding

If you turn on this control when you configure the Plugin, it will be added to the set of controls for structures, stripes, and basic blocks (e.g. “Image’, “Text”, “Button”, etc.) in the Padding section and will appear like this:

When a user selects any structure or block in the editor and then decides to set up individual padding for mobile, all they need to do is activate this control and enter values — this structure or block will be displayed with the specified padding values on mobile devices.

Hiding of element

In you turn on this control while you configure the Plugin, it will be added to the set of controls for every basic block (e.g. “Image”, “Image”, “Image”, etc.), containers, structures, and stripes and will appear like this:

When a user selects any of the elements in the editor and then decides not to display this element on mobile or on desktop only, all they need to do is activate this control and this is it — this element won’t be displayed when the email is opened on mobile devices or on desktop respectively.

Containers inversion on mobile

If you turn on this control when you configure the Plugin, it will be added to the set of structure controls only if there are 2 containers in it (the control will be hidden for structures with 1 or more than 2 containers inside) and will appear like this:

Please be advised that by default this control is turned off and also this control won’t be active in case a user turns off the “Responsive structure” control.

This control allows specifying which container should be displayed at the top and which one at the bottom of the mobile version of the email template.

If a user turns on the “Containers inversion on mobile” control, the containers will be placed on mobile the following way:

  1. the first container on the desktop will be displayed as the second container on mobile;
  2. the second container on the desktop will be displayed as the first one on mobile.

Alignment on Mobile

If you turn on this control when you configure the Plugin, the mobile icon will be added to the Alignment control of every basic block (e.g. “Image”, “Text”, “Button”, etc.) that have the “Alignment” control and will appear like this:

By default this icon is not activated, which means that the set alignment is relevant for the desktop version, yet will be the same for the mobile version if we do not specify another value.
To specify another value we should click on the “mobile” icon, it becomes activated (clicked), and then set another alignment by clicking on the proper icon here.

To switch back to the desktop version it is enough to click again on the “mobile” icon (it gets its default state when it’s non-clicked).

Border of Content of the Stripe

If you turn on this control when you configure the Plugin, it will be added to the set of stripe’s controls and will appear like this:

It allows setting the border for the content area of a selected stripe. It is possible to configure the borderline type (straight, dashed, dotted line), its color, and width for all sides or for a particular one (like only on the left side or on the top, etc.)

Background Color of Structure

If you turn on this control when you configure the Plugin, it will be added to the set of structure’s controls and will appear like this:

This control allows setting up the background color for a selected structure.

Background Color of Container

If you turn on this control when you configure the Plugin, it will be added to the set of container’s controls and will appear like this:

As the name suggests, this control allows setting up the background color for a selected container ;)

Background Image of Structure

If you turn on this control when you configure the Plugin, it will be added to the set of structure’s controls and will appear like this:

This control allows setting up any image as a background for a selected structure. It enables to configure the alignment and provides the ability to repeat a chosen image.

Background Image of Container

If you turn on this control when you configure the Plugin, it will be added to the set of container’s controls and will appear like this:

This control allows setting up any image as a background for a selected container. It enables to configure the alignment and provides the ability to repeat the chosen image.

Managing the Number of Containers in the Structure

If you turn on this control when you configure the Plugin, it will be added to the set of structure’s controls and will appear like this:

It allows adding or removing any existing container within a selected structure (it is possible to put up to 8 containers per structure). This control also allows changing the container’s width and indents between them.

Image Path

If you turn on this control when you configure the Plugin, the extra “Link” control will be added to the set of the Image block controls (as well as for the Menu, Banner blocks, etc) and will appear like this:

It allows specifying/replacing the URL to the image without making any changes to the HTML code. This feature is useful in case a user doesn’t want to place the image in your storage and simply wants to host it elsewhere (on an Internet site or any own storage of their own).

All they have to do is click on this “Link” control and replace the image URL with the required one in the “Image path” field.

Smart-elements Properties

This option provides the ability to activate smart properties for containers, structures, and stripes. If you activate this control when you configure the Plugin, and the user selects any container (structure or stripe) the new “Data” tab will be displayed at the top above the set of controls.

In this tab, a user has the ability to activate smart properties for a selected element and perform its configurations.

For more information about smart properties, please refer to our blog post – https://stripo.email/blog/smart-elements-reducing-time-creating-similar-letters-automating/.

Support of AMP HTML Mime type

In March 2019, Google released its AMP for emails technology. And as of July 2, 2019, it is available even for the G-Suite users and is “on” by default for all Gmail users. It allows senders to include AMP components inside engaging emails, making modern app functionality available within the email. This dynamic email format provides a subset of the AMP HTML components to use in email messages, that allows recipients of AMP emails to interact dynamically with content directly in the message.

Since June 18, 2019, Stripo has been supporting the creation of a new AMP HTML format of email template in the editor. To provide this option to your users you may activate the “Support of AMP HTML Mime type” on your Plugin details page. When it is activated and the user selects any block or container (structure or stripe) the new control will be added to the settings panel and will appear like this:

By default, all elements will be included in 2 versions of an email template: the traditional HTML version and the AMP HTML version. But users have a choice to include any element only in a particular version, for example, only in HTML or only in the AMP HTML version. In this case, that element will be highlighted with an orange border and a tooltip that indicates in which version that element is included. For more information on how to build AMP emails with Stripo, refer to our blog post – https://stripo.email/blog/how-to-build-amp-emails-with-stripo/

Please be advised that if the email template has at least one element that is included in the AMP version (or if it has a custom code with AMP components), then when you call the compileEmail JS function or compress method from your server, in addition to HTML version in response you will get the AMP HTML version of your email template. For more details, go to the Plugin Invocations section.

Image editor

This option helps you to enable or disable the image editor embedded in the Stripo Plugin. It helps to apply different effects to images, change their sizes, shapes, etc.
When it is activated and the user selects any image in email template, the new control will be added to the Settings panel and will appear like this:

Custom Components

External Images Library

If you have your own external image library that you would like your users to use while creating an email, you can display it instead of a Stripo image gallery. To do so, you need to set the externalImagesLibrary parameter when you initialize the Plugin:

To do so, you need to set the “externalImagesLibrary” parameter when you initialize the Plugin:

window.Stripo.init({
   ...,
   externalImagesLibrary: {
        openLibrary(onImageSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onImageSelectCallback({
                     originalName: 'YOUR_FILE_NAME.png',
                     resolution: '600 x 410 px',
                     size: '169.20 kb',
                     url: 'https://YOUR_STORAGE_URL/YOUR_FILE.png'
                  })
               when user select the image from external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }
    }
});

Please find a code example here to see how it works.

External Video Library

Just like in the case with the external image library, you also may display your own component with an external library of videos.

To do so, you need to set the externalVideosLibrary parameter when you configure the Plugin:

window.Stripo.init({
  ...,
  externalVideosLibrary: {
      buttonText: 'YOUR BUTTON NAME',
      open: openLibrary(onVideoSelectCallback, onCancelCallback) {
          /* Put your logic here.
             Call
                onVideoSelectCallback({
                  originalVideoName: 'YOUR VIDEO NAME',
                  originalImageName: 'YOUR IMAGE NAME',
                  urlImage: 'https://YOUR_STORAGE_IMAGE_URL.png',
                  urlVideo: 'https://your_storage_url/YOUR_FILE',
                  hasCustomButton: true || false
                })
             when user select the video from external library.
             Call
                onCancelCallback()
             when user close the library without video selection.
          */
      }
  }
});

Please find a code example here to see how it works.

External Merge Tags

If you have your own merge tags library that you would like your users to use while creating an email, you can display it instead of a Stripo merge tags.

To do so, you need to set the externalMergeTags parameter when you initialize the Plugin:

window.Stripo.init({
...,
      externalMergeTags: {
      open: open(oneSelectCallback) {
         /* Put your logic here.
            Call
               oneSelectCallback('%%YPUR_MERGE_TAG%%')
               when user selects the merge tag from external.
         */
      }
  }
});

Please find a code example here to see how it works.

File Picker for Links

If you want to add your own control for selecting a file from an external file system in the pop-up window to be linked with the existing Link control for every basic block, you can set the externalFilesLibrary param when you initialize the Plugin:

window.Stripo.init({
  ...,
  externalFilesLibrary: {
        buttonText: 'YOUR BUTTON NAME',
        open: openLibrary(onFileSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onFileSelectCallback('https://YOUR_STORAGE_FILE_URL')
               when user select the file from external library.
               Call
                  onCancelCallback()
               when user close the library without file selection.
            */
        }
    }
});

As a result your customers can add the file by clicking on the right button.

Please find a code example here to see how it works.

Smart Modules

To display your own external data list in a pop-up window that users can choose to dynamically retrieve data from for their smart modules, you can set the externalSmartElementsLibrary parameter when you initialize the Plugin:

window.Stripo.init({
   ...,
   externalSmartElementsLibrary: {
        openLibrary(onDataSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onDataSelectCallback({
                	key: value
})
               when the user selects the data from the external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }
    }

Please find a code example here to see how it works.

If you want to provide option to choose whether use external data list or website data list, you can set up additional parameter enableWebSiteLinksForSmartElementsLibrary when you initialize the Plugin:

window.Stripo.init({
   ...,
   externalSmartElementsLibrary: {
        openLibrary(onDataSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onDataSelectCallback({
                	key: value
})
               when the user selects the data from the external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }, enableWebSiteLinksForSmartElementsLibrary : true,
    }

As a result your customers can add their own data from the site or external source.

AMP Form Services

This parameter is an array of objects with the value and label fields that are used for collecting data from the AMP Form block. Label is the name of the service where the data from the AMP Form would be sent to, Value is a link to the endpoint for submitting forms.

  "ampFormServices": [
    {
      "label": "My endpoint 1",
      "value": "https://my-endpoint1.net"
    },
    {
      "label": "My endpoint 2",
      "value": "https://my-endpoint2.net"
    }
  ]

This is how a predefined list of services looks in the editor when a user clicks on the Form block inside their email template.

Editor extensions in business and enterprise subscriptions only

If you want to create your own editor blocks, flexibly customize their behavior and manage email layout, you can use the Stripo editor extensions.

First, create your own extension following the steps below:

  1. Checkout out the https://github.com/ardas/stripo-plugin-samples repository
  2. Navigate to preferred extension example in /extensions folder
  3. Install dependencies:
    npm i
  4. Replace sample extension code with your logic
  5. Compile this code
    npm run build

The ready-to-use code will be stored in the dist folder. Then you will need to store the compiled extension files on your hosting. When you initialize the Plugin, insert the code sample given below:

  window.Stripo.init({
       ...,
       "extensions": [
           {
             "globalName": "YourExtensionName",
             "url":"https://your.hosting/main.hash.extension.js"
           }
         ]
   });

Please find the code example and detailed guidelines here.

Plugin Notifications

This is useful for those who want to show messages or notifications to users when an action is performed in the editor, e.g. the image is uploaded, the module is saved, etc.

You have the opportunity to display the editor’s messages with the script initialization and call one of these functions:

{
    "notifications": {
        "info": message => console.log(message),
        "error": message => console.error(message),
        "success": message => console.log(message),
        "warn": message => console.log(message),
        "loader": message => console.log(message),
        "hide": message => console.log(message)
    }
}

You need to configure these functions to show messages in the correct place and styled the way you like.

Server Configuration

In this chapter, you’ll find instructions on how to set up and customize the Plugin’s backend.

Permissions Checker API

Using this option you can be sure that only your users have the rights to edit emails in your application. Enable the permissions checker feature to prevent third-party people from pretending to be who they are not.

This means that the Stripo Plugin will not perform any server-side operation (load/save/update...) without permissions from your end. To enable this feature, you need to implement this backend endpoint on your server.

{
    "POST": "/",
    "Host": "YOUR_PERMISSIONS_CHECKER_URL",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Body": {
        "pluginId": "YOUR_PLUGIN_ID",
        "uiData": {
            "emailId": "123",
            "someAnotherIdentifier": "456",
            ...
        },
        "requestPermissions":
        [
            {
                "type": "BLOCKS",
                "action": "READ",
                "key": "pluginId_YOUR_PLUGIN_ID_emailId_123_id_456",
                "keyTemplate": "emailId_${emailId}_id_${someAnotherIdentifier}"
            },
            ...
        ]
    },
    "Response": {
        "grantPermissions": [
            {
                "type": "BLOCKS",
                "action": "READ",
                "key": "pluginId_YOUR_PLUGIN_ID_emailId_123_id_456",
                "keyTemplate": "emailId_${emailId}_id_${someAnotherIdentifier}"
            },
            ...
        ]
    }
}

Please take a look at the descriptions of the request parameters below:

Parameter
Description
pluginId
Your plugin ID.
uiData
The value of apiRequestData parameter from plugin initialization parameters.
requestPermissions
Array of permissions that plugin requests.
type
Operation subject. Supported values: BLOCKS, DOCS.
action
Operation type. Supported values: READ, MODIFY.
key
Key identifier that was configured in plugin settings with filled values.
keyTemplate
Key identifier that was configured in plugin settings.

Please take a look at the descriptions of the response parameters below:

Parameter
Description
grantPermissions
Array of operations for plugin that are allowed to do. If you want to deny some operation just do not include it into this array.
type
Operation subject. Supported values: BLOCKS, DOCS.
action
Operation type. Supported values: READ, MODIFY.
key
Key identifier that was configured in plugin settings with filled values.
keyTemplate
Key identifier that was configured in plugin settings.

When choosing the Permissions Checker API option, you have to fill out the form to establish a connection with your backend. This is a description of the form fields with specifications regarding what information you will need to provide:

Parameter
Required
Description
URL
Yes
Endpoint address of your permissions checker backend.
Login
Yes
Basic auth username.
Password
Yes
Basic auth password.

AutoSave Option in paid subscriptions only

Whenever users make any changes to the email they are working on, these changes should be saved automatically. The Plugin sends micro changes (we call them “patches”) to its server, which in turn recreates the final version of the edited email template from them and sends it to your server for further saving/processing.

Enable the AutoSave option on the Plugin details page to receive a fresh version of the HTML and CSS code to your backend every time a change has been done by a user in the editor.

To support this option, you need to implement the interface on your backend that will receive the calls:

{
    "POST": "/",
    "Host": "YOUR_BACKEND_AUTO_SAVE_URL",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Body": {
        "key": "plId_YOUR_PLUGIN_ID_emailId_YOUR_EMAIL_ID_FROM_UI_REQUEST_PARAMS",
        "emailId": "YOUR_EMAIL_ID_FROM_UI_REQUEST_PARAMS",
        "html": "YOUR_HTML_CODE",
        "css": "YOUR_CSS_CODE",
        "width": "EMAIL_WIDTH",
        "height": "EMAIL_HEIGHT"
    },
    "Response status": "200 OK"
}


Please take a look at the descriptions of the request parameters below:

Parameter
Description
key
Email’s unique AutoSave key that contains the pluginId and emailId params.
emailId
Email ID from the request params. See the “Plugin request parameters” section.
html
HTML code.
css
CSS code.
width
Email width.
height
Email height.

The Basic Authentication is used to send these requests, so please make sure that you have specified the correct Login, Password, and API URL in the Stripo Plugin Integration menu in your Stripo account (if you don’t have an account, please

sign up).

Version History in paid subscriptions only

This option enables your users to view changes of an opened email template in the editor, as well as gives the ability to restore any previous version of the email template from earlier versions.

When it is activated your users can track all changes displayed in the Settings Panel area. As soon as they click on a particular change, they are able to restore the opened email template to the selected version.

Please note: the editor won't display a user name if it was not passed as one of the parameters with the Plugin initialization.

You can place the button/LINK (the trigger) in your application, by clicking on which the mode Version history of an opened email template will be activated.

Once this option is activated, please add these config parameters to the Plugin initialization call (see the “Plugin configuration” section):

{
    "userFullName": "YOUR_PLUGIN_USER_NAME",
    "versionHistory": {
        "changeHistoryLinkId": "YOUR_LINK_ELEMENT_ID",
        "onInitialized": "function(lastChangeInfoText)" {
            // Do any additional actions here when version history is initialized
        }
    }
}

If you do not use the AutoSave Option you can independently create the points displayed in the Version history section.

To do so, please add this function and call this method every time a template is saved on your end or when you want the corresponding entry to appear in the Version history:

function saveVersionHistoryPoint(onSaveCallback)
{
    if (window.StripoApi.createVersionHistoryPointAsync)
{
     	   window.StripoApi.createVersionHistoryPointAsync(onSaveCallback);
    }
   else {
        // Deprecated
        window.StripoApi.createVersionHistoryPoint();
        onSaveCallback();
    }
}

This function will create visible endpoints in the Version history and update the data of the last changes. You can independently choose where it should be applied, we recommend that you use it every time when your user clicks on the "Save" button.

If an AutoSave option is activated and configured, then all changes made in the editor will be automatically saved to our DB as a patch.

As soon as they are saved, our server will send the request to your end-point set for the AutoSave option with the changed HTML and CSS in order to replace the previous version in your DB. As a result, every change made by a user in the editor will be saved in your DB for that particular email and you have only the final, most up-to-date version of every template, opened in the editor.

If this feature is not activated, then a user has to click on the Save button manually within your app and you should call the getTemplate function to take out modified HTML and CSS from the editor in order to save it within your DB.

Roles and Access Managements

Soon we will add the ability to manage the roles you can assign to any user when you initialize the editor.

Currently, there are only 2 roles preset by default in the system:

  • Admin
  • User

You can use these roles when you configure the access levels to the folders created in the image gallery and in the Library of modules. Pass correct roles with authentication (see the “Plugin authentication” section) to enable your users to write data in one or the other folder: the image gallery or the Library of modules.

Plugin Invocations

The Stripo Plugin has the Javascript API and Backend API, where the Javascript API is used for interaction with the UI part of the Plugin and the Backend API is used to combine two files, HTML and CSS, to get a ready-to-send email template.

Stripo Plugin JS API

The Stripo Plugin JS API can be accessed via the window.StripoApi js object.

The list of available JS API functions:

Function
Input parameters
Output parameters
Description
getTemplate
callback
This method returns the HTML and CSS codes with the Plugin internal extra styles and editor markup.
Format: callback(HTML, CSS, width, height).
You should call the getTemplate function to take out modified HTML and CSS from the editor in order to save it in your DB. Please, check out the samples in our GitHub repository.
compileEmail
callback, minimize
This method returns compiled and compressed HTML code that is ready to be sent out to clients.
Format:
callback(error, html, ampHtml, ampErrors).

If an error occurs, the first parameter will contain the error description.
In case of success, the first parameter will be null and the second parameter will contain HTML code.

In case your email template contains AMP elements or components, the third parameter will contain the HTML code of the AMP HTML Mime type.
In case AMP HTML is invalid, the fourth parameter will contain the error descriptions (array of strings). minimize — boolean flag. If true — the HTML code will be in a format of a single line without line breaks.
Example:
compileEmail(function(error, html, ampHtml, ampErrors) {...}, false)
getTitle
emailTitle
This method returns an email title/subject line.
setTitle
emailTitle
This method sets an email title/subject line.
getHiddenPreHeader
preHeader
This method returns an email’s hidden preheader.
setHiddenPreHeader
preHeader
This method sets an email’s hidden preheader.
getGoogleAnnotations
null || { logo: 'https://logo', description: 'description', discountCode: 'discountCode', availabilityStarts: '2019-06-26T04:04:00+00:00', availabilityEnds: '2019-06-30T04:04:00+00:00', image: 'https://image' };
This method returns the Gmail Promo Annotations’ microdata inserted into the HTML code of the email template in the editor.

In case the microdata code is not available there, the null value is returned.

If any of the parameters are disabled or empty, then the empty data is returned (for example, discountCode: '').
For more information on these parameters, please refer to this page (go to the “Generate my code” button and check the “Microdata Format” tab) or on our blog here
setGoogleAnnotations
{ logo: 'https://logo', description: 'description', discountCode: 'discountCode', availabilityStarts: '2019-06-26T04:04:00+00:00', availabilityEnds: '2019-06-30T04:04:00+00:00', image: 'https://image' } || null;
This method inserts/updates the Gmail Promo Annotations’ microdata in HTML code of the opened email template in the editor.
In case you want to disable the whole feature please pass the null value. Otherwise, you will pass all or any parameters with the data according to these requirements.
If you want to disable any of the parameters, simply pass the empty data (for example, discountCode: '').
Please find more information on every parameter here (click on the “Generate my code” button and check the “Microdata Format” tab) or on our blog here.
allDataSaved
-
true/false
This parameter helps to identify whether all changes are saved or not.
If something was not saved it returns False, if everything saved - True.
Can be applied only if you don’t use Autosave option
showAmpErrorsModal
ampErrors, userSuccessButtons onCancel, onSubmit
-
Use this function to display the AMP validation errors in the Stripo preview mode if there are any in the email template.

Example: showAmpErrorsModal(ampErrors, userSuccessButtons, onCancel, onSubmit)

The first parameter ampErrors represents the array of AMP errors received after calling the compileEmail function.

The second parameter userSuccessButtons includes the array of external buttons that may be displayed in the preview window in case if there are no validation errors.

The third parameter OnCancel is a callback function the editor may call if the user closes the preview window.

The fourth parameter onSubmit is a callback function the editor may call when the user clicks on the “Fix in Code Editor” button if there are any errors. Please be advised that this button won’t be displayed if you did not pass the codeEditorButtonId with the Plugin initialization.

Please find the detailed description here.

Stripo Plugin Backend API

As mentioned above, the Stripo Plugin Backend API endpoint allows inlining CSS styles into HTML tags and provides the final HTML code of email templates that is ready to be sent to recipients.

POST: /api/v1/cleaner/v1/compress
Host: https://plugins.stripo.email
Content-Type: application/json
Header: ES-PLUGIN-AUTH: Bearer YOUR_AUTH_TOKEN
Accept: application/json
Body: {html:YOUR_HTML_CODE, css:YOUR_CSS_CODE, minimize:true}
Response: {html:HTML_READY_TO_BE_SENT}

Please see the descriptions of the request parameters below:

Parameter
Description
html
HTML code.
css
CSS code.
minimize
If true — html code will be in a format of a single line without line breaks.

To get YOUR_AUTH_TOKEN please take a look at this section.

Please be advised that if your email template contains AMP elements or components, in response you will see the ampHtml parameter that contains the HTML code of the AMP HTML Mime type.

In case the AMP HTML is invalid, you will also get the ampErrors parameter that contains the error descriptions (array of strings).

Example:

Request:
curl -X POST https://plugins.stripo.email/api/v1/auth -k -H "Content-Type: application/json" -H "Accept: application/json" --data "{\"pluginId\":\"YOUR_PLUGIN_ID\",\"secretKey\":\"YOUR_SECRET_KEY\"}" -i

Response:
{"token":"YOUR_AUTH_TOKEN"}

Request:
curl -X POST https://plugins.stripo.email/api/v1/cleaner/v1/compress -k -H "Content-Type: application/json" -H "Accept: application/json" -H "ES-PLUGIN-AUTH: Bearer YOUR_AUTH_TOKEN" --data "{\"html\":\"Some html\",\"css\":\"body {color: green}\",\"minimize\":true}" -i

Response:
{"html":"Some html"}

Helpers

How to Call the showAmpErrorsModal Function

Some errors may appear when users work on their emails. In order to notify your users about such errors and help them fix the bugs, the showAmpErrorsModal function is at your service.

Please see the example of how to call the showAmpErrorsModal function below:

showAmpErrorsModal(
	ampErrors,
	[
		{
			text: 'Preview',
			action: () => {console.log('"Preview" button clicked');}
		}
	],
	() => {console.log('"Close" button clicked');},
	() => {console.log('"Fix in Code Editor" button clicked');}
)

If you have set the option to display the code editor codeEditorButtonId, the “Fix in Code Editor” button will also be displayed:

Upon a click on this button, the preview window will be closed and the code editor will get opened instead. If you want anything else (not the code editor) to open upon a click on this button, then pass the 4th parameter to this function.

Once the “Close” button is clicked, you can add a callback function with the 3rd parameter, as well.
Upon a click on the red badge displayed on the code editor panel, the previous AMP errors will be displayed.

To run the email code validation again, the user has to click on the “Repeat check” button.

In case, no errors received once the email code validation check is completed, the editor will display the success notification message in the preview window as shown below:

If you want to display your custom buttons in this window, make sure you have passed them to the second parameter of the “showAmpErrorsModal” function. In our example above, we passed the “review” button that triggers opening the preview mode on an external application.

If the second parameter is empty, the only “Close” button will be displayed.

Configuration of AWS S3 Storage

To create custom AWS S3 storage, you need to:

  1. Create an Amazon AWS account.
  2. Create an IAM user with S3 bucket permissions.
  3. Create IAM policy:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "VisualEditor0",
                "Effect": "Allow",
                "Action": "s3:ListBucket",
                "Resource": "arn:aws:s3:::bucketname"
            },
            {
                "Sid": "VisualEditor1",
                "Effect": "Allow",
                "Action": "s3:GetObject",
                "Resource": "arn:aws:s3:::bucketname/*"
            },
            {
                "Sid": "VisualEditor2",
                "Effect": "Allow",
                "Action": [
                    "s3:PutAnalyticsConfiguration",
                    "s3:GetObjectVersionTagging",
                    "s3:CreateBucket",
                    "s3:ReplicateObject",
                    "s3:GetObjectAcl",
                    "s3:DeleteBucketWebsite",
                    "s3:PutLifecycleConfiguration",
                    "s3:GetObjectVersionAcl",
                    "s3:DeleteObject",
                    "s3:GetBucketWebsite",
                    "s3:PutReplicationConfiguration",
                    "s3:GetBucketNotification",
                    "s3:PutBucketCORS",
                    "s3:GetReplicationConfiguration",
                    "s3:ListMultipartUploadParts",
                    "s3:PutObject",
                    "s3:GetObject",
                    "s3:PutBucketNotification",
                    "s3:PutBucketLogging",
                    "s3:GetAnalyticsConfiguration",
                    "s3:GetObjectVersionForReplication",
                    "s3:GetLifecycleConfiguration",
                    "s3:ListBucketByTags",
                    "s3:GetInventoryConfiguration",
                    "s3:GetBucketTagging",
                    "s3:PutAccelerateConfiguration",
                    "s3:DeleteObjectVersion",
                    "s3:GetBucketLogging",
                    "s3:ListBucketVersions",
                    "s3:RestoreObject",
                    "s3:ListBucket",
                    "s3:GetAccelerateConfiguration",
                    "s3:GetBucketPolicy",
                    "s3:GetObjectVersionTorrent",
                    "s3:AbortMultipartUpload",
                    "s3:GetBucketRequestPayment",
                    "s3:GetObjectTagging",
                    "s3:GetMetricsConfiguration",
                    "s3:DeleteBucket",
                    "s3:PutBucketVersioning",
                    "s3:ListBucketMultipartUploads",
                    "s3:PutMetricsConfiguration",
                    "s3:GetBucketVersioning",
                    "s3:GetBucketAcl",
                    "s3:PutInventoryConfiguration",
                    "s3:GetObjectTorrent",
                    "s3:PutBucketWebsite",
                    "s3:PutBucketRequestPayment",
                    "s3:GetBucketCORS",
                    "s3:GetBucketLocation",
                    "s3:ReplicateDelete",
                    "s3:GetObjectVersion"
                ],
                "Resource": "arn:aws:s3:::bucketname/*"
            },
            {
                "Sid": "VisualEditor3",
                "Effect": "Allow",
                "Action": [
                    "s3:ListAllMyBuckets",
                ],
                "Resource": "*"
            }
        ]
    }

    Please be advised that you should replace the bucketname value with the name of your bucket created in your AWS account.

  4. Assign the created policy to the IAM user:
  5. Create the S3 bucket with a necessary custom name and in a necessary region:
  6. Choose Static website hosting and index document index.html:
  7. Set Bucket permission policy.
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "PublicReadGetObject",
                "Effect": "Allow",
                "Principal": "*",
                "Action": "s3:GetObject",
                "Resource": "arn:aws:s3:::bucketname/*"
            }
        ]
    }
    

    Please be advised that you should replace the bucketname value with the name of your bucket created in your AWS account.

  8. Deactivate Objects from the bucket permissions:
  9. Add settings to web server, e.g., nginx:

    location /content {
      add_header 'Access-Control-Allow-Origin' '*';
      proxy_pass  https://s3-eu-west-1.amazonaws.com/bucketname;
      proxy_redirect off;
    }
    
  10. Enter “YOUR_DOMAIN_ADDRESS/content” as “Base Download URL” when you configure the Plugin settings.