Plugin Docs

JavaScript API ​

The new Stripo editor provides a flexible API for interaction with external environments. Access to the API can be obtained through the global StripoEditorApi object.

Accessing the Stripo API:

js
const StripoEditorApi = window.StripoEditorApi

Available APIs:

APIDescription
modulesApi

API for working with modules in Module Editing Mode. A detailed description can be found in the modulesApi) section.

emailMetadataApi API for working with email metadata like email title and prehader. A detailed description can be found in the emailMetadataApi section.
actionsApi API for performing various actions in the editor. A detailed description can be found in the actionsAPI section.
emailMetadataApi API for working with email metadata like email title and prehader. A detailed description can be found in the emailMetadataApi section.
versionHistoryApi API for working with version history. A detailed description can be found in the versionHistoryApi section.
codeEditorApi API for working with the code editor. A detailed description can be found in the codeEditorApi section
editorCopilotApi This API is designed for advanced use cases such as AI-assisted content updates, automated template transformations, and custom logic that operates directly on the template structure rather than raw strings. A detailed description can be found in the editorCopilotApi section
uiApi API for controlling the visibility of UI panels in the Stripo editor. A detailed description can be found in the uiApi section.
devToolsApi API for working with developer tools of the Stripo editor. A detailed description can be found in the devToolsApi section.

Example Usage:

To access the version history API, you can use the following code:

js
const VersionHistoryApi = window.StripoEditorApi.versionHistoryApi

Actions API ​

The actionsApi provides methods for performing various actions within the Stripo email editor. This API allows for dynamic interactions with the editor, enabling users to execute commands such as saving templates, undoing/redoing changes, setting names, and more.

Available Methods:

MethodDescription
getTemplateData The getTemplateData method retrieves the template data, including the HTML, CSS, and additional parameters related to the template.

This is typically done when you want to save the current state of the email template in your database for future use or further processing.
js
const callback = function ({html, css, width, height, utmParams, syncModulesIds}) {
  // Process the template data here
};

window.StripoEditorApi.actionsApi.getTemplateData(callback);
Detailed Explanation:
  • getTemplateData: Method: This is called on the StripoEditorApi object to extract the current HTML and CSS of the email template.
  • Callback Function: The callback function that receives an object containing the following fields:
    • html (String): The HTML content of the template.
    • css (String): The CSS content of the template.
    • width (Number): The width of the template.
    • height (Number): The height of the template.
    • utmParams (Object): UTM parameters applied to the template (if any). More information here.
    • syncModulesIds (Array): A list of synchronized module IDs used within the template.
  • Saving the Template: The extracted HTML and CSS can then be saved to your database or processed further as needed.
Use Cases:
  1. Saving Templates: After users have made changes to their email templates, you can use the getTemplateData method to save the updated template to your database.
getTemplate

Deprecated

 The getTemplate method is used to retrieve the HTML and CSS codes, including the Plugin's internal extra styles and editor markup. This method is essential for extracting the modified template from the editor to save it in your database.

This is typically done when you want to save the current state of the email template in your database for future use or further processing.
js
const callback = function (html, css, width, height) {
  // ...
}

window.StripoEditorApi.actionsApi.getTemplate(callback)
Detailed Explanation:
  • getTemplate Method: This is called on the StripoEditorApi object to extract the current HTML and CSS of the email template.
  • Callback Function: The callback function is defined to handle the returned data. It receives four parameters: HTML, CSS, width and height.
    • HTML: The modified HTML code of the email template.
    • CSS: The modified CSS styles of the email template.
    • Width: The width of the email template.
    • Height: The height of the email template.
  • Saving the Template: The extracted HTML and CSS can then be saved to your database or processed further as needed.
Use Cases:
  1. Saving Templates: After users have made changes to their email templates, you can use the getTemplate method to save the updated template to your database.
compileEmail The compileEmail method is used to retrieve the compiled email template, including its HTML, AMP HTML, and other relevant information. This method is essential for obtaining the final version of the email, which can then be sent out or further processed.
js
const сompileEmailCallback = function(error, html, ampHtml, ampErrors, displayConditions) {
  // ...
};
const utmParameters = {
  utmSource: '',
  utmMedium: '',
  utmCampaign: '',
  utmContent: '',
  utmTerm: '',
  customUtms: [
    {
      'name1': 'val1',
      'name2': 'val2'
    }
  ]
};
window.StripoEditorApi.actionsApi.compileEmail(
  {
    callback: сompileEmailCallback,
    minimize: true,
    utmEntity: utmParameters,
    mergeTags: ['Tag1', 'Tag2'],
    forсeAmp: false,
    resetDataSavedFlag: false,
    disableLineHeightsReplace: true
  }
);
Detailed Explanation:
  • compileEmail Method: This is called on the actionsApi object to compile the email template.
  • Callback Function (compileEmailCallback): The function that handles the response from the compileEmail method. It receives several parameters:
    • error: Any error that occurred during the compilation process.
    • html: The compiled HTML version of the email.
    • ampHtml: The compiled AMP HTML version of the email.
    • ampErrors: Any errors related to the AMP HTML.
    • displayConditions: The display conditions applied to the email.
  • UTM Parameters (utmParameters): An object containing UTM parameters for tracking the email campaign. It includes standard UTM parameters and custom UTM tags.
  • Method Options:
    • minimize: Whether to minimize the HTML and AMP HTML. When set to true, this parameter optimizes the generated HTML and AMP HTML by:
      • Removing line breaks and unnecessary whitespace.
      • Minimizing class names to reduce the overall size of the email.
      • Removing unused CSS classes that do not have corresponding styles.
      This results in a more compact email output, improving loading times and ensuring compatibility with email clients with strict size limitations. By default, minimize is set to false, meaning the output retains its original formatting for readability.
    • mergeTags: An array of merge tags to be used in the email.
    • forceAmp: Whether to force the generation of AMP HTML.
    • resetDataSavedFlag: Whether to reset the data saved flag.
    • disableLineHeightsReplace: Whether to disable the replacement of line heights.
Use Cases:
  1. Finalizing Email Content: After making all necessary changes and customizations to the email template, use compileEmail to obtain the final version for sending.
  2. Email Tracking: Include UTM parameters to track the performance of your email campaigns in analytics platforms.
  3. Handling AMP HTML: Ensure that the AMP HTML version of your email is properly compiled and handle any related errors.
By using the compileEmail method, you can retrieve the fully compiled email template, complete with UTM tracking parameters and display conditions. This allows you to finalize and send your emails with confidence, knowing that all modifications and tracking information are included.
setName The setName method on the actionsApi method is used to set a new name for the email template. This can be useful for organizing and identifying different email templates within your application.

To set a new name for the email template, call the setName method on the actionsApi object of the StripoEditorApi.
js
window.StripoEditorApi.actionsApi.setName('New email name')
Detailed Explanation:
  • Method:setName
  • Description: This method sets a new name for the current email template.
  • Parameter:
    • name (string): The new name you want to assign to the email template.
Use Cases:
  1. Organizing Templates: Assign meaningful names to email templates to easily identify and manage them within your application.
  2. Dynamic Naming: Change the email template name dynamically based on user input or other application logic.
  3. Template Management: Ensure that each email template has a unique and descriptive name, which can be particularly useful when handling multiple templates.
isAllDataSaved To check if all user changes are saved, call the isAllDataSaved method on the actionsApi object of the StripoEditorApi.
js
const isAllDataSaved = window.StripoEditorApi.actionsApi.isAllDataSaved()
Detailed Explanation:
  • Method:isAllDataSaved
  • Description: This method checks if all changes made by the user in the email editor are saved.
  • Return Value:
    • Boolean: Returns true if all changes are saved, false if there are unsaved changes.
Use Cases:
  1. Preventing Data Loss: Before closing the email editor or navigating away, check if there are unsaved changes to prevent data loss.
  2. User Prompts: Prompt the user to save their changes if the method returns false, ensuring that no modifications are lost.
  3. Conditional Logic: Implement conditional logic based on whether all changes are saved, such as enabling or disabling certain actions.
The isAllDataSaved method is a crucial tool for ensuring that all changes made by the user in the email editor are saved before closing or navigating away from the editor. By using this method, you can help prevent data loss and provide a smoother user experience.
save The save method is used to manually save user changes when autosave is disabled. This is useful in scenarios where you want to provide users with control over when their changes are saved, rather than relying on automatic saving.

