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.
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.
Collection
Available Resources
/message
html, pdf, images, merge, index, plain-text
/page
html, pdf, images, merge, index
/popup
html
/amp
html
/template
brand
/ai
metadata, sms, summary
/conversion
email-to-page, page-to-email
Example URLs
The following table provides a few examples of URLs you can use to make specific types of requests.
Type
Action
Example URL
Email
Request HTML for email
https://api.getbee.io/v1/message/html
Landing Page
Request HTML for a landing page
https://api.getbee.io/v1/page/html
Popup
Request HTML for a popup
https://api.getbee.io/v1/popup/html
AMP
Request HTML for AMP
https://api.getbee.io/v1/amp/html
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
Transform Beefree JSON into HTML
post
Use this endpoint to transform any template's Beefree JSON into HTML. This endpoint is compatible with Email, Page, and Popup builder designs.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
commentsobjectOptional
An object field for comments
beautifyHtmlEnabledintegerOptional
An integer field for beautifyHtmlEnabled
Responses
200
Successful response
text/html
Responsestring
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/html
Include the optional newbutton query string parameter and set its value to true to generate HTML button results optimized for Outlook. Reference HTML Outlook Button Rendering for additional details.
Plain Text
Endpoint: /message/plain-text
Transform Beefree JSON into Plain Text
post
Use this endpoint to transform any template's Beefree JSON into HTML. This endpoint is compatible with Email builder designs.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
languagestringOptional
A string field for language
Responses
200
Successful response
text/plain
Responsestring
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/plain-text
PDF
URL:https://api.getbee.io/v1/{collection}/pdf
Transform HTML into a PDF
post
Transform email or page HTML into a PDF that can be attached to emails, SMS messages, or physically printed out.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
page_sizestringOptional
A string field for page_size
page_orientationstringOptional
A string field for page_orientation
htmlstringOptional
A string field for html
Responses
200
Successful response
application/json
Responseobject
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/pdf
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.
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.
Name
Type
Description
html*
String
A Beefree HTML message.
size
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.
width
Integer
The image width in pixels. Required if size is not defined.
height
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.
file_type*
String
Accepts jpg or png.
Transform HTML into an Image
post
Use this endpoint to transform a design's HTML into an Image, which can be used for thumbnails and similar purposes. Compatible with Email and Page builder.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
file_typestringOptional
A string field for file_type
sizestringOptional
A string field for size
htmlstringOptional
A string field for html
Responses
200
Successful response
image/png
Responsestring
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/image
Merge
URL:https://api.getbee.io/v1/{collection}/merge
Merge to replace or update content
post
Replace or update content in a Beefree template using a specific path and value. Compatible with Email and Page builders.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Integrate custom fonts and resized images into your designs. It saves custom fonts within the template's JSON, ensuring 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.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
rowIdentifierLabelstringOptional
A string field for rowIdentifierLabel
Responses
200
Successful response
application/json
Responseobject
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/merge-rows
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.
Reference an array of metadata objects from a Beefree template in JSON format.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
Responses
200
Successful response
application/json
Responseobject
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/merge/index
AI Collection
Important: The AI collection is only compatible with OpenAI AddOns that were configured before August 1, 2024. We are actively working on making it compatible with AI AddOns and Providers configured after that date, too.
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
Note: OpenAI billing costs apply in addition to the Content Services API billing.
Metadata (Preheader and Subject)
v1/ai/metadata
Generate Preheader and Subject Metadata with AI
post
Use AI and this endpoint to generate metadata, which includes preheaders and subject lines, automatically.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
Responses
200
Successful response
application/json
Responseobject
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/metadata
SMS
v1/ai/sms
Generate SMS with AI
post
Submit your JSON template as the request body to generate a custom SMS using AI.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
Responses
200
Successful response
application/json
Responseobject
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/sms
Summary
v1/ai/summary
Generate a Summary with AI
post
Submit your JSON template as the request body to generate a custom and concise summary using AI.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
Responses
200
Successful response
application/json
Responseobject
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/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.
Convert Email JSON to Page JSON
post
Convert an email JSON template to a page JSON template, and ensure compatibility throughout the conversion process by removing or adjusting unsupported blocks.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
collectionstringRequired
The collection ID or name
Body
Responses
200
Successful response
application/json
Responseobject
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/email-to-page
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:
Handle Multi-Column Layouts
The email builder supports up to 12 columns, which is compatible with the page builder's column configurations.
Convert Page JSON to Email JSON
post
Convert a page JSON template to an email JSON template, and ensure compatibility throughout the conversion process by removing or adjusting unsupported blocks.
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
