This page lists and describes the Convert category of endpoints within the Content Services API. It also includes interactive testing environments for each endpoint in this category.
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. The Simple to Full JSON endpoint enables you to convert Simple Schema templates into full Beefree JSON templates that can be loaded in the builder.
Important: For all endpoints in this category, the value for collection is conversion. When making API calls, replace the collection placeholder within the URL with conversion to execute the call.
Available Collection Value for Convert Endpoints
The following table lists the collection values available in this category of endpoints, and their corresponding collection options.
Note: The only collection value available for this category of endpoints is conversion. Therefore, all {collection} placeholders in the URL in this category should be replaced with conversion.
Prior to referencing the table, the following example shows how you can replace the {collection} placeholder with conversion.
How to Replace the {collection} Placeholder
The following example URL has a {collection} placeholder. This placeholder needs to be filled in with a Collection Option prior to making an API call.
The following table provides a comprehensive reference of all available options based on what you'd like to convert.
Resource
Collection Options
/page-to-email
/conversion
/email-to-page
/conversion
/simple-to-full-json
/conversion
/full-to-simple-json
/conversion
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>.
Path parameters
collectionstringRequired
The collection ID or name
Body
disableHtmlSanitizerintegerOptional
An integer field for disableHtmlSanitizer
Responses
200
Successful response
application/json
Responseobject
400
Bad request
401
Unauthorized
403
Forbidden
500
Internal Server Error
post
/v1/{collection}/page-to-email
Simple to Full JSON
This section discusses what the /simple-to-full-json endpoint is and how you can use it for AI-driven designs. Beefree SDK template JSON is long and includes many properties. For this reason, it does not provide the best structure for training AI models in workflows that include AI-driven design creation. Beefree SDK's Simple schema is a lightweight alternative that is optimized for training AI models. Simple schema, which is several lines shorter than Beefree SDK's template JSON, is a great solution for AI-generated schemas. This endpoint accepts Simple schema as the body of the POST request, and returns the full Beefree SDK template JSON, which can then be loaded in the Beefree SDK editor for an end user to view and edit accordingly. There are many creative ways to use and implement this endpoint, because it provides a pathway to programmatically creating full Beefree SDK-compatible templates completely outside of the Beefree SDK builder.
Request Parameters
The API call accepts a template object, which is required to successfully perform the /simple-to-full-json API call. The following table describes this required object.
Object Parameters Nested within the Template Object
The following table lists and describes both required and optional object parameters nested within the mandatory template object. This template object is the body of the POST request for the API call.
Name
Type
Required
Description
type
String
✅ Yes
Specifies the template type. Possible values include: email, page, popup.
The following code snippet shows the optional settings object nested within the template object in the body of the POST request.
The following table lists and describes optional object parameters nested within the settings object. The settings object is nested within the mandatory template object.
Name
Type
Required
Description
linkColor
String
❌ No
The default color of the links within the template.
backgroundColor
String
❌ No
The background color of the template.
contentAreaBackgroundColor
String
❌ No
The background color of the content area.
width
integer
❌ No
Important: The width of the template must be between 320 and 1440 pixels.
Metadata Object Parameters
The following code snippet shows the optional metadata object nested within the template object in the body of the POST request.
The following table lists and describes optional object parameters nested within the metadata object. The metadata object is nested within the mandatory template object.
Name
Type
Required
Description
lang
string
❌ No
The language code of the template (for example, "en", "fr").
title
string
❌ No
The title of the template.
description
string
❌ No
A short description of the template.
subject
string
❌ No
The subject line of the email (if applicable).
preheader
string
❌ No
The preheader text for the email (if applicable).
Simple to Full JSON
post
Transforms a simple JSON schema into a full JSON schema that can be easily loaded as a template within the Beefree SDK builder.
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}/simple-to-full-json
Full to Simple JSON
This endpoint is in beta.
The Simple Schema currently doesn't support all modules and properties present in the full JSON Schema, so please note that some design details may not carry over when using this API.
We'd love to hear about your experience working with this endpoint. Please share your feedback [email protected]. We can't wait to hear from you!
The Full to Simple endpoint provides a service that converts Beefree SDK's rich design documents (Full JSON) into simplified representations (Simple Schema). This enables a new layer of AI integration and workflows, making Beefree SDK's content understandable to large language models (LLMs) and other generative tools. If you’re building with LLMs or generative design systems, this endpoint is your bridge between rich visual design and structured AI-compatible data. When paired with the Simple to Full conversion endpoint, you'll unlock a complete AI-human collaborative design loop.
Use Cases
The Full to Simple endpoint is particularly useful in the following scenarios:
AI Iteration Workflows: Use the Simple Schema output to feed an AI agent that proposes changes or creates design variations. After AI-generated suggestions are returned in Simple Schema format from the AI agent, use the existing Simple to Full endpoint to convert back to full JSON and load the new version of the design in the Beefree SDK builder. From there, the end user can review the updated design, apply edits within the no-code builder, and export the design once they reach a final version.
Selective Design Adjustments by AI: AI tools can target individual components in a simplified layout—for example, change a CTA, adjust text, or move sections—without dealing with full schema complexity.
Training AI Models: Convert your library of full Beefree templates into simplified JSON to use as training input for generative design agents, enforcing brand consistency or layout structure in AI-created outputs.