To manually save user changes, call the save method on the actionsApi object of the StripoEditorApi.
js
const saveCallback = function (error) {
  //...
}
window.StripoEditorApi.actionsApi.save(saveCallback)
Detailed Explanation:
  • Method: save
  • Description: This method saves the current changes made by the user in the email editor. It is particularly useful when autosave is disabled.
  • Parameter:
    • saveCallback (function): Callback that is called then all changes are saved. If there are errors during save, then the error param will contain error details.
Use Cases:
  1. Manual Save Control: Provide users with the ability to manually save their changes, which can be useful in scenarios where users prefer to save their work at specific points rather than relying on autosave.
  2. Autosave Disabled: In situations where autosave is disabled for performance or user preference reasons, the save, method ensures that changes can still be saved manually.
  3. Custom Save Triggers: Implement custom triggers for saving, such as a "Save" button or saving changes before performing other actions like closing the editor or switching templates.
undo The undo method is used to revert the last change made by the user in the email editor. This is useful for providing a seamless editing experience by allowing users to easily correct mistakes or revert changes.

To undo the last user change, call the undo method on the actionsApi object of the StripoEditorApi.
js
window.StripoEditorApi.actionsApi.undo()
Detailed Explanation:
  • Method: undo
  • Description: This method undoes the most recent change made by the user in the email editor.
  • Parameters: None.
Use Cases:
  1. Error Correction: Allow users to quickly revert unintended changes or mistakes.
  2. Editing Flexibility: Enhance the editing experience by providing easy access to undo actions, making it simple to experiment with different designs and revert if needed.
  3. User Control: Give users more control over their editing process, improving overall usability and satisfaction.
redo The redo method is used to reapply the last change that was undone by the user in the email editor. This feature complements the undo functionality by allowing users to restore changes they have previously reverted.

To redo the last undone user change, call the redo method on the actionsApi object of the StripoEditorApi.
js
window.StripoEditorApi.actionsApi.redo()
Detailed Explanation:
  • Method: redo
  • Description: This method undoes the most recent change made by the user in the email editor.
  • Parameters: None.
Use Cases:
  1. Reversing an Undo: Allow users to easily reapply a change that they have previously undone, providing flexibility in the editing process.
  2. Editing Flexibility: Enhance the editing experience by allowing users to navigate back and forth between changes, making it easier to experiment with different designs and options.
  3. User Control: Give users more control over their editing process, improving overall usability and satisfaction.
showAmpErrorsModal The showAmpErrorsModal method is used to display AMP validation errors in the Stripo preview mode if any errors exist in the email template. This feature helps users identify and address AMP-related issues directly within the preview interface.

To display AMP validation errors, call the showAmpErrorsModal method on the actionsApi object of the StripoEditorApi.
js
window.StripoEditorApi.actionsApi.showAmpErrorsModal(
  ampErrors,
  [
    {
      text: 'Preview',
      action: () => {
        console.log('"Preview" button clicked')
      },
    },
  ],
  () => {
    console.log('"Close" button clicked')
  },
  () => {
    console.log('"Fix in Code Editor" button clicked')
  }
)
Detailed Explanation:
  • Method:showAmpErrorsModal
  • Description: This feature helps to notify users about AMP errors and help them fix the bugs.
  • Parameters:
    • ampErrors (array of string): An array of AMP errors received after calling the compileEmail function. This array contains details about each error that needs to be addressed.
    • userSuccessButtons (array of objects with ‘text’ and ‘action’ keys): An array of external buttons that may be displayed in the preview window if there are no validation errors. These buttons provide additional actions for the user when no errors are present.
    • onCancel (function): A callback function that is called when the user closes the preview window. This function allows the editor to handle the user's cancellation action appropriately.
    • onSubmit (function): A callback function that is called when the user clicks the "Fix in Code Editor" button if there are any errors. This button is displayed only if the codeEditorButtonId was provided during the Plugin initialization. The function allows users to directly navigate to the code editor to fix the identified errors.
Use Cases:
  1. Error Identification: Display AMP validation errors to help users quickly identify and address issues in their email templates.
  2. Preview Enhancements: Provide additional functionality in the preview mode, such as external action buttons, to improve the user experience.
activateCustomViewStyles This method toggles the customViewStyles that were injected via the customViewStyles initialisation parameter. It lets you switch your custom CSS on or off without reloading the editor.

Usage: Call activateCustomViewStyles on actionsApi and pass a boolean flag..
js
// Turn custom styles ON
window.StripoEditorApi.actionsApi.activateCustomViewStyles(true);

// Turn custom styles OFF
window.StripoEditorApi.actionsApi.activateCustomViewStyles(false);
Detailed Explanation:
  • Method:activateCustomViewStyles
  • Description: Adds or removes the style tag that contains your customViewStyles rules.
  • Parameters:
    • isActive (boolean): true applies the styles false removes them.
      If the parameter is omitted the call is ignored.
Use Cases:
  1. Brand preview: allow marketers to preview an email with a brand‑specific skin and then revert to the original look for export.
  2. Visual debugging: temporarily highlight certain blocks (e.g., add red outlines) when testing template logic.
  3. A/B design experiments: programmatically switch themes while collecting user‑centric feedback during live sessions.
updateHtmlAndCss The updateHtmlAndCss method is used to reinitialize the current email template in the editor with new HTML and CSS. This method is useful when you need to replace the current template content programmatically and immediately reflect the updated markup and styles in the editor.

To update the current template content, call the updateHtmlAndCss method on the actionsApi object of the StripoEditorApi.
js
const html = '<!DOCTYPE html><html><body><p>Hello world</p></body></html>';
const css = 'p { color: #ff0000; }';

window.StripoEditorApi.actionsApi.updateHtmlAndCss(
  html,
  css,
  () => {
    console.log('Template HTML and CSS were updated');
  }
);
Detailed Explanation:
  • Method:updateHtmlAndCss
  • Description: This method recreates the current editor document using the provided HTML and CSS.
  • Parameters:
    • html (string): The HTML content of the template that should be loaded into the editor. This parameter is used to reinitialize the current template structure with the new markup.
    • css (string): The CSS styles associated with the template. This parameter is applied together with the provided HTML to restore the template appearance in the editor.
    • callback (function): A callback function that is called after the editor finishes applying the new HTML and CSS and triggers the template recreation process.
Use Cases:
  1. Loading External Template Data: Replace the current editor content with HTML and CSS received from your database or another external source.
  2. Applying Programmatic Template Updates: Rebuild the current template after generating or modifying markup and styles outside the editor.

Warning: If more than one person is working on the same email at the same time, calling updateHtmlAndCss replaces the template for every active editor session. The content is updated for everyone, and users in other sessions may lose unsaved work.

Email Metadata API ​

The emailMetadataApi provides methods for accessing and managing the metadata associated with an email template in the Stripo email editor. This API allows users to retrieve and update metadata such as the email title and preheader, facilitating integration with external systems and enhancing the customization of the email editing experience.

Available Methods:

MethodDescription
getTitle The getTitle method is used to retrieve the current title of the email template within the Stripo email editor. This method allows you to access the title that has been set for the email template, which can be useful for displaying or managing the title within your application.

This is typically done when you want to synchronize the title displayed in your application with the title used in the editor.

Sample:
js
const title = window.StripoEditorApi.emailMetadataApi.getTitle();

if (title) {
    console.log('Current email title:', title)
} else {
    console.log('No title is specified for the email in the editor.')
}
Detailed Explanation:
  • getTitle Method: This is called on the StripoEditorApi.emailMetadataApi object to retrieve the current title of the email template.
  • Handling Undefined Title: If the method returns undefined, it means that the email template currently does not have a title set in the editor. This is important to check to avoid unexpected behavior in your application.
Use Cases:
  • Displaying the Title: You can use the getTitle method to display the current email title within your application's UI, ensuring that users see the correct title as they work with the template.
  • Title Synchronization: If your application has a custom field for managing the email template's title, this method is essential for retrieving and displaying the current title in your interface. This ensures that any title changes made within the editor are reflected in your application.
setTitle The setTitle method is used to update the title of the email template within the Stripo email editor. This method allows you to dynamically change the email title, which can be particularly useful when customizing or personalizing templates based on specific criteria or user inputs.

This is typically done when you want to set or update the title of the email to reflect the content or purpose of the template during the editing process.
js
const newTitle = 'Welcome Email'
window.StripoEditorApi.emailMetadataApi.setTitle(newTitle)
Detailed Explanation:
  • setTitle Method: This is called on the StripoEditorApi.emailMetadataApi object to update the title of the email template.
  • Title Parameter: The newTitle parameter represents the new title to be set for the email template. It should be passed as a string.
  • Updating the Title: By calling this method, the title of the email template is immediately updated within the editor interface.
