Learn more about how to get started with the Content Services API in the following sections:

A richer content creation experience

Beefree SDK is a complete content design and creation platform for you to build upon. Our objective is to help you create a fantastic content creation experience for your customers inside your software applications.

As this may go beyond the interactions that happen within our email, page, and popup builders, we created an API to offer more assistance. We call it the Content Services API: it exposes a set of services that will help you provide a better experience with how emails, pages, and popups are created, updated, and transformed into different formats.

Overview

The Content Services API (CSAPI) – helps you achieve the following:

• Retrieving the HTML of an email, page or popup created with a Beefree builder, so you can build a custom UX flow for saving messages. With the CSAPI, you can ask the Beefree system for the HTML whenever you need it.

• Updating the HTML of an email, page or popup created with a Beefree builder, 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 the builder and resave it.

• Outputting partial HTML that enables you to reuse code, increase consistency across your templates, and easily maintain your code.

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

• Use Brand Style Management to make template-wide design changes to existing templates quickly and easily.

• Generate plain text versions of emails from JSON templates, ensuring emails look sharp and easy to read on any device.

• Leverage AI to generate SMS, Metadata (Preheader and Subject), or Summary text from JSON templates.

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.

A Few 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:

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 is shared by 10 messages and needs to be updated in all of them? The Synced Rows feature was created precisely to address the scenario of content that is shared across multiple emails, pages, or popups, and it is used in conjunction with the Content Services API.

The Merge method of the Content Services API allows you to update a 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”

• etc.

The Content Services API Reference provides a comprehensive guide to utilizing the Content Services API, which leverages the REST architecture and HTTP protocol for making API calls. This reference document outlines the available collections, including /message, /page, /popup, /amp, /template, and /ai, detailing the resources for each collection. For every resource, this document includes its description, parameters, and example responses and requests.

API Key

To use the Content Services API you will first need to obtain a your API Key from the Beefree SDK Console.

To obtain an API Key, take the following steps:

1. Log into the Beefree SDK Console

2. Locate the application that you wish to work with, and click on Details

3. Locate the Content Services API section and click Create New API Key

4. Acknowledge the message that reminds you that if you exceed the number of API calls included in your plan, you may be charged for overages and click Create Key

Your API key will appear under the Content services API section of your application details.

The Content Services API uses API Keys to authenticate requests for resources. You can manage your API Keys within the Beefree SDK Console. All requests must be made over HTTPS and contain the following HTTP Header:

Authorization: Bearer {token}

Rate Limits

API requests rate limits exist independently of API key’s monthly usage allowance.

By default, the API has the following rate limits:

• Per minute: 500 requests

• Per second: 100 requests

• X-Rate-Limit: An integer representing the total number of requests available per cycle. Exceeding the limit per cycle results in a 429 error. (e.g. 500)

• X-Rate-Limit-Remaining: An integer representing the number of remaining requests before the next cycle begins, and the count resets. (e.g. 100)

• X-Rate-Limit-Reset: A Unix timestamp representing the time the next cycle will begin, and the count will reset.

• Retry-After: A Unix timestamp representing the time the application may resume submitting requests.

API Root

All API access is over HTTPS, and accessed from the following URL:

https://api.getbee.io/v1/{collection}/{resource}

Collections

The following table lists the available collection option and corresponding resources for each collection.

Example URLs

The following table provides a few examples of URLs you can use to make specific types of requests.

Resources

The following section provides detailed information for each of the resources associated with each collection mentioned in the previous section.

HTML

URL: https://api.getbee.io/v1/{collection}/html

Plain Text

Endpoint: /message/plain-text

PDF

URL: https://api.getbee.io/v1/{collection}/pdf

Image

URL: https://api.getbee.io/v1/{collection}/image

Prior to using the image endpoint, ensure you reference the following information.

The HTML is rendered in a fixed window size of 1920x1080 to generate a screenshot, with default viewport widths of 320 pixels for mobile and 1024 pixels for desktop, which may cause cropped previews if the content exceeds these dimensions. A clipping size of 1920x1080 is applied, but it can be customized, and the scale factor adjusts to align the viewport and clipping dimensions. For improved results, using auto height with the size parameter is recommended.

Merge

URL: https://api.getbee.io/v1/{collection}/merge

Merge Rows

URL: https://api.getbee.io/v1/{collection}/merge-rows

Synced Rows

URL: https://api.getbee.io/v1/{collection}/synced-rows

Index

URL: https://api.getbee.io/v1/{collection}/merge/index

AI Collection

The resources in the AI collection accept your template JSON and use generative AI to return text within a JSON object to you.

Prerequisites

Prior to getting started with the resources in this collection, ensure you have the following:

• Superpowers subscription or higher

• OpenAI AddOn installed and configured in your Beefree Developer Console

• Content Services API key

Metadata (Preheader and Subject)

