Stripo Plugin Reference

Developer Guide

Getting Started

Displaying the editor

Stripo plugin is written in native Javascript and designed like a component in a way to be easily configured and extended within your web-application.

From UI point of view it's just a 2 div areas (Settings Panel and Preview Area) and one JS that can be configured according to your needs to be embedded into these areas.

In order to display the plugin on your end please do the following:

1. Define the layout for plugin containers

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

<div id="stripoSettingsContainer"></div>
<div id="stripoPreviewContainer"></div>
2. Include Script

Include the script taken from the application details page of the Stripo Plugin Integration menu of your Stripo account (if you don’t have an account, sign up).

<script src="https://plugins.stripo.email/static/latest/stripo.js"></script>

                                    or

<script src="https://plugins.stripo.email/static/rev/[version]/stripo.js"></script>

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.

Plugin initialization

Once you have added 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 be:

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
   }
});

Plugin configuration

Here is the list of available configuration parameters:

Parameter
Required
Description
Default
locale
No
2-letter language identifier.
Available Languages:
English: “en”
Spanish: “es”
French: “fr”
German: “de”
Italian: “it”
Slovenian: “sl”
Russian: “ru”
Ukrainian: “uk”
“en”
previewId
Yes
ID of preview container.
settingsId
Yes
ID of settings container.
apiRequestData
Yes
These parameters will be passed to backend with every request. See “Plugin request parameters” section for details.
getAuthToken
Yes
To get auth token from backend this function should be implemented. See “Plugin authentication” section for details.
html
No
HTML code should be open.
css
No
CSS code should be applied to email.
userFullName
No
Full name of the user who uses the editor
codeEditorButtonId
No
ID of open/close code editor button.
undoButtonId
No
ID of undo button.
redoButtonId
No
ID of 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 fire clickOutsidePreview event and as a result does not reset block selection in preview area
notifications
No
Set of methods that will be called when some message needs to be visible for user. See “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 into “Social Networks” block. See “Social Networks" section for details.
mergeTags
No
List of merge tags to be included in Text Editor panel. See “Merge Tags” section for details.
See “Merge Tags” documentation for default values
viewOnly
No
Set to TRUE if you want to disable email modifications.
false
apiBaseUrl
No
Stripo Plugin main backend entrypoint.
/pluginapi/api/v1
bankImagesDefaultSearchString
No
Default search string for images from the “Image Bank”.
Depends on season: “spring” / “summer” / “autumn” / “winter”
versionHistory
No
See “Version History” section for details
draft
No
The Stripo Plugin supports auto-save which 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 it is expressed in the examples.
draft: { showAutoSaveLoader: function() {console.log('Auto save in process')}, hideAutoSaveLoader: function(error) {console.log('Auto save completed')} }

Plugin request parameters

Plugin configuration contains parameter called “apiRequestData”. This is a JSON object that contains parameters that will be sent to server with each request. They are used to identify path to image library documents and modules. All of them are sent to a third-party permission checker system. See the Permissions checker API section.

The only “emailId” param here is mandatory for Stripo Plugin infrustructure. It is a string type of data with the max limit of 255 characters.

Use different emailId values for different emails to provide correct work of autosaving feature.

Plugin authentication

To authenticate your instance with Stripo Plugin Editor, call the endpoint 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 user editor role. For example: “ADMIN”.

Plugin configuration contains parameter called getAuthToken. Plugin calls 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.

The full authentication schema should look like this:

  1. Stripo Plugin can't do any operation without authentication token. To get it plugin calls "getAuthToken" function defined in Customer Application UI.
  2. Customer Application UI sends GET request without any parameters to Customer Application Backend (for example "/token" request).
  3. Customer Application Backend loads "Plugin Id" and "Secret Key" values from storage.
  4. Customer Application Backend sends "/auth" POST request to Stripo Plugin Backend with "pluginId", "secretKey" and "role" parameters.
  5. Stripo Backend generates plugin authentication token.
  6. Stripo Backend sends token back to Customer Application Backend.
  7. Customer Application Backend sends token back to Customer Application UI.
  8. Customer Application UI calls "callback(token)" method from "getAuthToken" method params to load token to Stripo Plugin.