Use Cases:
  • Custom Title Management: If the application owner has a custom field to display and manage the title of the opened email template within the editor, this method becomes crucial. If a customer updates the title through this custom field, it’s essential to call the setTitle method to ensure the template's title is updated within the editor, as this title will be reflected in the <title> tag of the editor.
getHiddenPreHeader The getHiddenPreHeader method is used to retrieve the current hidden preheader of the email template within the Stripo email editor. The hidden preheader is an essential part of an email, as it is often displayed by email clients alongside the subject line, providing additional context to the recipient.

This method is typically used when you want to access the preheader text that is set within the editor, either for display in your application or for synchronization purposes

Sample:
js
const preheader = window.StripoEditorApi.emailMetadataApi.getHiddenPreHeader();

if (preheader) {
    console.log('Current hidden preheader:', preheader)
} else {
    console.log('No hidden preheader is specified for the email in the editor.')
}
Detailed Explanation:
  • getHiddenPreHeader Method: This is called on the StripoEditorApi.emailMetadataApi object to retrieve the current hidden preheader of the email template.
  • Handling Undefined Preheader: If the method returns undefined, it means that the email template currently does not have a hidden preheader set in the editor. Checking for this is crucial to avoid issues when displaying or processing the preheader in your application.
Use Cases:
  • Displaying the Preheader: You can use the getHiddenPreHeader method to display the current hidden preheader within your application's UI, ensuring that users can see the preheader as it will appear to email recipients.
  • Custom Preheader Management: When managing preheaders through your application, it’s important to use the getHiddenPreHeader method to fetch the current preheader before any updates. This ensures that your application always operates with the most up-to-date preheader, which is particularly important for email marketing campaigns.
setHiddenPreHeader The setHiddenPreHeader method is used to update the hidden preheader of the email template within the Stripo email editor.

This method is typically used when you want to set or update the hidden preheader text within the editor to ensure it accurately reflects the content or intent of the email.
js
const newPreheader = "Don't miss out on our latest updates!"
window.StripoEditorApi.emailMetadataApi.setHiddenPreHeader(newPreheader)
Detailed Explanation:
  • setHiddenPreHeader Method: This is called on the StripoEditorApi.emailMetadataApi object to update the hidden preheader of the email template.
  • Preheader Parameter: The newPreheader parameter represents the new hidden preheader text to be set for the email template. It should be passed as a string.
  • Updating the Preheader: By calling this method, the hidden preheader of the email template is immediately updated within the editor, ensuring that the preheader reflects the intended message.
Use Cases:
  • Personalizing Preheaders: You can use the setHiddenPreHeader method to dynamically set the hidden preheader based on user data or specific campaign requirements, enhancing email engagement by providing a relevant preview in the inbox.
  • Custom Preheader Management: If the application owner has a custom field to display and manage the hidden preheader of the opened email template in the editor, this method is crucial. If a customer updates the preheader through this custom field, it’s essential to call the setHiddenPreHeader method to ensure the template's preheader is updated within the editor, providing a seamless experience across different management interfaces.

Accessibility API ​

The accessibilityApi provides methods for controlling the Accessibility Testing Mode in the Stripo email editor. This API allows your application to programmatically start accessibility testing, simulate visual impairments, adjust preview settings, and control the editor interface while testing accessibility.

Accessibility Testing Mode helps users identify potential accessibility issues in email templates by simulating different visual conditions and providing tools for inspecting the email content.

Available Methods:

MethodDescription

openAccessibilityTestingMode

The openAccessibilityTestingMode method switches the editor to Accessibility Testing Mode.
This method only changes the editor mode. The UI controls used to manage accessibility testing (for example preview switching, image visibility, or color vision filters) must be implemented in the host application interface.

Sample

js
window.StripoEditorApi.accessibilityApi.openAccessibilityTestingMode();

Detailed Explanation

  • Custom UI Integration:
    The plugin does not provide built-in UI controls for managing the testing mode. These controls can be implemented by the plugin owner in the host application interface.
  • Testing Environment Activation:
    Once activated, the editor becomes ready to accept additional Accessibility API commands such as applying color filters or switching preview modes.

Use Cases

  • Custom Accessibility Button:
    Add a button in your application header that starts accessibility testing.
  • Accessibility Workflow:
    Trigger accessibility testing as part of a quality assurance workflow before sending the email.

closeAccessibilityTestingMode

The closeAccessibilityTestingMode method exits Accessibility Testing Mode and returns the editor to the regular editing mode.

Sample

js
window.StripoEditorApi.accessibilityApi.closeAccessibilityTestingMode();

Detailed Explanation

  • Return to Editing Mode:
    The editor switches back to the normal editing interface.
  • Accessibility Simulation End:
    Any testing environment previously enabled (such as image hiding or color vision filters) is no longer applied.

Use Cases

  • Custom Exit Button:
    Implement a button that allows users to leave accessibility testing mode.
  • UI State Control:
    Automatically exit testing mode after accessibility checks are completed.

isAccessibilityTestingModeOpen

The isAccessibilityTestingModeOpen method checks whether the editor is currently in Accessibility Testing Mode.

Sample

js
const isOpen = window.StripoEditorApi.accessibilityApi.isAccessibilityTestingModeOpen();

Detailed Explanation

  • Mode Status Detection:
    Returns the current state of the Accessibility Testing Mode.
  • Boolean Response:
    Returns true if testing mode is active and false otherwise.

Use Cases

  • UI State Synchronization:
    Update custom UI controls depending on whether the editor is currently in testing mode.
  • Prevent Duplicate Activation:
    Avoid triggering Accessibility Testing Mode if it is already active.

showImages

The showImages method displays images in the email preview while Accessibility Testing Mode is active.

Sample

js
window.StripoEditorApi.accessibilityApi.showImages();

Detailed Explanation

  • Image Visibility Control:
    This method restores image visibility in the email preview.
  • Accessibility Simulation:
    It is typically used after images were previously hidden during testing.

Use Cases

  • Toggle Image Visibility:
    Implement a UI control that allows users to switch between showing and hiding images.
  • Testing Email Readability:
    Compare how the email appears with images enabled and disabled.

hideImages

The hideImages method hides images in the email preview while Accessibility Testing Mode is active.

Sample

js
window.StripoEditorApi.accessibilityApi.hideImages();

Detailed Explanation

  • Image Suppression:
    All images in the preview are temporarily hidden.
  • Accessibility Testing:
    This allows users to verify whether the email content remains understandable without images.

Use Cases

  • Accessibility Verification:
    Ensure that important information is not conveyed only through images.
  • Alt Text Testing:
    Evaluate how well the email content works in text-only scenarios.

setColorVisionDeficiency

The setColorVisionDeficiency method applies a visual filter that simulates a specific type of color vision deficiency.

Supported values

'protanopia'
'deuteranopia'
'tritanopia'
'achromatopsia'
''

An empty string disables the filter.

Sample

js
window.StripoEditorApi.accessibilityApi.setColorVisionDeficiency('protanopia');

Detailed Explanation

  • Color Vision Simulation:
    The editor applies a filter that mimics how users with specific color vision deficiencies perceive the email.
  • Testing Visual Accessibility:
    This helps ensure that color contrast and visual hierarchy remain understandable.

Use Cases

  • Color Accessibility Testing:
    Verify that text and interactive elements remain distinguishable.
  • Inclusive Design Validation:
    Improve accessibility for users with color blindness.

getColorVisionDeficiency

The getColorVisionDeficiency method returns the currently applied color vision deficiency filter.

Sample

js
const filter = window.StripoEditorApi.accessibilityApi.getColorVisionDeficiency();

Detailed Explanation

  • Filter State Retrieval:
    Returns the currently active color vision simulation filter.
  • Possible Values:
    'Protanopia', 'deuteranopia', 'tritanopia', 'achromatopsia', ''

Use Cases

  • UI Synchronization:
    Update custom UI controls based on the currently applied accessibility filter.
  • Testing State Tracking:
    Ensure that the correct filter is applied during accessibility testing.

switchToDesktopPreview

The switchToDesktopPreview method switches the email preview to the desktop layout while Accessibility Testing Mode is active.

Sample

js
window.StripoEditorApi.accessibilityApi.switchToDesktopPreview();

Detailed Explanation

  • Preview Mode Change:
    Displays the desktop version of the email template.
  • Accessibility Evaluation:
    Helps evaluate layout accessibility on larger screens.

Use Cases

  • Responsive Accessibility Testing:
    Compare accessibility between desktop and mobile views.

switchToMobilePreview