v1/ai/metadata

SMS

v1/ai/sms

Summary

v1/ai/summary

Conversion Collection

The Conversion Collection provides you with endpoints that enable you to convert templates from one format to another. With the Email to Page endpoint, you can easily convert your email JSON templates into page JSON. The Page to Email endpoint lets you turn your page JSON templates into email-ready JSON, with the option to disable the HTML sanitizer if needed.

Email to Page Conversion: Important Behaviors

The Email to Page endpoint converts a JSON template created for email into a JSON template optimized for web pages. During this conversion, the following adjustments are applied:

• Remove AMP Carousel Any AMP carousels included in the email template are removed, as these are not supported in the page format.

• Expand Content Area Width The content width is expanded to 900px to fit the web page format, removing the width constraints typically applied to emails.

• Target Attributes Target attributes will not be processed. Remove all link target attributes or set them to "Open a new page." Links will not be modified during the conversion.

• Remove Subject and Preheader Email-specific metadata, such as the subject line and preheader text, is removed since these elements are not relevant in the page format.

• Retain Comments and Secondary Language Comments and secondary language data in the email template are preserved in the conversion process.

Page to Email Conversion: Important Behaviors

The Page to Email endpoint transforms a JSON template designed for a web page into a JSON template optimized for email. During this conversion process, the following adjustments are made:

• Remove Video Row Backgrounds Video backgrounds applied to page rows are removed because email formats do not support video backgrounds.

• Replace Embedded Videos with Thumbnails Embedded videos are replaced with thumbnail images. This ensures recipients can preview the content visually without the compatibility issues of embedded videos. Note: Hosted videos will not be converted.

• Remove Form Blocks Any form blocks present in the page template are removed.

• Adjust Design Content Area Width If the page width exceeds the maximum width supported by the email builder (900px), it is resized to fit within email constraints.

• Update Link Target Attributes Target attributes will not be processed. Remove all link target attributes. Links will not be modified during the conversion.

• Sanitize Code The endpoint sanitizes the code to ensure compatibility with email standards. When the sanitizer is disabled, the payload looks like this:

  Copy

  {
    "disableHtmlSanitizer": true,
    "template": { "page": ... }
  }

• Handle Multi-Column Layouts The email builder supports up to 12 columns, which is compatible with the page builder's column configurations.

Overview

The Brand Style Management endpoint enables you to manage and modify the style of email, pages, and popup templates. While the Content Defaults feature enables you to set default styles for new content elements like headings, paragraphs, and buttons, the Brand Style Management endpoint takes it a step further. It allows you to make template-wide design changes to existing templates quickly and easily, ensuring that all modules adhere to the broader design system or brand guidelines. In this article, we'll explore what this Content Services API (CSAPI) Brand Style Management endpoint is, its benefits, how to get started with it, and how it differs from Content Defaults.

How to Apply Styles Globally

To apply a style globally, take the following steps:

1. Manage Brand Styles: Begin by defining your brand's styles within the schema. The Brand Style Management endpoint schema mirrors the Content Defaults’ JSON. This enables you to easily reuse the styles you’ve already defined in your application’s frontend. Use the same schema to specify colors, fonts, and any other design elements you want to apply uniformly.

2. Prepare the Template: Ensure you have the JSON template ready, which is the foundation for your branding modifications.

3. API Call: Make an API call to the CSAPI Brand Style Management endpoint, providing the schema with your defined brand styles and the JSON template to be updated.

4. API Processing: The API will take care of processing your request. It will automatically merge the specified brand styles into the template, applying the desired changes globally.

5. Receive Modified Template: After the API processes your request, it will return the modified JSON template with the updated styles. This template is now ready to be used in your marketing campaigns with the consistent branding you've defined.

Authentication

Authentication is essential to secure access to the Brand Style Management endpoint. We use API keys to authenticate requests. The API key you should use to access this endpoint is the CSAPI API key available in your Beefree SDK Developer Console. If you do not have a CSAPI key in your Developer Console, ensure you have a paid plan.

Include the API key in the request header as follows:

Authorization: Bearer YOUR_API_KEY

Endpoint

/template/brand

HTTP Method: POST

Description: Apply brand styles to a template, ensuring a consistent visual identity.

Request Parameters:

• styles (JSON): The brand styles to apply to the template.

• template (JSON): The JSON template to be updated with the brand styles.

• HTML Return the template with or without HTML.

The following section displays an example request. Note that the syntax for the CSAPI Brand Style Management endpoint is similar to the syntax for Content Defaults.

Example Request:

POST / template / brand
Content-Type: application / json
Authorization: Bearer YOUR_API_KEY 