Wrong authentication implementation
IMPORTANT

Do NOT call Stripo Backend directly from UI. It is insecure and your "Secret Key" can be stolen. Keep your "Secret Key" on your backend and do not tell it to anyone.

Example of “getAuthToken implementation”:

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)
   });
}

Template requirements

The email templates that may be created/edited with Stripo editor, consist of two parts: the HTML code and the CSS code. These parts of one template should be stored in customer’s database separately and passed simultaneously (see the initialization parameters) when the user decides to edit the template.

In order to activate editor’s drag-n-drop feature for an imported email template, it is required that this 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 Stripo editor, please make sure you have converted the HTML code of those templates correctly (with specific classes included into their HTML code) to activate Stripo editing features. Please, read 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/

If you want to show Stripo free email templates and display them in you application for your end users for inspirational purposes you can download them from here.

If you want to open the editor to enable your users to create new email templates (as if they click “Create template from the scratch”) please go to the editor, find HTML and CSS code of an empty (scratch) email template that can be used as default email template. It is required that the email template HTML code has at least one stripe with one structure in it. The examples of basic and empty email templates can be taken from here.

UI Configuration

The UI settings can be configured in the the ‘UI settings’ tab. Get there from the application details page of the Stripo Plugin Integration menu in your Stripo account (if you don’t have one, sign up).

Please see explanations of each UI Settings controls provided below.

Image storage configuration

In Stripo editor, image management can be performed through Image Gallery, which can be configured according to your needs on the application details page.

It is up to you to configure the features as follows:

  1. Image Storage;
  2. Folder Configuration;
  3. Limits;
  4. Stock Images Configuration.

Image Storage

Stripo currently supports 4 different ways to store images, used in your instance of plugin:

Stripo storage

This option is activated by default when you create plugin application. Please be advised that there might be a limitation to use Stripo storage depending on the selected plugin pricing 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.

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 store images.

When choosing this option, you have to fill out the form to establish connection with your storage. This is a description of the form fields with specifications regarding what information you will need to provide in 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 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 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 on your S3 bucket. For example, it may be your CDN domain name or any other address, depending on your server configuration.

Please be sure that provided account has read and write access to the given bucket. You can take a look at the Helpers section to get more details on how to configure your AWS S3 storage More about AWS credentials.

Azure Blob storage

Azure Blob storage is a plugin application configuration feature that allows you to easily connect your own Azure storage account to store images.

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

When choosing “Azure Blob Storage” option, you have to fill out the form to establish connection with your storage. This is a description of the form field with specifications regarding what information you will need to provide in each of them:

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

We created a way to connect to a custom file system provider (via HTTP protocol), allowing you to use Stripo editor with your own file storage, no matter which technology you use. A custom file system provider is an API that will allow the Stripo editor to perform actions with files out of the plugin environment, connecting your file system to Stripo’s file manager. It can be built with your preferred technology: just be sure to follow our instructions to provide successful communication between the two systems.

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

File system operations:

GET LIST OF FILES

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}]}, {key: KEY_FOLDER_2, documents:[]}]
Parameter
Description
key
It is generated from the application's Id and the specified value to the Folder path in which the image is loaded. For example: key=0000000_99999, where 0000000 is the application's id and 99999 is the value set to the Folder path.
documents
Array of the documents grouped by key.
url
Absolute url of the document.
originalName
Document name.
uploadTime
Time of document upload in milliseconds.
size
Document size in bytes.

UPLOAD FILE TO STORAGE

POST: /
Host: YOUR_BASE_URL
Content-Type: multipart/form-data
Transfer-Encoding: chunked
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}
Parameter
Description
key
It is generated from the application's Id and the specified value to the Folder path in which the image is loaded. For example: key=0000000_99999, where 0000000 is the application's id and 99999 is the value set to the Folder path.
file
Multipart file.