The switchToMobilePreview method switches the email preview to the mobile layout while Accessibility Testing Mode is active.

Sample

js
window.StripoEditorApi.accessibilityApi.switchToMobilePreview();

Detailed Explanation

  • Mobile Rendering:
    Displays the mobile layout of the email template.
  • Accessibility Testing:
    Allows checking readability on smaller screens.

Use Cases

  • Mobile Accessibility Checks
  • Responsive Design Validation

emitToggleCodeEditor

The emitToggleCodeEditor method opens or closes the Code Editor while Accessibility Testing Mode is active.

Sample

js
window.StripoEditorApi.accessibilityApi.emitToggleCodeEditor();

Detailed Explanation

  • Code Editor Toggle:
    This method toggles the visibility of the Code Editor panel.
  • Template Inspection:
    Developers can inspect or adjust the HTML structure while performing accessibility testing.

Use Cases

  • Advanced Template Review
  • Debugging Accessibility Issues

URL Validation API ​

The urlLinkValidationApi provides methods for controlling the URL Validation Mode in the Stripo email editor. This API allows your application to programmatically start URL validation, switch the preview layout while the mode is active, and run the check from code.

URL Validation Mode helps users find broken, unsafe, or suspicious links, image sources, and anchors before an email is sent.

Available Methods:

MethodDescription

openUrlLinkValidationMode

This method switches the editor to URL Validation Mode and starts the check. The UI controls used to enter and leave the mode must be implemented in the host application interface. The method does nothing if the current user has no urlValidation.read permission.

Sample

js
window.StripoEditorApi.urlLinkValidationApi.openUrlLinkValidationMode();

Detailed Explanation

  • Mode Activation:
    The code editor is closed, the selected element is deselected, and the results panel opens with the check in progress.
  • Permission Check:
    The call is ignored when urlValidation.read is false.

Use Cases

  • Custom "Check links" Button:
    Add a button in your application header that starts URL validation.
  • Pre-send QA:
    Trigger URL validation as part of a quality assurance workflow before sending the email.

closeUrlLinkValidationMode

This method exits URL Validation Mode and returns the editor to the regular editing mode.

Sample

js
window.StripoEditorApi.urlLinkValidationApi.closeUrlLinkValidationMode();

Detailed Explanation

  • Return to Editing Mode:
    The results panel is closed and the regular settings panel is shown again.
  • Ignored Findings:
    Findings marked as ignored are kept only for the current editor session.

Use Cases

  • Custom Exit Button:
    Implement a "Back to editor" button in your header.

isUrlLinkValidationModeOpen

This method checks whether the editor is currently in URL Validation Mode.

Sample

js
const isOpen = window.StripoEditorApi.urlLinkValidationApi.isUrlLinkValidationModeOpen();

Detailed Explanation

  • Boolean Response:
    Returns true if the mode is active and false otherwise.

Use Cases

  • UI State Synchronization:
    Highlight your custom button while the mode is active.
  • Prevent Duplicate Activation:
    Avoid starting the mode if it is already open.

switchToDesktopPreview

This method switches the email preview to the desktop layout while URL Validation Mode is active. The call is ignored outside the mode.

Sample

js
window.StripoEditorApi.urlLinkValidationApi.switchToDesktopPreview();

Use Cases

  • Responsive Review:
    Let users inspect where a flagged link is placed in the desktop version.

switchToMobilePreview

The switchToMobilePreview method switches the email preview to the mobile layout while URL Validation Mode is active. The call is ignored outside the mode.

Sample

js
window.StripoEditorApi.urlLinkValidationApi.switchToMobilePreview();

Use Cases

  • Mobile Review:
    Check links that are shown only in the mobile version of the email.

validate

The validate method compiles the current email, validates all links, image sources, and anchors, sends the links that passed the format check to the Stripo URL validation service, and returns the combined result as an RxJS Observable. It does not open the mode or change the UI.

Sample

js
window.StripoEditorApi.urlLinkValidationApi.validate().subscribe(result => {
  const failed = [...result.links, ...result.images, ...result.anchors, ...result.unidentified]
    .filter(item => item.status === 'Error');
  console.log(`Failed: ${failed.length}`, failed);
  if (result.validationFailed) {
    console.warn('The check could not be completed');
  }
});