{
    "styles": {
        "general": {
            "background": "#eeeeee",
            "links": "#0068a5"
        },
        "h1": {
            "styles": {
                "color": "#333333",
                "fontSize": "36px"
            }
        },
        "h2": {
            "styles": {
                "color": "#CCCCCC",
                "fontSize": 246 px "
            }
        },
        "paragraph": {
            "styles": {
                "color": "#333333",
                "fontSize": "16px"
            }
        },
        "button": {
            "styles": {
                "backgroundColor": "#ff9900",
                "borderRadius": "5px"
            }
        }
    },
    "template": {
        // Your template JSON here
    }
}

You can define multiple classes of buttons, images, and rows by passing an array of styles targeting design elements by their class names. To provide multiple styles, use the className property to define as many styles as you like. Before defining the className within the array, ensure you define the className within the template using the Custom Attribute feature.

The following examples displays a button array.

{
  "styles": {
    "button": [
      {
        "className": "Primary",
        ...more styles
      },
      {
        "className": "Secondary",
        ...more styles     
      }
    ]
  }
}

Response Format:

• 200 OK: The request was successful, and the modified template was returned.

• 400 Bad Request: There was an issue with the request parameters.

• 401 Unauthorized: The API key is invalid or missing.

• 500 Internal Server Error: An unexpected server error occurred.

Example Response:

{
  "html": “html document”,
  "json": {
    // Updated template JSON here
  }
}

Request Format

This section discusses the request formats for the different parameters.

Styles

The styles parameter in the request should follow this JSON format:

{
  "general": {
    // General brand styles
  },
  "title": {
    // Title block styles
  },
  "text": {
    // Text block styles
  },
  "button": {
    // Button block styles
  },
  // Add more block styles as needed
}

Each block style can include attributes such as colors, fonts, borders, and more, depending on your brand's requirements. For additional code samples of each content block type and its respective style customization options, reference the Content Defaults schema page.

Template

The template parameter should contain your template's JSON structure. Ensure that the JSON structure aligns with the template you intend to update.

Table Content Defaults

The following code shows an example of how to configure the style for headers within the table content block:

{
  "headersBackgroundColor": "#EAEAEA",
  "headersColor": "#505659",
  "headersFontSize": "14px",
  "headersFontWeight": "400",
  "headersTextAlign": "left",
  "linkColor": "#0068a5"
}

Using the Brand Style Management Schema

The Brand Style Management endpoint schema is designed to be user-friendly and intuitive. You can use the same Content Defaults schema you used to style your application’s frontend with the Brand Style Management endpoint.

For example:

"styles": {
  "general": {
    "background": "#eeeeee",
    "links": "#0068a5"
  }
}

The CSAPI Brand Style Management endpoint will take these styles and merge them with your design template, eliminating the need for complex manual editing.

Difference Between Content Defaults and the Brand Style Management Endpoint

While both Content Defaults and the Brand Style Management endpoint aim to streamline the design process, they serve different purposes:

Content Defaults

• Can be a part of the Configuration Parameter.

• Set default styles for specific content types.

• Useful for quickly creating new templates with consistent styling.

Brand Style Management Endpoint

• CSAPI endpoint that enables the development of a user interface that empowers end users to make style changes with ease and speed.

• Modify the style of existing templates.

• Suitable for users who need to make template-wide design changes or maintain brand consistency on existing templates.

API billing: why we are charging for this API

The Content Services API (CSAPI) allows you to carry out a number of useful tasks, like converting an email or a page into a thumbnail image or a PDF document, or updating a footer into all the emails that use it (i.e. a saved row).

These tasks consume resources in our Amazon Web Services environment, so we have to account for that. We did extensive research to define pricing that is consistent with other APIs.

Here is a quick summary:

There will be no changes to the functionality of the CSAPI, except that we’ve added a really useful Merge API that allows you to update saved rows in the documents that use them. You can find complete technical documentation on the new “merge” method here.

Most changes related to CSAPI will be in the background, but there will be some changes in the Beefree SDK Console, and in terms of billing.

• API Key Management: when you configure an application in the Beefree SDK Console, you will see two actions – instead of a single Revoke action – in the area of the application settings where your API key is shown:

  • Regenerate: Revokes the current key and creates a new one

  • Disable and revoke: Revokes the current key and disables the service, so you will not be charged for it*

• Billing statement changes: you will see new line items on your Beefree SDK invoice.

Can I try the service without paying?

You can by creating a development application, and then creating a new API key for that app, which will be used for development purposes. Reference our Development Applications documentation to learn how to create one.

How will charges appear on my bill?

An additional charge, CSAPI, will be added to your current subscription plan invoice.

Can I use different payment methods for each app?

The Content Services API is provided as a component for your current subscription and the charges will be applied to the subscription payment method. Currently, there is no option to use an alternative payment method specific to these charges.

How do you calculate request limits?

API requests rate limits exist independently of any API key’s monthly usage allowance.

As of January, 2020, the API has the following rate limits:

• Per minute: 500 requests

• Per second: 100 requests