DELETE/REMOVE FILE FROM STORAGE

POST: /delete
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Body: {url:DOC_URL}
Parameter
Description
url
Absolute url of the document.
key
It is generated from the application's Id and the specified value to the Folder path in which the image is loaded. For example: key=0000000_99999, where 0000000 is the application's id and 99999 is the value set to the Folder path.

GET FILE INFO

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}
Parameter
Description
src
Absolute url of the document.

Folder Configuration

In the Image Gallery, customer may see as many folders (tabs) as you have configured for your plugin application. For example, below you may see 3 folders in the Image Gallery called “Email”, “Project”, “Common”.

This is because they were configured this way on the application details page.

In this section, you can manage:

  • the number of folders – simply click the “Add” icon to add a new folder or the “Remove” button to delete one. Please, be advised that in case a folder is removed it won't be displayed on UI anymore but the folder itself and all images in it will still be existing.
  • 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 particular folders. You can specify the relative path to the repository and insert into 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 ${emailId}. When initializing the plugin, you have to pass the emailId value (e.g. 00000) among the parameters and, as a result, the the plugin will get the images from that folder 00000 (this folder will be automatically created in case it does not exist).
  • and define the write permissions. At this stage, there are only two predefined roles in the Stripo editor. Please, read more about it here. By leveraging the proper role you can manage who of your customers is able to add and remove images to/from particular folders.

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

Limits

You can set the maximum size of one image uploaded to Image Gallery by your customers. The limit can be specified for all folders simultaneously in a range from 1 to 20 Mb per 1 file.

Stock Images Configuration

In case you want to provide your customers with an option to search and use free stock images within Image Gallery when they create email templates with Stripo builder, you need to simply activate the ‘Stock images’ option.

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

Currently we do support only Pexels.com and Pixabay.com providers. The list of providers will be extended in the future.

Configuration of custom modules library

Similar to the Image Gallery, customer may see as many folders (tabs) in the Modules as you configured for your plugin application. For example, below you may see 3 folders in the Library of custom modules called “My blocks”, “Template blocks”, “General blocks”.

This is because they were configured this way in the application details page

In this section you can manage:

  • the number of folders – simply click the “Add’ icon to add a new folder or the “Remove” button to delete one. Please, be informed that in case a folder has been removed it won't be displayed on UI as well as all saved modules removed from the server.
  • their names. You have the option to specify what names a created folder should have in every supported language.
  • the storage key ID will be assigned to modules and will be used as an identifier. You can specify the key as a static value or variable (use braces for this). For example, if you want to restrict access to the modules of one customer from another, you can create the ‘My blocks’ folder and specify its path as ${UserId}. When initializing the plugin, you have to pass the userId value (e.g. 00000) among the parameters and, as a result, the the plugin will get the modules from the DB by the key “00000”.
  • and define the write permissions. At this stage, there are only two predefined roles in the Stripo editor. Please read more about it here. By leveraging the proper role you can manage who of your customers is able to add and remove modules to/from particular folders.

Please be informed that you can turn off this feature so that Library section won’t be displayed in the editor at all. In this case there won’t be an option to save selected elements from the context menu

Merge Tags

Merge tags help dynamically insert text templates into a text, such as the very common scenarios, like “Dear {first_name}”.

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

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

Here is the example of creating mergeTags you can pass while plugin initialization:

{
    "mergeTags": [
        {
            "category": "MailChimp",
            "entries": [
                {
                    "label": "First Name",
                    "value": "*|FNAME|*"
                }
            ]
        }
    ]
}

Here is the description of parameters:

Parameter
Description
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.

Undo-redo actions

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

Social Networks

You can include your favorite social networks in “Social Network” block. To do this, add this config parameter:

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

Full list of supported network names:

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

While configuring Stripo plugin application you can decide which basic blocks to display in the initialized editor for your users.

In case you want to hide any of the blocks on editor’s UI please be sure to have turned them off in the plugin configuration section named “Basic blocks management”

