- Enhance your customers' experience outside of BEE
- In a nutshell
- Getting the HTML from a message JSON
- Getting additional output formats
- Merging saved rows in existing messages
Enhance your customers' experience outside of BEE
The Content Services API helps you create more value for your users when they are not using the BEE editor.
It exposes a set of services that will help you provide a better experience with how messages and pages are created, updated, and transformed into different formats.
In a nutshell
The Content Services API helps you take care of five, important tasks:
- Retrieving the HTML of an email or page created with BEE, so you can build a custom UX flow for saving messages. With the CSAPI, you can ask BEE for the HTML when you need it.
- Updating the HTML of an email or page created with BEE, without user interaction. Why? For example, the HTML of an email template might need to be updated (e.g. to resolve a newly discovered rendering issue in an email client), and you don’t want to ask your users to open the email with BEE and resave it.
- Generating a thumbnail from the HTML, because thumbnails are always nice to have, for all sorts of reasons 🙂
- Generating a PDF from the HTML, as your users may want to share or print an email or a page, and PDF is great for that.
- Merging shared content (saved rows) into emails and pages that use it (e.g. update 30 emails that use the same footer).
Getting the HTML from a message JSON
This service allows the host application to build a custom workflow that doesn’t rely on the
onSave callback in the editor (list of available callbacks).
Check our reference documentation on how to use the API to get the HTML from a JSON file.
Common use cases
Getting newer, better HTML
The first reason for this API to exist is a common use case: a transactional message was created months ago, it does not need to be edited in the editor, but its HTML code needs to be updated to benefit from fixes or changes that resolve rendering issues.
As you know, HTML for email is a mix of old markup – needed by email clients with a lack of support for standards – and advanced tricks used to take advantage of modern email client capabilities. The result is an environment that changes continuously, driven by the discovery of new techniques and by software updates released by the most popular email clients and browsers.
Having the ability to update the HTML without user interaction in the editor means ensuring that your customers can take advantage of the latest fixes or improvements, even if the messages are transactional notifications created years ago and never edited.
Displaying the preview for incorrectly saved messages
It’s not common, but it may happen that a browser crashes before the user saves a message they are working on. In this scenario, using the
autosave or the
onChange callbacks are enough to prevent any work loss. However, the host application ends up storing a message JSON without the HTML counterpart.
This presents the problem as the two files are out of sync, making things hard for the host application to get a preview, and, therefore, hard for the user to understand if they are looking at the right version of the message.
Using the API the host application can generate an updated HTML from the latest JSON, solving the issue.
Eliminating the need for “Save” buttons
A step further in the use case described above. Some modern applications remove any “Save” button from the UI, autosaving the work every time a change is applied (e.g. Google Docs). Through the
onChange callback, your application can reproduce this behavior, and get the HTML from the saved JSON, when needed.
Getting additional output formats
The API provides some useful services that offer additional message formats, reducing the development effort in the host application.
Generating a PDF file from an HTML
A dedicated endpoint that transforms an HTML into a PDF document and supports the following options:
Landscape and portrait as available values.
Letter, A4, A3, and Full as available values.
While the other values split the message into pages, the Full option returns a single page using 900px as the page width and the proportional height.
PDF is often used in most approval processes, but is also a perfect format for printers.
Check our reference documentation on how to use the API to get a PDF from an HTML file.
Generating image files from an HTML
An endpoint that creates an image from an HTML source supporting the following options:
The image width in pixels
The image height in pixels
When the height is not provided, the API applies a proportional value based on the given width, keeping the image aspect ratio. When the Height value is provided, but not proportional to the given width:
If it’s higher: the proportional value applies
If it’s lower: the image is cropped
Merging saved rows in existing messages
What if a footer (i.e. a saved row) is shared by 10 messages and needs to be updated in all of them?
The Merge method of the Content Services API allows you to update a saved row across multiple messages. More specifically, it allows the host application to update an element in an existing JSON document. This means that, for instance, you could create a feature that takes care of updating existing messages in the background, without any further action by your users.
The Index method of the Content Services API is a complementary method, designed to retrieve the assets which contain saved rows, so that you know which assets need update using the Merge method.
There are many use cases, including:
- updating headers & footers;
- changing the expiration date in a seasonal offer;
- making price changes, link changes, etc. in content that otherwise can be re-used “as is”