Detailed Explanation

  • Result Structure:
    links (HTTP/HTTPS/FTP links), images (image src URLs), anchors (#name links), and unidentified (empty href, mailto:/tel:/other protocol links, merge-tag links, and values that cannot be classified). Each item contains attribute (href | src), tagName, value, category, status (Passed | Error), an optional issue message, nodeId, and codeSnippet
  • Backend Payload:
    backendPayload.links and backendPayload.images list the URLs that were sent to the Stripo URL validation service (only the ones that passed the format check).
  • Failure Flag:
    validationFailed: true means the compilation or the server call failed; the arrays are then empty.
  • Asynchronous Result:
    The method returns an RxJS Observable, not a value. Use subscribe, or wrap it in a Promise:
    js
    const result = await new Promise(resolve =>
window.StripoEditorApi.urlLinkValidationApi.validate().subscribe(resolve));

Use Cases

  • Custom Gate Before Sending:
    Block the "Send" action in your application while the email still has failed links.
  • Custom Reporting:
    Build your own report or notification from the results.

validateHtml

The validateHtml method synchronously runs only the client-side format checks (link format, protocols, anchors, merge tags) on the HTML string you pass and returns the same result structure as validate. It does not compile the email, does not call the URL validation service, and does not check whether the links are reachable.

Sample

js
const result = window.StripoEditorApi.urlLinkValidationApi.validateHtml(`
  <a href="https://example.com">Valid</a>
  <a href="not-a-url">Broken</a>
  <img src="invalid-image">
`);
console.table([...result.links, ...result.images, ...result.unidentified]
  .map(({category, value, status, issue}) => ({category, value, status, issue})));

Use Cases

  • Quick Offline Check:
    Validate a saved HTML version of the email without compiling it again.

Version History API ​

The versionHistoryApi provides methods for managing the version history of email templates in the Stripo editor. This API allows users to track changes, undo or redo actions, and restore previous versions of an email template.

Please be advised, that option can be activated or deactivated within the plugin configuration page in your Stripo account, on the Server Settings tab. If the option is disabled, the Version History feature will not be shown or function for any users of the plugin.

If you want to customize who can see and use the Version History feature, you can manage permissions individually using the Stripo User Permissions API.

Version annotations: tags and names. Every saved version (patch) of an email can carry annotations that your integration manages through this API:

  • Tags — up to 20 labels per version, each 1–60 characters. Tags are case-insensitive: adding a duplicate tag is a successful no-op. The same tag can be attached to many versions.
  • Name — a single label of 1–60 characters. A version can have only one name, and a name is unique within the email: assigning it to another version releases it from the previous one.

Annotation methods work with already saved versions only — they never trigger actionsApi.save and do not touch unsaved local changes. Reading methods require the versionHistory.read permission; modifying methods require versionHistory.write. If the Version History option is disabled in your Plugin settings, every method below fails with the VERSION_HISTORY_NOT_ENABLED error without sending a request.

Available Methods:

ParameterDescription
openVersionHistory The openVersionHistory method is used to open the version history of the email template within the Stripo editor. This method allows users to view, manage, and restore previous versions of their email templates.

To open the version history, call the openVersionHistory method on the versionHistoryApi object of the StripoEditorApi. You need to provide two callback functions: one to handle state changes and another to handle when the version history is closed.
js
const onStateChanged = function (state) {
  const prevPatch = state.previousPatch
  const currentPatch = state.currentPatch
  const nextPatch = state.nextPatch
  const currentPatchId = currentPatch.id
  const currentPatchDate = currentPatch.date
  const currentPatchDescription = currentPatch.description
  const currentPatchAuthorId = currentPatch.authorId
  const currentPatchAuthorName = currentPatch.authorName
}
const onVersionHistoryClosed = function () {}
window.StripoEditorApi.versionHistoryApi.openVersionHistory(onStateChanged, onVersionHistoryClosed)
Detailed Explanation:
  • Method:openVersionHistory
  • Description: Opens the version history for the email template, allowing users to view and manage previous versions.
  • Parameters:
    • onStateChanged (function): Callback function that handles state changes in the version history.
    • onVersionHistoryClosed (function): Callback function that handles the event when the version history is closed.
Callback Functions:
  1. onStateChanged: This function is triggered whenever there is a state change in the version history. It provides details about the previous, current, and next patches
    • Parameters:
      • state: An object containing the state of the version history.
        • previousPatch: Information about the previous version.
        • currentPatch: Information about the current version.
        • nextPatch: Information about the next version (if any).
  2. onVersionHistoryClosed (function): This function is triggered when the version history is closed.
Use Cases:
  1. Saving Templates: Allows users to review changes made to the email template over time, providing a detailed history of edits.
  2. Change Management: Facilitates better change management by providing visibility into who made changes and when.
closeVersionHistory The closeVersionHistory method is used to close the version history panel within the Stripo email editor. This method is useful for exiting the version history view and returning to the main editing interface.

To close the version history, call the closeVersionHistory method on the versionHistoryApi object of the StripoEditorApi.
js
window.StripoEditorApi.versionHistoryApi.closeVersionHistory()
Detailed Explanation:
  • Method:closeVersionHistory
  • Description: Closes the version history panel, returning the user to the main editing interface.
  • Parameters: None.
Use Cases:
  1. Exit Version History: Allow users to exit the version history view and return to the main editor after reviewing or restoring a previous version.
  2. UI Navigation: Simplify the user interface by providing a clear way to close the version history panel.
switchToMobilePreview The switchToMobilePreview method is used to switch the email editor to mobile preview mode within the Stripo email editor. This allows users to see how their email template will appear on mobile devices.

To switch to mobile preview mode, call the switchToMobilePreview method on the versionHistoryApi object of the StripoEditorApi.
js
window.StripoEditorApi.versionHistoryApi.switchToMobilePreview()
Detailed Explanation:
  • Method:switchToMobilePreview
  • Description: Switches the email editor to mobile preview mode, allowing users to view how their email template will look on mobile devices.
  • Parameters: None.
Use Cases:
  1. Mobile Optimization: Ensure that the email template looks good and functions correctly on mobile devices by previewing it in mobile mode.
  2. Responsive Design: Check the responsiveness of the email design and make necessary adjustments to improve mobile user experience.
  3. Quality Assurance: Perform quality checks to ensure that all elements of the email template are displayed correctly on mobile devices.
switchToDesktopPreview The switchToDesktopPreview method is used to switch the email editor to desktop preview mode within the Stripo email editor. This allows users to see how their email template will appear on desktop devices.

To switch to desktop preview mode, call the switchToDesktopPreview method on the versionHistoryApi object of the StripoEditorApi.
js
window.StripoEditorApi.versionHistoryApi.switchToDesktopPreview()
Detailed Explanation:
  • Method:switchToDesktopPreview
  • Description: Switches the email editor to desktop preview mode, allowing users to view how their email template will look on desktop devices.
  • Parameters: None.
Use Cases:
  1. Desktop Optimization: Ensure that the email template looks good and functions correctly on desktop devices by previewing it in desktop mode.
  2. Responsive Design: Check the responsiveness of the email design and make necessary adjustments to improve desktop user experience.
  3. Quality Assurance: Perform quality checks to ensure that all elements of the email template are displayed correctly on desktop devices.
previewVersion The previewVersion method is used to update the email preview to a specific version from the version history. This allows users to view how the email looked at a particular point in time.

To update the preview to a specific version, call the previewVersion method on the versionHistoryApi object of the StripoEditorApi, passing the version ID and a callback function to handle any errors.
js
const prevPatch = ...;
window.StripoEditorApi.versionHistoryApi.previewVersion(prevPatch.id,  function(error) {
  // handle error
});
Detailed Explanation:
  • Method:previewVersion
  • Description: Updates the email preview to the specified version from the version history.
  • Parameters:
    • versionId (string): The ID of the version to preview.
    • callback (function): A callback function that handles any errors encountered during the preview update.
Use Cases:
  1. Review Past Versions: Allows users to review how the email looked at a specific version, which can be helpful for understanding changes over time.
  2. Quality Assurance: Ensure that changes made to the email template did not introduce any issues by comparing different versions.
  3. Decision Making: Help users decide if they want to revert to a previous version by providing a visual comparison.
restoreVersion The restoreVersion method is used to restore the email to a specific version from the version history and then close the version history panel. This allows users to revert their email template to a previous state easily.

To restore the email to a specific version, call the restoreVersion method on the versionHistoryApi object of the StripoEditorApi, passing the version ID, a success callback, and an error callback.
js
const prevPatch = ...;
window.StripoEditorApi.versionHistoryApi.restoreVersion(prevPatch.id,
function() {
  // do something on success
},
function(error) {
  // handle error
});
Detailed Explanation:
  • Method:restoreVersion
  • Description: Restores the email to the specified version from the version history and closes the version history panel.
  • Parameters:
    • versionId (string): The ID of the version to restore.
    • successCallback (function): A callback function that is executed on successful restoration.
    • errorCallback (function): A callback function that handles any errors encountered during the restoration process.
Use Cases:
  1. Revert to Previous State: Allows users to revert their email template to a previous state if recent changes are not satisfactory.
  2. Error Correction: Quickly correct errors by restoring a known good version of the email template.
  3. Version Management: Manage email versions effectively by providing the ability to easily restore and close the version history.
getLastSavedPatchId Returns the ID of the most recent saved version (patch) of the email. Use it as the starting point for annotation chains — for example, tag or name the version you have just saved, or open it in Version History.

The method is available right afte after successful editor connection and does not require the Version History panel to be open. Unsaved local changes are not taken into account.
js
window.StripoEditorApi.versionHistoryApi.getLastSavedPatchId(
 patchId => console.log('last saved patch:', patchId),
 error => console.error(error)
)
Parameters:
  • onSuccess (function): receives the patchId string.
  • onFailed (function): receives the error. LAST_SAVED_PATCH_NOT_FOUND is returned when the email has no saved versions yet;
    VERSION_HISTORY_NOT_ENABLED when the Version History option is disabled.
Requires the versionHistory.read permission.
addTag Adds a tag to a specific version or to the latest saved version of the email.

If patchId is provided, the tag is added to that version. If it is omitted, the backend atomically resolves the latest saved version and tags it — safe to call right after a save, even during co-editing.
js
window.StripoEditorApi.versionHistoryApi.addTag(
 { tag: 'approved', patchId: '869f6f19-9fbd-4e4b-9e61-0ff74b5fa4f9' }, // patchId is optional
 result => console.log(result), // { patchId, tag, alreadyExisted }
 error => console.error(error)
)
Behavior notes:
  • The tag value is trimmed; allowed length is 1–60 characters.
  • A version can hold up to 20 tags; existing tags are never removed or overwritten by this call.
  • Tags are case-insensitive: adding an existing tag succeeds without creating a duplicate and returns alreadyExisted: true
  • The call never triggers actionsApi.save and works with saved versions only.
Requires the versionHistory.write permission. Fails with VERSION_HISTORY_NOT_ENABLED when the Version History option is disabled.
setName Sets a name for a specific version or for the latest saved version of the email. Not to be confused with actionsApi.setName, which renames the email itself — this method labels a version in the version history.

If patchId is provided, the name is set for that version. If it is omitted, the backend atomically resolves the latest saved version and names it.
js
window.StripoEditorApi.versionHistoryApi.setName(
 { name: 'release 2.678', patchId: '869f6f19-9fbd-4e4b-9e61-0ff74b5fa4f9' }, // patchId is optional
 result => console.log(result), // { patchId, name }
 error => console.error(error)
)
Behavior notes:
  • The value is trimmed; allowed length is 1–60 characters.
  • A version can have only one name — a new value replaces the previous one. Setting the same name again is a successful idempotent operation.
  • Changing the name does not affect the version's tags.
  • The call never triggers actionsApi.save and works with saved versions only.
Requires the versionHistory.write permission. Fails with VERSION_HISTORY_NOT_ENABLED when the Version History option is disabled.

getTags

Returns the tags of the email's versions as a map, where each tag points to the array of version IDs it is attached to.

js
window.StripoEditorApi.versionHistoryApi.getTags(
 { tagsCount: 10 }, // max number of tags per request
 result => console.log(result), // { tags: { approved: ['patch1', 'patch2'] }, totalTagsCount: 1, lastTag: '...' }
 error => console.error(error)
)

Pagination:

  • request the first page with tagsCount only. If the response contains lastTag, there are more results — pass it together with tagsCount to fetch the next page. lastTag is the real last value of the page (an exclusive boundary); when it is absent, you have reached the end.
  • totalTagsCount always contains the total number of tags.

Requires the versionHistory.read permission. Fails with VERSION_HISTORY_NOT_ENABLED when the Version History option is disabled.

getNames

Returns the names of the email's versions as a map. A name is unique within the email, so each entry points to a single version ID.

js
window.StripoEditorApi.versionHistoryApi.getNames(
 { namesCount: 10 }, // max number of names per request
 result => console.log(result), // { names: { 'release 2.678': 'patch678' }, totalNamesCount: 1, lastName: '...' }
 error => console.error(error)
)

Pagination:

works the same way as in getTags — request the first page with namesCount, continue with the returned lastName boundary until it is no longer present in the response.

Requires the versionHistory.read permission. Fails with VERSION_HISTORY_NOT_ENABLED when the Version History option is disabled.

movePatchName

Moves an existing name from one version to another — for example, to shift a production label to a newer version.

js
window.StripoEditorApi.versionHistoryApi.movePatchName(
 '7caee114-c7a9-4801-bddd-cbae5cbcd568', // sourcePatchId -- the version that currently has the name
 '869f6f19-9fbd-4e4b-9e61-0ff74b5fa4f9', // targetPatchId -- the version to receive it
 result => console.log(result), // { name, sourcePatchId, targetPatchId, replacedName? }
 error => console.error(error)
)

Behavior notes:

  • After a successful call, the source version no longer has a name and the target version carries it.
  • If the target version already had a different name, it is overwritten and returned in the result as replacedName.
  • The call fails if the source version has no name or if source and target are the same version.
  • The operation does not open the Version History panel and never triggers a save.

Requires the versionHistory.write permission. Fails with VERSION_HISTORY_NOT_ENABLED when the Version History option is disabled.

openVersionHistoryByPatchId

Opens Version History directly on a specific version. The editor loads the required data for the given patchId, rebuilds that version, shows its preview, expands the group the version belongs to, scrolls the panel to it, and highlights its card as selected. Combine it with getNames / getTags / getLastSavedPatchId to open a version found by its annotation without making the user search the history manually.

js
window.StripoEditorApi.versionHistoryApi.openVersionHistoryByPatchId(
 'c6cb4e93-35c2-4b66-b542-1df30bdb976a', // patchId
 state => console.log('state:', state),  // optional, same shape as in openVersionHistory
 () => console.log('history closed'),    // optional
 error => console.error(error)           // optional
)

Behavior notes:

  • The first onStateChanged call fires when the target preview is ready, with state.currentPatch.id equal to the requested patchId; afterwards the callback behaves exactly as in openVersionHistory.
  • If Version History is already open, the call switches it to the new target version without closing the panel.
  • If several calls run concurrently, the latest one wins.
  • If the version does not exist, belongs to another email, or is not available to the user, onFailed receives VERSION_HISTORY_PATCH_NOT_FOUND — the method never falls back to the latest version.
  • The regular openVersionHistory keeps working as before and opens the latest version.

Requires the versionHistory.read permission and an active connection. Fails with VERSION_HISTORY_NOT_ENABLED when the Version History option is disabled.

Restore a Version as a New Email ​

The Restore as new action creates a new email from the selected version without modifying the currently open email.

Unlike restoreVersion, this action does not restore content into the current email. The editor only passes the selected patchID to your application through the historySaveAsNew callback. Your application is responsible for creating a new email ID and copying the selected version to it.

The action is available when:

  • the Version History feature is enabled;
  • the user has the versionHistory.write permission;
  • the editor is online;
  • the historySaveAsNew callback is provided during editor initialization.

If the callback is not provided, the action is hidden. The action is also disabled when the editor is offline or the user does not have write permission.

To obtain patch IDs programmatically (outside the Version History UI), use the Version History API methods described above — for example, getLastSavedPatchId, getNames, or getTags.

Configure the callback ​

Add the historySaveAsNew callback to the editor initialization settings:

js
{
  historySaveAsNew: async function({ patchID }, callback) {
    try {
      const response = await fetch('/api/emails/restore-as-new', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          sourceId: currentEmailId,
          patchId: patchID
        })
      });

      if (!response.ok) {
        throw new Error('Failed to restore the version as a new email');
      }

      const result = await response.json();

      callback(null);

      // Optional: open the newly created email.
      // openEmail(result.destinationId);
    } catch (error) {
      callback(
        error instanceof Error
          ? error.message
          : 'Failed to restore the version as a new email'
      );
    }
  }
}