Advanced controls settings

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

Hiding of element

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

When a customer 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

In case you turn on this control while configuring 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 informed that by default this control is turned off and also this control won’t be active in case if a customer turns off the “Adaptive structure” control.

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

In case a customer turns on the “Container inversion on mobile” control, the containers will be placed on mobile the following way:

  1. the first container on the desktop will be displayed under the second container on mobile;
  2. the second container on the desktop will be displayed above the first one on mobile.
Different alignment of basic block on mobile

In case you turn on this control while configuring 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 selected alignment is relevant for desktop version, yet will be the same for mobile version if we do not specify another value.

To specify another value we should click on ‘mobile’ icon, it becomes activated (clicked), and then choose another alignment by clicking on proper icon here

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

Border of content part of the stripe

In case you turn on this control while configuring the plugin, it will be added to set of stripe’s controls and will appear like this:

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

Background color of structure

In case you turn on this control while configuring 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 the selected structure.

Background color of container

In case you turn on this control while configuring the plugin, it will be added to set of container’s controls and will appear like this:

It is obvious from the name, this control allows setting up the background color for the selected container.

Background image of structure

In case you turn on this control while configuring 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 ability to repeat a chosen image.

Background image of container

In case you turn on this control while configuring 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 chosen image.

Managing the number of containers in the structure and their sizes

In case you turn on this control while configuring the plugin, it will be added to the set of structure’s controls and will appear like this:

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

Image path

In case you turn on this control while configuring the plugin, the extra ‘Link’ control will be added to the set of 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 customer doesn’t want to place the image in your storage and simply wants to host it elsewhere (on Internet site or any own storage). All they have to do is click on this “Link” control and replace the image URL with required one in the “Image path” field.

Smart-elements properties

This option provides ability to activate smart properties to containers, structures and stripes. When this control is activated while configuring the plugin, and customer selects any container (structure or stripe) the new ‘Data” tab will be displayed at the top above set of controls.

In this tab a customer has an ability to activate smart properties for a selected element and perform its configurations. Please read more about this here – https://stripo.email/blog/smart-elements-reducing-time-creating-similar-letters-automating/.

Plugin notifications

When plugin needs to show message to user it calls 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 override these functions to show messages in correct place and styled the way you wish.

Server Configuration

The set of server-side settings can be configured in the Server settings’ tab from the application details page of the Stripo Plugin Integration menu of your Stripo account (if you don’t have an account, sign up).

You can find the explanations of each of Server Settings controls with code samples below.

Permissions checker API

Make sure only your users have the rights to edit emails in your application. Enable operation permissions checker to prevent third-party people from pretending to be who they are not!

This means that 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 end.

{
    "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}"
            },
            ...
        ]
    }
}

REQUEST PARAMETERS:

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.

RESPONSE PARAMETERS:

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 Permissions Checker API option, you have to fill out the form to establish 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.

The Basic Authentication is used to send these requests.

Autosaving feature

Enable this feature to receive a fresh version of HTML and CSS code at your backend every time a change has been done to the code by a user.

You need to implement this backend endpoint:

{
    "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"
}


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

REQUEST PARAMETERS:

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

Version history and restoring email templates from previous revisions

This option enables to provide ability to your customers to be able to view changes of an open email template in the editor, as well as the function to restore the current version of the email template from earlier versions. You can place inside your application the link (trigger), by clicking on which the mode of viewing the history of changes of an open email template can be activated.

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

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

To activate version history feature add this config parameters (see “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
        }
    }
}

Plugin Invocations

Stripo Plugin has the Javascript API and backend API.

Stripo Plugin JS API

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

The list of available JS API functions:

