Content Services API

  1. Enhance your customers' experience outside of BEE
  2. In a nutshell
  3. Getting the HTML from a message JSON
  4. Getting additional output formats
  5. 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 four, key tasks:

  1. Updating the HTML of a message or page created with BEE, without user interaction. Why? Because the HTML might need to be updated (e.g. to resolve a newly discovered rendering issue), and you don’t want to ask your users to open each one with BEE and resave it.
  2. Generating a thumbnail from the HTML, because thumbnails are always nice to have, for all sorts of reasons 🙂
  3. Generating a PDF from the HTML, because your users may want to share or print a message or a page, and PDF helps to just that.
  4. Merging shared content (saved rows) into messages and pages that use it (e.g. 30 emails that use the same footer).

 

More details

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

Autosaving the message during the editing

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:

Page orientation
Landscape and portrait as available values.

Page size
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:

Width
The image width in pixels

Height
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

Check our reference documentation on how to use the API to get images from an HTML file.

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.

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”
  • etc.