Callback signature:

js
historySaveAsNew?: (
  payload: { patchID: string },
  callback: (error: string | null) => void
) => void;

Parameters:

  • patchID — the UUID of the version selected by the user;
  • callback(null) — reports successful completion to the editor;
  • callback(errorMessage) — reports an error to the editor.

The editor displays a success or error notification after the callback is completed. It does not create a new email, modify the current model, or switch the user to another email.

Do not call the Stripo Email Model Clone API directly from the browser. The request requires an API-role authentication token and must be performed by your backend.

Copy the selected version on your backend ​

Your backend should:

  1. Create a new email in your system and assign it a unique email ID. This ID becomes destinationId.
  2. Call POST /coediting/v1/email/copy with sourceId, destinationId, and the received patchId.
  3. Return destinationId to your frontend.

Example request:

bash
curl https://plugins.stripo.email/coediting/v1/email/copy \
  --request POST \
  --header 'ES-PLUGIN-AUTH: Bearer YOUR_API_ROLE_TOKEN' \
  --header 'ES-PLUGIN-UI-DATA: {"emailId":"SOURCE_EMAIL_ID"}' \
  --header 'Content-Type: application/json' \
  --data '{
    "sourceId": "SOURCE_EMAIL_ID",
    "destinationId": "NEW_EMAIL_ID",
    "patchId": "SELECTED_PATCH_UUID"
  }'

Example response:

json
{
  "destinationId": "NEW_EMAIL_ID"
}

When patchId is provided, Stripo creates the destination model using the content of the selected historical version. When it is omitted or set to null, the current state of the source model is copied.

The source email and its version history remain unchanged.

Retrieve HTML and CSS ​

Creating the model does not trigger an Email Change Notification webhook for the new email. If your application stores email content in its own database, retrieve it explicitly after copying:

bash
curl https://plugins.stripo.email/coediting/v1/email/html-css \
  --request GET \
  --header 'ES-PLUGIN-AUTH: Bearer YOUR_API_ROLE_TOKEN' \
  --header 'ES-PLUGIN-UI-DATA: {"emailId":"NEW_EMAIL_ID"}'

Store the returned HTML and CSS under the new email in your system.

Open the new email ​

By default, we recommend keeping the user in the currently opened email after the copy is created.

If your application needs to open a new email:

  1. Make sure all current changes are saved by checking StripoEditorApi.actionsApi.isAllDataSaved().
  2. Call removeEditor().
  3. Initialize the editor again with metadata.emailId set to the new email ID.

Do not use forceRecreate for this flow.

Limitations and behavior ​

  • destinationId must not already exist. Otherwise, the API returns 400 Bad Request.
  • sourceId and destinationId must not exceed 100 characters.
  • patchId must be a valid UUID identifying a visible, non-technical version of the source email.
  • An invalid, unknown, foreign, hidden, or technical patchId returns 400 Bad Request. The destination model is not partially created.
  • The initial version ID 00000000-0000-0000-0000-000000000001 is supported.
  • The new model starts with an empty version history.
  • Timers contained in the selected version are cloned for the new email.
  • If the source email has a Template Theme, the destination uses the source email’s current theme binding and the latest version of that theme. The historical theme state from the selected patch is not restored.
  • Each new email ID counts toward the plugin’s unique email quota.

Code Editor API ​

The codeEditorApi provides methods for interacting with the code editor within the Stripo email editor. This API allows users to open the code editor, close the code editor, and retrieve the current state of the code editor panel.

ParameterDescription
getCodeEditorState The getCodeEditorState method is used to retrieve the current state of the code editor panel within the Stripo email editor. This method provides detailed information about the code editor's state, including whether it is open, and the status of various panels and dimensions.

To retrieve the current state of the code editor panel, call the getCodeEditorState method on the codeEditorApi object of the StripoEditorApi.
js
const state = window.StripoEditorApi.codeEditorApi.getCodeEditorState()
/*
{
  "isOpen": false,
  "isDefaultCSSOpen":true,
  "isCustomCSSOpen": false,
  "containerHeight": 80,
  "defaultCSSPanelWidth": 100,
  "customCSSPanelWidth": 100
}
*/
Detailed Explanation:
  • Method:getCodeEditorState
  • Description: Retrieves the current state of the code editor panel.
  • Return Value: An object containing the current state of the code editor panel with the following properties:
    • isOpen (boolean): Indicates whether the code editor is open.
    • isDefaultCSSOpen (boolean): Indicates whether the default CSS section is open.
    • isCustomCSSOpen (boolean): Indicates whether the custom CSS section is open.
    • containerHeight (number): The height of the code editor container in pixels.
    • defaultCSSPanelWidth (number): The width of the default CSS section in pixels.
    • customCSSPanelWidth (number): The width of the custom CSS section in pixels.