Function
Input parameters
Output parameters
Description
getTemplate
callback
This method returns HTML and CSS codes with plugin internal extra styles and editor markup.
Format: callback(HTML, CSS, width, height).
Call this method to save HTML and CSS to storage and later to load them to the editor again.
compileEmail
callback, minimize
This method returns compiled and compressed HTML code ready to be sent to clients.
Format: callback(error, html).
In case of error first parameter will contain error description.
In case of success first parameter will be null and second parameter will contain html code.
minimize — boolean flag. If true — html code will be in a format of a single line without line breaks
getEmail
callback
This method returns clean HTML and CSS code without any additional editor markup. Format: callback(HTML, CSS, width, height).
getTitle
emailTitle
This method returns email title.
setTitle
emailTitle
This method sets email title.
getHiddenPreHeader
preHeader
This method returns hidden preheader in emails.
setHiddenPreHeader
preHeader
This method sets hidden preheader in emails.

Stripo Plugin Backend API

Stripo Plugin Backend API endpoint allows inlining CSS styles into HTML code and prepare HTML for sending to clients.

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}

To get YOUR_AUTH_TOKEN please take a look at this section.

REQUEST PARAMETERS:

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.
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"}

Roles and access managements

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

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

  • Admin
  • User

You can use these roles while configuring access levels to the folders created in the Image Gallery and in the Library of modules. Pass correct role during authentication (see “Plugin authentication” section) to enable him/her to write data in one or another folder of the Image Gallery or the Library of modules.

Role values:
Role
“PLUGIN_EDITOR_ROLE” param value
User
Skip this parameter in the authentication request.
Administrator
ADMIN.

Custom Components

External Images Library

In case you want to display your own component with external file system for images in the pop-up window instead of Stripo Image Library you can define “externalImagesLibrary” param during plugin initialization as follows:

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

In case you want to display your own component with external list of videos in the pop-up window, which users can pick up while working with Video blocks, you can define “externalVideosLibrary” param during plugin initialization as follows:

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.

File picker for links

In case if you want to add your own control for selecting a file from external file system in the pop-up window to be linked with the existing “Link” control of every basic block, you can define “externalFilesLibrary” param during plugin initialization as follows:

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.
            */
        }
    }
});

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

Sample Code

Using this simple client-side example you can try out Stripo Plugin:

  • Get “PLUGIN_ID” and “SECRET_KEY” values by signing up here and creating a new plugin.
  • Download the client-side code example.
  • Open index.html with code editor.
  • Replace “YOUR_PLUGIN_ID” and “YOUR_SECRET_KEY” with your values.
  • Save the file.
  • Open it in your browser and enjoy the process of email creation.

IMPORTANT: client-side example is created just to play with Stripo Plugin editor and can 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 tell it to anyone. See plugin authentication section to implement authentication correctly.

Appendix A. Helpers

Configuration of AWS S3 storage

To create custom AWS S3 storage do the following:

  1. Get Amazon AWS account.
  2. Create IAM policy as follows:
    {
        "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:GetIpConfiguration",
                    "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:PutIpConfiguration",
                    "s3:GetObjectTorrent",
                    "s3:PutBucketWebsite",
                    "s3:PutBucketRequestPayment",
                    "s3:GetBucketCORS",
                    "s3:GetBucketLocation",
                    "s3:ReplicateDelete",
                    "s3:GetObjectVersion"
                ],
                "Resource": "arn:aws:s3:::backupname/*"
            },
            {
                "Sid": "VisualEditor3",
                "Effect": "Allow",
                "Action": [
                    "s3:ListAllMyBuckets",
                    "s3:HeadBucket",
                    "s3:ListObjects"
                ],
                "Resource": "*"
            }
        ]
    }
  3. Register IAM user for S3 bucket and attach it to just created policy:
  4. Create S3 bucket with necessary custom name and in necessary region:
  5. Choose Static website hosting and index document index.html:
  6. Set Bucket permission policy:
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "PublicReadGetObject",
                "Effect": "Allow",
                "Principal": "*",
                "Action": "s3:GetObject",
                "Resource": "arn:aws:s3:::bucketname/*"
            }
        ]
    }
    
  7. 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;
    }
    
  8. Enter “YOUR_DOMAIN_ADDRESS/content” as “Base Download URL” when configure plugin settings.