Learn more about how to get started with the Content Services API in the following sections:
CSAPI Overview: Learn about the services available through our Content Services API
Content Service API Reference: Explore our REST API collections and resources
Brand Style Management: Make template-wide design changes to existing templates quickly
FAQs: Reference answers to our mostly commonly asked questions
This feature is available on Beefree SDK paid plans only.
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.
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 your1 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.
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.
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.
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.
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.
The API provides some useful services that offer additional message formats, reducing the development effort in the host application.
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.
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.
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 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.
To apply a style globally, take the following steps:
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.
Prepare the Template: Ensure you have the JSON template ready, which is the foundation for your branding modifications.
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.
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.
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 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:
/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:
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.
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:
This section discusses the request formats for the different parameters.
The styles parameter in the request should follow this JSON format:
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.
The template parameter should contain your template's JSON structure. Ensure that the JSON structure aligns with the template you intend to update.
Both the Content Defaults (frontend) and Brand Style Management endpoint (backend) include the table content block.
The following code shows an example of how to configure the style for headers within the table content block:
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:
The CSAPI Brand Style Management endpoint will take these styles and merge them with your design template, eliminating the need for complex manual editing.
While both Content Defaults and the Brand Style Management endpoint aim to streamline the design process, they serve different purposes:
Can be a part of the Configuration Parameter.
Set default styles for specific content types.
Useful for quickly creating new templates with consistent styling.
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.
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*
*Note: Extra API calls are charged at the end of the billing period. For this reason, the first invoice after cancellation may include CSAPI charges.
Billing statement changes: you will see new line items on your Beefree SDK invoice.
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.
An additional charge, CSAPI, will be added to your current subscription plan invoice.
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.
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
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.
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:
Locate the application that you wish to work with, and click on Details
Locate the Content Services API section and click Create New API 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}
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.
All API access is over HTTPS, and accessed from the following URL:
https://api.getbee.io/v1/{collection}/{resource}
The following table lists the available collection option and corresponding resources for each collection.
The following table provides a few examples of URLs you can use to make specific types of requests.
The following section provides detailed information for each of the resources associated with each collection mentioned in the previous section.
URL: https://api.getbee.io/v1/{collection}/html
HTTP Method: POST
Description: Transform JSON template to HTML.
The following table lists the parameters applicable for this request.
Content-Type: application/json
The following JSON displays an example request.
The following HTML displays an example response.
Endpoint: /message/plain-text
HTTP Method: POST
Description: The endpoint accepts a JSON template and returns a plain text document.
page
(JSON): The email JSON template to create the plain text for.
The following table lists the parameters for this endpoint.
The following section shows an example request:
The following section shows an example response:
URL: https://api.getbee.io/v1/{collection}/pdf
Method: POST
Description: Transform HTML and PDF settings to a JSON object with a PDF url.
The following table lists the parameters applicable for this request.
Content-Type: application/json
The following code sample shows an examples request with HTML and PDF settings.
The following code sample shows an examples response.
Note: The response is a JSON string that will contain the URL of the temporary location of the PDF document. The file is available for 24 hours.
URL: https://api.getbee.io/v1/{collection}/image
HTTP Method: POST
Description: Transform HTML and image settings into an image.
The following table lists the headers applicable for this request.
Content-Type: application/json
The following code sample shows an example response.
The following image is an example response.
application/jpg
The response includes the raw image data.
URL: https://api.getbee.io/v1/{collection}/merge
HTTP Method: POST
Description: Replace a Beefree template in JSON format.
The following table lists the request parameters.
Content-Type: application/json
The following table lists the request parameters for the replace array and whether or not they are optional.
The following code displays an example request of the "replace" array.
application/json
The JSON object containing the following parameters:
The following code displays an example response.
URL: https://api.getbee.io/v1/{collection}/merge-rows
HTTP Method: POST
Description: The Merge Rows endpoint enables you to integrate custom fonts and resized images into your designs. It saves custom fonts within the template's JSON, ensuring the the correct font is displayed. It also handles image resizing, particularly when the image's initial template width is narrower than the saved row's destination template. To use this endpoint, send your template and rows in JSON format. You will receive a response with an updated template. The rows requiring an update are identified by their rowIdentifier
values.
The following table lists the request parameters.
Content-Type: application/json
The following code displays an example request.
The following code displays an example response.
When utilizing this feature, it's important to consider adding a handle to the metadata. This handle serves a crucial role in functions such as onDeleteRow
and onEditRow
. In our provided example, we use a handle named guid
. However, users have the flexibility to choose their own handle name according to their preferences and requirements. When selecting a handle name, we recommend you choose something descriptive and meaningful for ease of identification and management within your workflow.
URL: https://api.getbee.io/v1/{collection}/synced-rows
HTTP Method: POST
Description: Get a list of all the synced rows inside a template with their corresponding rowIdentifier
values.
The following table lists the request parameters.
Content-Type: application/json
The following code displays an example request.
The following code displays an example response.
The following table provides the name, type, and description for the response elements within the returned syncedRows
array.
URL: https://api.getbee.io/v1/{collection}/merge/index
HTTP Method: POST
Description: Reference an array of metadata objects from a Beefree template in JSON format.
The following table lists the request parameters.
Content-Type: application/json
The following JSON shows an example request.
application/json
The JSON object containing the following parameters:
The following JSON shows an example response.
The resources in the AI collection accept your template JSON and use generative AI to return text within a JSON object to you.
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
Note: OpenAI billing costs apply in addition to the Content Services API billing.
v1/ai/metadata
HTTP Method: POST
Description: The endpoint accepts a JSON template and returns a JSON object with metadata (preheader and subject).
The following table lists the parameters for this endpoint.
*Note: Reference the optional parameters for the options
JSON in the following section.
The following table lists the optional parameters for making this request.
The following section shows an example request:
The following section shows an example response with the preheader and subject metadata in the JSON object:
v1/ai/sms
HTTP Method: POST
Description: The endpoint accepts a JSON template and returns a JSON object with the SMS text. Use this endpoint for summaries geared toward SMS.
The following table lists the parameters for this endpoint.
*Note: Reference the optional parameters for the options
JSON in the following section.
The following table lists the optional parameters for making this request.
The following code sample shows an example request.
The following code sample shows an example response.
v1/ai/summary
HTTP Method: POST
Description: The text endpoint accepts a JSON template and returns a JSON object with the summary text. This endpoint is for generating general summaries that can have multi-purpose use.
The following table lists the parameters for this endpoint.
*Note: Reference the optional parameters for the options
JSON in the following section.
The following table lists the optional parameters for making this request.
The following section shows an example request:
The following section shows an example response:
Plan | Included API calls | Cost per extra API call |
---|---|---|
Log into the
Acknowledge the message that reminds you that if you exceed the , you may be charged for overages and click Create Key
Collection | Available Resources |
---|
Type | Action | Example URL |
---|
Name | Type | Description |
---|
Name | Type | Required | Description |
---|
Name | Data Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Parameters | Type | Required or Optional | Description |
---|
Parameter | Type | Required or Optional | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Parameter | Type | Required or Optional | Description |
---|
Name | Type | Required | Description |
---|
Name | Type | Description |
---|
Name | Type | Required | Description |
---|
Name | Type | Description |
---|
Name | Type | Required | Description |
---|
Name | Type | Description |
---|
Essentials
15,000
$0.01
Core
100,000
$0.006
Superpowers
250,000
$0.003
Enterprise
1,000,000
$0.003
|
|
|
|
|
|
|
|
|
|
|
|
Request HTML for email |
|
Landing Page | Request HTML for a landing page |
|
Popup | Request HTML for a popup |
|
AMP | Request HTML for AMP |
|
| object | A Beefree template in JSON format |
| boolean | This flag will force the API to return uncompressed HTML |
| String | A full HTML document |
| String | Accepted values: letter (default), A4, A3, full Full: a single page using 900px as page width. The page_orientation is always portrait when using this page size. |
| String | Accepted values: landscape (default), portrait |
| String | Accepted values: PDF |
| String | A Beefree HTML messag |
| String | Use “size” instead of “width” and “height” when you only know the width and want the height automatically calculated. Required if width and height are not defined. |
| Integer | The image width in pixels. Required if size is not defined. |
| Integer | The image height in pixels. Default applies a proportional value based on the given width, keeping the image aspect ratio. When the value is not proportional to the given width either will occur: If it’s higher, the proportional value applies, or, if it’s lower, the image is cropped. Required if size is not defined. |
| String | Accepts jpg or png. |
source* | Object | A Beefree template in JSON format. |
replace* | Array | An array of objects that contain a JSON path and value to replace. |
value* | String | Object | The value can be an object, such as a saved row. Or, it can be a string, such a hex color code. The value should be the same type as the value you want to match in your match expression. |
path* | String | A JSON Path to the matching nodes in the source JSON. |
Value | String | Object | Required | The value can be an object, such as a saved row. Or, it can be a string, such a hex color code. The value should be the same type as the value you want to match in your match expression. |
Path | String | Required | A JSON Path to the matching nodes in the source JSON. |
json | object | required | The updated Beefree template in JSON format. In the event of an error, the original source is returned. |
html | string | required | The HTML message. |
warnings | array | optional | An array of objects containing information about issues that occurred during the merge. If no warnings exist, then it is safe to save the updated JSON. |
| Array | An array of Beefree rows in JSON format. The array accepts the following format: |
| JSON | A Beefree template in JSON format. |
| This facilitates the addition of missing webfonts for messages associated with synced or saved rows. It allows you to provide a list of webfonts available in your host application to the editor. This information enables the editor to rectify missing webfonts during the merge process, ensuring consistent and accurate rendering of messages across synced or saved rows. |
| String | The label used for identifying the rows added to the metadata key usually is guid. |
| String | The label used for identifying the rows added to the metadata key usually is guid. |
| Array | The JSON of a template. |
| Number | The index of the row in the array of rows inside the Template. |
| String | The value of the |
source* | object | A Beefree template in JSON format. |
rows | array | required | An array of metadata objects containing row details, which can be saved in a database to create a reference (or relational table) to the rows associated with your template. |
| JSON | Yes | The template's JSON. This is the template used to create the AI-generated metadata. |
| JSON | No | Optional settings that instruct the output.* |
| string | Use this parameter to define a tone of voice for the response output. For example, you can include words such "Formal", "Humorous", or "Business" to instruct the AI's response. |
| string | Use this parameter to include extra instructions and fine tune the AI's response. |
| boolean | Use this parameter to return the usage data from OpenAI. Set this boolean to true or false. |
| string | Use this parameter to specify the output language for the response. |
| JSON | Yes | The template's JSON. This is the template used to create the AI-generated SMS text. |
| JSON | No | Optional settings that instruct the output.* |
| string | Use this parameter to define a tone of voice for the response output. For example, you can include words such "Formal", "Humorous", or "Business" to instruct the AI's response. |
| string | Must be one of the following options: "Concise", "Standard", or "Detailed". |
| string | Use this parameter to include extra instructions and fine tune the AI's response. |
| boolean | Use this parameter to return the usage data from OpenAI. Set this boolean to true or false. |
| string | Use this parameter to specify the output language for the response. |
| JSON | Yes | The template's JSON. This is the template used to create the AI-generated summary text. |
| JSON | No | Optional settings that instruct the output.* |
| string | Use this parameter to define a tone of voice for the response output. For example, you can include words such "Formal", "Humorous", or "Business" to instruct the AI's response. |
| string | Must be one of the following options: "Concise", "Standard", or "Detailed". |
| string | Use this parameter to return the usage data from OpenAI. Set this boolean to true or false. |
| boolean | Use this parameter to return the usage data from OpenAI. Set this boolean to true or false. |
| string | Use this parameter to specify the output language for the response. |
| JSON | Yes | The template's JSON. This is the template used to create the plain text document. |
| JSON | Optional |
For , any valid language code sets the output language.