Use Cases:
  1. State Monitoring: Monitor the state of the code editor to make decisions based on whether it is open or closed and the status of its panels.
  2. UI Adjustments: Adjust other parts of your application's UI based on the dimensions and state of the code editor panel.
  3. Conditional Logic: Implement conditional logic that depends on the state of the code editor, such as enabling or disabling certain features.
openCodeEditor The openCodeEditor method is used to open the code editor within the Stripo email editor. This method allows users to start editing the HTML and CSS of their email templates directly.

To open the code editor, call the openCodeEditor method on the codeEditorApi object of the StripoEditorApi.
js
window.StripoEditorApi.codeEditorApi.openCodeEditor()
Detailed Explanation:
  • Method:openCodeEditor
  • Description: Opens the code editor, allowing users to edit the HTML and CSS of their email templates.
  • Parameters: None.
Use Cases:
  1. Direct Code Editing: Allow users to open the code editor to make direct changes to the HTML and CSS of their email template.
  2. Advanced Customization: Provide advanced users with the ability to customize the email template beyond what is possible with the visual editor.
  3. Debugging: Enable users to debug and fix any issues in the HTML or CSS code of their email template.
closeCodeEditor The closeCodeEditor method is used to close the code editor within the Stripo email editor. This method allows users to exit the code editing mode and return to the main visual editing interface.

To close the code editor, call the closeCodeEditor method on the codeEditorApi object of the StripoEditorApi.
js
window.StripoEditorApi.codeEditorApi.closeCodeEditor()
Detailed Explanation:
  • Method:closeCodeEditor
  • Description: Closes the code editor, returning the user to the main visual editing interface.
  • Parameters: None.
Use Cases:
  1. Exit Code Editing: Allow users to close the code editor after making changes and return to the visual editor for further adjustments.
  2. Simplify UI: Provide a clear way for users to exit the code editor, ensuring a smooth transition back to the visual editing interface.
  3. User Workflow: Enhance the user workflow by allowing them to toggle between code editing and visual editing as needed.

Editor Copilot API ​

The Editor Copilot API allows you to work with the email template markup (HTML and CSS) in a structured and safe way.

Instead of modifying raw HTML or CSS strings, this API exposes AST-like nodes and modifiers that are already used internally by Stripo extensions.

The API is available via:

js
window.StripoEditorApi.editorCopilotApi
ParameterDescription
getTemplateModifier() Returns a TemplateModifier instance that can be used to analyze and modify the email template structure.

This modifier provides high-level operations for working with template markup and is commonly used to implement intelligent or automated template updates.
js
const templateModifier = window.StripoEditorApi.editorCopilotApi.getTemplateModifier();
Returns:
  • TemplateModifier — an object that provides high-level operations for modifying template markup.

See full reference here.

Typical use cases:
  • Apply changes to the template structure.
  • Replace or regenerate content blocks programmatically.
  • Perform controlled transformations without breaking editor semantics.
getDocumentRootHtmlNode()
js
const htmlRoot = window.StripoEditorApi.editorCopilotApi.getDocumentRootHtmlNode();
Returns:
  • HtmlNode — the root node of the document HTML tree.

See full reference here.

Typical use cases:
  • Traverse the template structure.
  • Inspect or modify specific HTML elements.
  • Implement intelligent content updates based on document context.
getDocumentRootCssNode() Returns the root CSS node of the email document.

This node provides structured access to all CSS rules defined in the template.
js
const cssRoot = window.StripoEditorApi.editorCopilotApi.getDocumentRootCssNode();
Returns:
  • CssNode — the root node of the document CSS tree.

See full reference here.

Typical use cases:
  • Analyze or update template styles.
  • Apply automated styling changes.

UI API ​

The uiApi interface provides methods to control the visibility of UI panels in the Stripo plugin.

ParameterDescription
setSettingsPanelVisible The setSettingsPanelVisible method is used to show or hide the settings panel in the Stripo editor.

To control the visibility of the settings panel, call the setSettingsPanelVisible method on the uiApi object of the StripoEditorApi.
js
window.StripoEditorApi.uiApi.setSettingsPanelVisible(false); // Hides the settings panel
Detailed Explanation:
  • Method:setSettingsPanelVisible
  • Description: Shows or hides the settings panel in the Stripo editor.
  • Parameters:
    • isVisible (boolean) – A flag to determine the visibility state of the settings panel.
      • true – The settings panel is visible.
      • false – The settings panel is hidden.
Use Cases:
  1. UI Customization: Allows users to customize the editor layout by hiding the settings panel when not needed.
  2. Focus Mode: Helps users concentrate on email content by reducing distractions from UI elements.
setBlocksPanelVisible The setBlocksPanelVisible method is used to show or hide the blocks panel in the Stripo editor.

To control the visibility of the blocks panel, call the setBlocksPanelVisible method on the uiApi object of the StripoEditorApi.
js
window.StripoEditorApi.uiApi.setBlocksPanelVisible(false); // Hides the blocks panel
Detailed Explanation:
  • Method: setBlocksPanelVisible
  • Description: Shows or hides the blocks panel in the Stripo editor.
  • Parameters:
    • isVisible (boolean) – A flag to determine the visibility state of the blocks panel.
      • true – The blocks panel is visible.
      • false – The blocks panel is hidden.
Use Cases:
  1. UI Customization: Enables users to tailor the editor layout by hiding the blocks panel when not in use.
  2. Focus Mode: Helps users concentrate on email content by minimizing distractions from additional UI elements.
setActiveGeneralPanelTab Programmatically switches the active tab in the General Settings panel of the editor.

This method allows external applications to open a specific tab in the Settings panel (for example, Styles, Message Settings, Comments , or tabs added by extensions).
The tab switch behaves exactly the same as when a user clicks the tab manually.

If the specified tab does not exist, is hidden, disabled, or cannot be activated in the current editor state, the editor will ignore the request and return an error via callback.

Syntax:
js
window.StripoEditorApi.uiApi.setActiveGeneralPanelTab(tabId, callback);
  • tabId (string, required) — Identifier of the tab that should become active.

    Supported identifiers:
    • "letter" — Message Settings tab
    • "styles" — General Styles tab
    • "comments" — Comments tab
    • extension tab id — identifier from ExtensionGeneralPanelUtils defined by an extension with type: "extensionGeneralTab"
  • callback (function, required) — Function that receives the result of the operation.
Behavior: The method performs the same logic as a user clicking a tab:
  • updates the active tab in the Settings panel;
  • updates the tab header and panel content;
  • triggers internal editor logic including saving the active tab state.
The tab will not be switched in the following cases:
  • the provided tabId does not exist;
  • the tab is hidden or disabled;
  • the editor is opened in module editing mode (editorMode === 'module');
  • the comments tab is requested but is not available for the current user.
Callback result
If the tab switch was successful:
json
{ "status": "success" }
If the tab cannot be activated:
json
{
  "status": "error",
  "code": "TAB_NOT_AVAILABLE",
  "message": "Tab \"{tabId}\" is not available or cannot be activated."
}
Example
Switch to the General Styles tab:
js
window.StripoEditorApi.uiApi.setActiveGeneralPanelTab('styles', function(result) {
 if (result.status === 'success') {
   console.log('Tab switched successfully');
 } else {
   console.error(result.message);
 }
});
Switch to the Comments tab:
js
window.StripoEditorApi.uiApi.setActiveGeneralPanelTab('comments');

getActiveGeneralPanelTab

Returns the identifier of the currently active tab in the General Settings panel of the editor.

This method allows external applications to read the current UI state of the General Panel — for example, to build integrations that react to which tab is active without manually tracking tab switches.

Syntax:

js
const tabId = window.StripoEditorApi.uiApi.getActiveGeneralPanelTab();

Return value (string) — Identifier of the currently active tab.

Possible values:

  • "letter" — Message Settings tab
  • "styles" — General Styles tab
  • "comments" — Comments tab
  • extension tab id — identifier defined by an extension with type: "extensionGeneralTab"

Example:
Read the active tab:

js
const activeTab = window.StripoEditorApi.uiApi.getActiveGeneralPanelTab();
console.log('Active tab:', activeTab); // e.g. 'styles'

Check the active tab before switching:

js
if (activeTab !== 'comments') {
  window.StripoEditorApi.uiApi.setActiveGeneralPanelTab('comments', function(result) {
    if (result.status === 'success') {
      console.log('Switched to Comments tab');
    }
  });
}

Use Cases:

  • Use Cases: UI State Synchronization: Keep your application UI controls in sync with the editor's current General Panel tab.

  • Conditional Logic: Build integrations that react to the currently active tab — for example, showing or hiding application-side controls based on whether the user is in the Styles or Comments tab.

  • Tab Guard: Check the current tab before calling setActiveGeneralPanelTab to avoid redundant tab switches.

Example: Hiding Panels When Opening Code Editor

To automatically hide both the settings panel and the blocks panel when opening the code editor, use the following sample implementation:

js
onCodeEditorVisibilityChanged: function (isCodeEditorVisible) {
  window.StripoEditorApi.uiApi.setSettingsPanelVisible(!isCodeEditorVisible);
  window.StripoEditorApi.uiApi.setBlocksPanelVisible(!isCodeEditorVisible);
}

This ensures that when the code editor is opened, the panels are hidden, and when it is closed, the panels become visible again.

View Options API ​

The viewOptionsApi allows you to dynamically control how the template is displayed inside the editor. You can use it to respond to changes in your own UI — for example, if you allow your users to toggle preview modes, merge tag visibility, or hide/show elements dynamically. See details here.

MethodDescription
setViewOptions Updates the current display settings inside the editor — such as which MIME type is shown, how merge tags are rendered, or whether hidden blocks are visible. Use this method when users interact with your UI controls.

Sample
js
window.StripoEditorApi.viewOptionsApi.setViewOptions(viewOptions)
Parameters:
  • viewOptions — an object with one or more of the following fields:
    • showHiddenElements: boolean — whether hidden blocks should be shown.
    • mimeType: 'html' | 'ampHtml' | 'both' — which version of the email to show.
    • mergeTags: 'raw' | 'label' | 'value' — how merge tags are rendered.
    • displayConditions: array — list of conditions with id, name, and visibility.
Example:
js
window.StripoEditorApi.viewOptionsApi.setViewOptions({
  mimeType: 'html',
  mergeTags: 'label',
  showHiddenElements: false,
  displayConditions: [
    { id: '1234', name: 'VIP Users', visibility: true },
    { id: '5678', name: 'Beta Testers', visibility: false }
  ]
});
Details: You can update just one field or multiple fields at once. If a field is not passed, the previous value remains active. This method does not reinitialize the editor — it updates the preview immediately.

showPinsInEditor

Displays all comment pins on the editor canvas. Pins become visible to users in the editing area, allowing them to see comment annotations attached to document elements.

Note: This method only affects canvas visibility. Pins in the Comments tab panel remain always visible.

Sample:

js
window.StripoEditorApi.viewOptionsApi.showPinsInEditor()

Details: This method shows all comment pins that were previously hidden. The pins remain attached to their respective elements and are now visually displayed. This is useful for switching between editing modes where users need to see or ignore comment annotations.

hidePinsInEditor

Hides all comment pins from the editor canvas view. Pins remain attached to elements but are not visually displayed on the canvas, providing a distraction-free editing experience.

Note: This method only affects canvas visibility. Pins in the Comments tab panel remain always visible.

Sample:

js
window.StripoEditorApi.viewOptionsApi.hidePinsInEditor()

Details: This method hides all currently visible comment pins. The pins are preserved on their elements and can be shown again by calling showPinsInEditor(). This is useful for focused editing or presentation modes where comment annotations should not be visible.

getPinsEditorState

Returns the current visibility state of pins on the editor canvas. Use this method to check whether comment pins are currently shown or hidden on the canvas before toggling visibility.

Note: This method reflects canvas visibility only, not the Comments tab where pins are always visible.

Sample:

js
const areVisible = window.StripoEditorApi.viewOptionsApi.getPinsEditorState()

Parameters:

  • Return value — boolean — true if pins are visible in the editor, false if pins are hidden.

Example:

js
window.StripoEditorApi.viewOptionsApi.getPinsEditorState()
// Returns: true (pins are visible)

// Toggle pin visibility based on current state
const currentState = window.StripoEditorApi.viewOptionsApi.getPinsEditorState()

if (currentState) {
  window.StripoEditorApi.viewOptionsApi.hidePinsInEditor()
} else {
  window.StripoEditorApi.viewOptionsApi.showPinsInEditor()
}

Details: You can call this method to determine the current pin visibility before performing conditional logic. This method does not change the editor state — it only reports the current visibility status. Use it in combination with showPinsInEditor() and hidePinsInEditor() to implement toggle functionality

Comments API ​

Used to manage comments in the editor. Methods allow developers to programmatically trigger comment creation mode and check comment system status.

MethodDescription

addComment

Activates comment creation mode in the editor. The cursor changes to a crosshair, prompting the user to select a document element for adding a comment. Once an element is selected, the comment creation dialog appears with permission checks applied based on the user's role.

Sample:

js
window.StripoEditorApi.commentsApi.addComment()

Behavior. When addComment() is called:

  • Editor enters comment mode with crosshair cursor active.
  • User can click on any document element to attach a comment.
  • Comment dialog opens with selected element context.
  • Permission validation occurs — if user lacks comment creation rights, multilingual error message displays.
  • User can type and submit comment, or cancel the operation.

Error Handling
If the user doesn't have permission to add comments, error messages appear in the user's language through the notifications parameter.

Example:

js
// Trigger comment mode from custom UI button
document.getElementById('addCommentBtn').addEventListener('click', () => {
  window.StripoEditorApi.commentsApi.addComment()
})

// User clicks on an image element → comment dialog opens
// User types comment → comment is saved with element reference

Details: Use this method to create custom "Add Comment" triggers in your application UI. The method respects role-based permissions automatically. If permissions validation fails, the appropriate error message is shown without entering comment mode.

Template Theme Mode API ​

The templateThemeModeApi allows you to dynamically control how the email template is rendered inside the editor canvas — in Light or Dark mode.

You can use this API to synchronize template rendering with your application UI, allow users to toggle between light and dark views, or apply theme changes dynamically without reloading the editor.

See details here.

MethodDescription

setTemplateThemeMode

Updates the template rendering mode inside the editor.

Use this method when users interact with your UI controls (for example, a Light / Dark toggle) and you want to immediately update how the email template is displayed.

Sample

js
StripoEditorApi.templateThemeModeApi.setTemplateThemeMode(templateThemeMode);

Parameters:

  • templateThemeMode — one of the following values:
    • 'LIGHT' — renders the template in light mode.
    • 'DARK' — renders the template in dark mode.

Example:

js
StripoEditorApi.templateThemeModeApi.setTemplateThemeMode('DARK');

Details:

  • The change is applied immediately.
  • The editor is not reinitialized.
  • The email HTML, styles, and export output remain unchanged.

getThemeMode

Returns the currently active template theme mode.

Sample

js
StripoEditorApi.templateThemeModeApi.getThemeMode();

Example

js
const mode =
  StripoEditorApi.templateThemeModeApi.getThemeMode();

console.log(mode); // 'LIGHT' or 'DARK'

Details:

  • This method can be used to synchronize your UI state with the editor.
  • Useful when restoring UI controls or reacting to external state changes.

Modules API ​

The modulesApi provides methods for working with modules when the editor runs in Module Editing Mode entityType: 'module'. It lets your application open the module details dialog programmatically — for example, from a custom "Show module data" button in your interface.

ParameterDescription
openModuleDetailsDialog

The openModuleDetailsDialog method opens the module details dialog, where the module metadata (name, description, category, tags) is displayed and edited. It mirrors the module details panel available in email mode.

Sample:

js
window.StripoEditorApi.modulesApi.openModuleDetailsDialog();

Use Cases:

Custom "Show module data" button: Add a button in your application UI that opens the module details dialog on click. Available in Module Editing Mode: Use this method when the editor is initialized with entityType: 'module'.

Dev Tools API ​

The devToolsApi provides methods for interacting with developer tools of the Stripo editor. This API facilitates the handling of exceptional situations and issues with the editor.

ParameterDescription
dump The dump method is used to create a snapshot of the editor at the time of invocation for further analysis by the Stripo team and bug fixing.

To create a dump, call the dump method on the devToolsApi object of the StripoEditorApi.
js
window.StripoEditorApi.devToolsApi.dump()
Detailed Explanation:
  • Method: dump
  • Description: Creates a snapshot of the editor at the time of invocation.
  • Parameters: None.
Use Cases:
  1. Error handling: Allows users to capture a snapshot of the editor and attach it directly to a support ticket.

© 2026 Stripо.email — Next Generation Email Editor.