Overview

In this article, we will discuss how to sign up for an account in the Beefree SDK Developer Console, create an application, and obtain your Client ID and Client Secret.

This article will cover steps for the following processes:

• Sign up for an account in the Developer Console

• How to create an application

• Obtain your client secret and client id

Sign up for account in the Developer Console

The first step to embedding Beefree’s visual builders in your software is to sign up for a Beefree SDK account.

Take the following steps to sign up for a Beefree SDK account and subscribe to the Free plan:

1. Navigate to the Developer Console Sign Up page.

   Note: If you already have an account, navigate to the Developer Console Login page instead.

2. Complete the required information to sign up or login.

   You will be redirected to the dashboard.

3. In the dashboard, click Add new subscription.

   You will be redirected to a page that asks you to provide a name for your new subscription.

4. Type in a name and click Next.

   You will be redirected to a page that asks you to select a subscription plan. If you'd like to subscribe to the Free version, click on the corresponding Select plan button Free plan type. If you'd like to subscribe to a paid plan, select the paid option that works best for your needs.

5. A confirmation message will appear confirming that you selected the Free plan and that you will not be charged anything. Click Confirm to confirm your subscription the the free plan.
6. While the plan is free, ensure that you familiarize yourself with the scenarios in which charges would apply. The following image shows a plan summary displaying instances of when charges apply.

1. Enter and confirm your billing address.

2. Enter and confirm your card information by clicking Place Order.

   You will be redirected your new Free plan subscription.

How to create an application

Once that’s done, you will be able to log into the Beefree SDK Console. Your dashboard will look like the following image.

You will have the option to activate any or all of the following applications:

• Email Builder Application

• Page Builder Application

• Popup Builder Application

• File manager Application

Take the following steps to create an application:

1. Click the Activate button that corresponds with the application you'd like to create.

2. Type in a name for your new application.

3. Click Create.

Your application will look like the following in the dashboard once it is activated:

You have successfully created an application. Now, you can enter the application Details and obtain your Client ID and Client Secret.

Obtain your Client ID and Client Secret

Click on your application's Details button to view your Client ID and Client Secret. Use these to authenticate when you initialize it.

With your Client ID and Client Secret, you can use our Sample Code to experiment with a simple integration of Beefree SDK. You can also get started with your own implementation of Beefree SDK.

Reference the following related topics to learn more about customizing your applications, creating development instances, and referencing sample code.

Regenerate Client Secrets

Inside the Beefree Developer Console, you have the option to regenerate the Client Secret for your application. To regenerate your application's Client Secret, take the following steps:

1. Log in to the Beefree SDK Console.

2. Navigate to the application you'd like to update the Client Secret for.

3. Click on the application's Details button.

1. Navigate to Application keys within the application's details.

2. Click Regenerate to generate a new Client Secret.

1. You will be prompted to a modal and asked to confirm your application's name.

2. Complete the App Name field and click Regenerate to complete the action.

Your new Client Secret is now available and ready to use. Your old Client Secret will expire 24 hours after creating the new one. Ensure you replace it in all the necessary environments prior to its expiration.

• Create development applications

• Configuration parameters

• Server-side options

• Sample code

Overview of Form Block

The Form Block within Beefree SDK allows you to easily create and integrate customizable forms into your application. This feature is particularly useful for capturing user information, feedback, and other data directly through interactive forms. With various pre-built templates and customization options, the Form Block is easy to integrate for developers and intuitive to use for end users.

into page or popup builders is straightforward. The SDK provides intuitive methods to embed forms within your web pages or popups. With drag-and-drop functionality and predefined settings, adding a form to a design can be accomplished in just a few steps, enhancing workflow efficiency for your application's end users.

The Form Block supports a wide range of input types, such as text fields, radio buttons, checkboxes, and dropdown menus. This flexibility ensures that end users can gather the exact type of information they need from the form. Additionally, form submissions can be easily configured to trigger actions, such as email notifications or data storage, providing a robust and integrated data collection solution.

Learn more about to use and integrate Form Block in the following section:

Overview

When you load a Beefree application inside the host application, you pass a configuration object with multiple sections that define the characteristics of the UI, UX, and available elements. However, there are cases when you may want to reload this configuration without the need to reload the Beefree application. In these cases, you can use a specific event to update the configuration while the editor is open.

Use cases

With this event, you can make on-the-fly changes to the user experience. For example:

• Updating available categories for Saved rows

• Refreshing a Custom header for authorization

• Changing Advanced permissions for the current user

• Updating settings for the editor’s Content defaults

How it works

You can load the configuration changes via a new instance event. Here’s an example:

var newConfig = {
  advancedPermissions: {
    // new permissions
  }
}

bee.loadConfig(newConfig)

What is Beefree SDK?

Beefree SDK is an embeddable no-code email, landing page, and popup builder. It enables your end users to achieve their design goals without writing a single line of code. By embedding Beefree SDK into your application, you'll provide your end users with access to a full suite of design features that include the following and more:

• Email builder: A no-code email creation environment that helps end users quickly create beautiful emails. This environment supports your end users in following email creation best practices recommended by industry experts.

• Page builder: A no-code landing page creation environment that empowers end users to build visually stunning landing pages. They can use a landing page as a link for a call-to-action (CTA) inside emails, to embed forms and capture information, or to create standalone pages.

• Popup builder: The popup builder is a no-code environment that provides end users with the tools they need to build compelling popups that capture attention.

• File manager: A tool to manage media assets (images, PDFs, and so on).

• Template catalog: A design template catalog that integrates industry best practices to support end users in quickly getting across the finish line with their creations and achieving quick design wins.

• AI Writing Assistant: A helpful AI assistant to help end users write their design content.

These builders can easily integrate into your application in minutes. Browse this documentation's latest sample code and implementation guides to get started.

Quick Start

Take the following steps to get started with Beefree SDK in a few minutes:

1. Create an account to access the Developer Console and obtain your credentials.

2. Create a new subscription to get started. Beefree SDK offers a generous Free plan that includes each builder type mentioned in the previous section.

3. Create an application and obtain your Client ID and Client Secret.

4. Clone the beefree-sdk-sample-client repository, which includes the code for email and popup builder implementations.

5. Add your credentials, the Client ID and Client Secret from step three, inside the placeholders in the code.

6. Once the email builder, or popup builder, depending on which environment you chose, opens, you can start experimenting with the SDK's configuration by customizing the configuration parameters in the beeConfig section of the code.

7. You can also customize the SDK's configuration inside the Developer Console under the Application configuration section of the application you created.

Beefree SDK's Embeddable Builders

Learn more about our three embeddable builders.

File Manager

In addition to our drag-and-drop editors, we also offer a standalone File Manager application, which can be used alongside any of the builders. The File Manager is specifically designed to simplify the organization and management of digital assets, which might happen outside of a content editing session. It is an image and document management user interface that can be launched as a standalone application. This allows your customers to quickly upload or manage assets, without having to load one of the builders.

Learn more about our File Manager and File Storage Options.

Customize Your Application with AddOns

Learn more about how our builder AddOns can help you customize your application's offerings.

Content Services API and Template Catalog API

The Content Services API allows you to perform a number of tasks (e.g. refreshing the HTML for a certain asset) and add features to your application (e.g. converting an email to a PDF document). We continue to release new API methods to help you enrich and personalize the content design experience for your customers.

The Template Catalog API enables you to incorporate design templates into your application. With this API, you can browse, retrieve, and utilize a variety of pre-designed templates to enhance your user's content creation experience. It gives you the flexibility to offer customized design solutions directly within your platform.

Learn more about Content Services API and Template Catalog API.

Sample Code

Browse our sample code to experiment and gain hands-on experience. Get up and running quickly with a simple implementation.

Developer Essentials

Get your free Client ID and Client Secret in the Developer Console to get started. Experiment with customizing a configuration in the playground. When you're ready, install Beefree SDK.

About this documentation

These products share the same, unique combination of design flexibility and ease of use. Note that the majority of the documentation applies to all builders (and in many cases to the File Manger too), unless otherwise specified.

Overview

Saving your end users time when creating designs is more important than ever—especially as AI continues to reshape expectations. Today’s users want to move fast, and increasingly expect to generate polished, on-brand designs with just a prompt or a click. is built to meet that demand. It provides you with the building blocks you need to construct an AI-driven content creation experience for your end users. This provides them with a faster, more flexible way to build emails, landing pages, and popups instantly inside your application.

empowers your team to unlock AI-driven design creation and headless template generation—making it easier than ever to build designs programmatically, and 100% outside of Beefree SDK's visual builders. Whether you're building emails, landing pages, or popups, you can leverage Simple Schema as a lightweight, intuitive format that AI models can easily understand and generate.

Headless Template Creation with AI

is designed for flexibility, making it ideal for AI-assisted and headless workflows. Imagine a tool where users describe the design they want in plain language, and submit that description to an AI agent. On the backend:

• An AI model receives the description and generates a Simple Schema-compatible template.

• This template is passed to the /v1/conversion/simple-to-full-json .

• The API returns the complete Beefree JSON for the entire template.

• The template is loaded in the builder, and the end user can start applying edits in a no-code environment.

The following image displays an example UI with a basic AI Email Design Assistant that connects to Simple Schema on the backend. By building your own UI and AI agent, you can leverage Simple Schema on the backend to programmatically build templates and load them in the Beefree SDK builder for your end users to use.

In the following image, the programmatically-created email template is loaded within the Beefree SDK builder, and ready for editing.

Benefits

Using for AI-driven design creation offers the following benefits:

• AI-ready: A simplified format perfect for machine-generated layouts.

• Headless by default: Build and deploy templates entirely outside the visual builder.

• Production-ready: Easily convert to Beefree JSON with a single API call.

• Efficient: Reduced payload size and faster AI generation.

Simple to Full JSON API Endpoint

This endpoint is essential for converting AI-generated or manually assembled Simple Schema templates into full, builder-compatible Beefree JSON. Learn more about how to use this endpoint in the .

Overview

Here is a list of terms used frequently throughout the Beefree SDK technical documentation. Things can get a bit tricky when embedding a software application within another software application, so this page is an attempt to create as much clarity as possible. We hope we find it useful. If anything sounds confusing or if you have any suggestions for improvement, please .

Frequently used terms

• Beefree SDK A toolkit that includes white-label, no-code builders for emails, landing pages, and popups. The toolkit also provides a range of components, APIs, sample code, and support services to help you seamlessly integrate into your software a content creation workflow that your customers will love.

• Beefree SDK subscription A subscription to the Beefree SDK. There are different , starting with a Free plan. Once you have a subscription, you can create one or more Beefree applications.

• Beefree application An instance of any of the no-code tools that can be embedded in your software. They include:

  • Email Builder

  • Page Builder

  • Popup Builder

  • File Manager

• Beefree SDK Console A multi-user administration panel where you can sign up for a Beefree SDK subscription, manage the subscription, and create and configure a Beefree application within a subscription.

• Production application An instance of a Beefree application used in your production environment.

• Development application An instance of a Beefree application used for development, QA or staging environments. You can create multiple, development applications under a production application.

• Host application Your software application, which will host one or more Beefree applications.

• Beefree system The backend system that interacts with your Beefree application to provide services such as application authorization.

• Content Services API A set of in the Beefree system that allow you to perform a variety of tasks connected to the implementation of a content creation workflow.

Merge

The merge method allows you to update a row across multiple templates. Specifically, it enables the host application to modify an element within an existing JSON document. This means you can implement a feature that updates templates in the background—without requiring any action from your users. It's ideal for merging shared content () into templates that use it—for example, updating the same footer across 30 different email or page templates.

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

What if a footer is shared by 10 messages and needs to be updated in all of them? The 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.

Index

The index method in the Content Services API lets you retrieve a list of assets that include a specific saved row. This method is essential for determining which assets need to be updated using the merge method.

Typical Use Cases

• Updating shared headers or footers across multiple templates

• Modifying expiration dates in seasonal campaigns

• Applying price or link changes to reused promotional content

• Making any update to shared blocks without manually editing each message

Use the index method first to locate all impacted assets, then apply changes with the merge method to ensure content is updated consistently.

Fetch a list of all Designers

/v1/catalog/designers

HTTP Method: GET

Description: Access a complete list of all Designers in the catalog.

The response is paginated, with a standard display of 200 items per page. You can manipulate the ‘pagesize’ request parameter to control the number of items shown per page.

Request Parameters

The following table displays request parameters.

Fetch a single Designer

/v1/catalog/designers/:slug

HTTP Method: GET

Description: Retrieve detailed information for a specific Designer, identified by the unique slug present in the URL. This enables the procurement of comprehensive data pertaining to the particular designer, including their portfolio of templates and any associated metadata within the catalog.

Fetch a list of all Tags

/v1/catalog/tags

HTTP Method: GET

Description: Retrieve a full list of all the Tags in the catalog. Tags are keywords tied to templates, helping you find and sort templates based on certain themes or attributes.

Request Parameters

The following table displays request parameters.

Manage users in the Console

You can invite additional users to your Beefree SDK Console. To do so, go to Manage users from the personal menu in the top right.

The user that initially created the account is identified as the account owner and can add users from this page.

Additional users will be identified as admins. The owner may limit access to certain production apps when creating or editing an admin.

The account owner has these additional privileges, compared to admins:

• add, edit or delete users, as described above;

• turn on , using tokens provided by mobile apps like Google Authenticator or Authy. 2FA can be enabled either for specific users, or account-wide from the Settings & Security section in the personal area ();

• change the company’s name, also in Settings & Security.

Bearer Token Authentication

Beefree SDK's Content Services API uses bearer tokens to authenticate requests. You can create, view, and manage your bearer token in the . All requests must be made over HTTPS and contain the following HTTP Header:

Create a Bearer Token

To use the Template Catalog API you will first need to obtain a your API Key—the bearer token you will use to authenticate to make API calls—from the Beefree SDK Developer Console.

To obtain an API Key, take the following steps:

1. Log in to the .

2. Navigate to the application you'd like to activate the Template Catalog API for.

3. Click on the corresponding Details button.

4. Navigate to the Content Services API section of the Details page.

5. Click Create New API Key.

   A pop up will appear asking you to confirm that you understand may apply.

6. Click Create Key.

Your API key will appear under the Template Catalog API section of your application details.

Manage Subscriptions in the Console

We understand that each company has its own unique needs. For that reason, we offer the flexibility of adding multiple Beefree SDK subscriptions within the Developer Console. Through this option, you can take advantage of multiple subscriptions to our product for your teams, business units, and so on.

How to Add a New Subscription

You can create an additional subscription within the Beefree SDK Developer Console.

To achieve this, take the following steps:

1. Log in to the

2. Navigate to your dashboard

3. Click Add new subscription on the upper right-hand side of the screen

4. Type a name for your next subscription and click Next

5. Choose a plan and click Select plan

6. Confirm the plan you selected

7. Finalize your additional subscription

Fetch a list of all Categories

/v1/catalog/categories

HTTP Method: GET

Description: Retrieve a list of all the Templates within the catalog, applying filters based on request parameters.

You can extract a list of all the Categories present within the catalog. This comprehensive list includes all categories under which templates are classified.

The response that you receive is paginated for ease of reading and navigation. It displays 200 items per page by default, providing a comprehensive view of the catalog content.

However, if you wish to adjust the number of items shown on each page, you can use the ‘pagesize’ request parameter.

Request Parameters

The following table displays request parameters.

Fetch a single Category

/v1/catalog/categories/:slug

HTTP Method: GET

Description: Retrieve a list of all the Templates within the catalog, applying filters based on request parameters.

Retrieve detailed information about a specific Category using its unique identifier, or slug, which can be found in the URL. This method allows you to access in-depth data related to that particular category, such as its associated templates and related metadata.

Bearer Token Authentication

Beefree SDK's Content Services API uses bearer tokens to authenticate requests. You can create, view, and manage your bearer token in the . All requests must be made over HTTPS and contain the following HTTP Header:

Create a Bearer Token

To use the Content Services API you will first need to obtain a your API Key—the bearer token you will use to authenticate to make API calls—from the Beefree SDK Developer Console.

To obtain an API Key, take the following steps:

1. Log in to the .

2. Navigate to the application you'd like to activate the Content Services API for.

3. Click on the corresponding Details button.

4. Navigate to the Content Services API section of the Details page.

5. Click Create New API Key.

   A pop up will appear asking you to confirm that you understand may apply.

6. Click Create Key.

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

Overview

Self-Hosted Saved Rows allow you to control where and how your rows are stored and managed, offering flexibility to meet your application's unique requirements. This option is ideal for teams with development resources who want to integrate row storage into their existing infrastructure.

When users save rows, the data includes layout, content, and style settings. This data needs to be stored and managed, typically in your own database, to make rows available for reuse within your design builder.

Key considerations for Self-Hosted Saved Rows:

1. Storage Use a database or storage solution to house self-hosted saved rows. Examples of a few options include:

   • Cloud databases (e.g., AWS RDS, Google Cloud Firestore)

   • Local databases (e.g., MySQL, PostgreSQL)

   • Document-based databases (e.g., MongoDB)

2. Development Resources Ensure your team has the capability to connect your storage to your application. This includes:

   • Setting up secure storage with proper access controls.

   • Implementing any necessary API endpoints or backend logic to retrieve, save, and manage rows.

Custom Database Integration

You can directly save and retrieve rows using your own database.

Managed Solution Alternative

For teams that prefer not to handle row storage and development in-house, we offer . This solution stores rows for you and provides your end users with a UI for saving rows throughout their designing experience. This eliminates the need to create a custom infrastructure.

Building web pages with Beefree SDK

Beefree SDK Page Builder will help your customers create beautiful, responsive landing pages, complete with forms and embedded videos. Combined with our Email Builder, you’ll have the power to deliver to your customers a single, optimized user experience for designing both emails and web pages.

With the Page Builder, your customers can create landing pages and one page sites with

In addition, you will find exclusive features that make sense for web pages, such as forms, embedded videos, and the ability to paste scripts, like an embeddable SurveyMonkey or Typeform survey.

Here are a few examples of web pages your customers can build with:

• Product showcase or teaser

• Disclaimer (e.g. age verification)

• Registration (e.g. events, gated content)

• Newsletter subscription

• Customer survey

• Booking request

• Portfolio

They can also create fantastic one page websites, i.e. sites where all the content usually spread in different pages fits nicely into an easy-to-scroll page, complete with menu and anchors to navigate it.

We are constantly improving the user experience: we see the Page Builder as a long-term, ongoing project at Beefree SDK.

MIME types are a standardized way to indicate the nature and format of a file, specifying what kind of data it contains. Groups are categories that aggregate these MIME types for simplified handling and management in applications like File manager. This organization allows for custom limitations and processing based on file type.

The following list shows which specific mime types are mapped to our group names for custom limitations on File manager.

Additional Considerations

When working with files, mime types and groups, ensure you consider the following:

• The default maximum file size you can upload is 20MB.

• If you upload an image wider than 1920 pixels, when the image is uploaded or imported, it will be resized to fit within 1920px. This may cause issues with the image's appearance, including colors that change and GIFs that lose frames. Ensure your images are no wider than 1920px to avoid these issues.

Learn more about .

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.

• An configured within the .

• Content Services API key.

Metadata (Preheader and Subject)

v1/ai/metadata

SMS

v1/ai/sms

Summary

v1/ai/summary

Overview

The debug parameter in the beeConfig is an optional object that enables internal debugging features within the Beefree SDK editor. It's designed to help developers inspect configurations, , and more easily during development.

How to Use

You can pass the debug parameter directly in your beeConfig object when initializing the editor. Alternatively, you can set or update it live using the loadConfig method—no need to refresh the editor.

Example (in beeConfig):

Set it live (no refresh needed):

Parameters

The debug parameter in the Beefree SDK configuration accepts the following parameters:

• all (boolean): Enables all available debug options (inspectJson and showTranslationKeys). Use this during heavy debugging sessions.

• inspectJson (boolean): Adds an eye icon in the toolbar that allows you to inspect the specific JSON used for that element. Useful for understanding how your configuration is being rendered.

• showTranslationKeys (boolean): Replaces localized strings with their translation keys throughout the UI. This is especially helpful when debugging i18n issues or checking for missing .

When It's Useful

The debug parameter is particularly helpful in the following scenarios:

• You're troubleshooting UI rendering issues tied to configuration JSON.

• You need to inspect what exact data is being used for rows/modules.

• You're working on translations and want to ensure correct keys are being used.

Overview

A Release Candidate (RC) Environment is a crucial part of the deployment workflow designed to provide Enterprise customers with additional stability and assurance before a feature reaches full production. Unlike standard releases, which immediately roll out updates to all users, the RC environment acts as an intermediate step. It allows selected customers to access a production-ready version of the latest code before it becomes available to the wider user base. This controlled rollout process mitigates risks associated with unforeseen bugs and ensures a smoother transition. It also mitigates the risk of regressions and rollbacks. By implementing an RC environment, Beefree SDK enables Enterprise customers to conduct their own QA testing on new features, reducing potential disruptions when updates go live.

Benefits of the Release Candidate Environment

The following list includes some of the most commonly referenced benefits of utilizing the Release Candidate Environment.

• Risk Mitigation: Enterprise customers can validate new updates in a stable, production-like setting before they are fully deployed.

• Enhanced Quality Assurance: QA teams can test features in real-world scenarios, catching regressions before broader release.

• Predictable Deployment Schedule: A structured release cadence (RC → General → Delayed) ensures smoother rollouts with fewer surprises.

• Reduced Need for Rollbacks: The phased approach minimizes critical failures in production, lessening the necessity for emergency rollbacks.

• Customer Control: Enterprise customers have additional time to adjust workflows and prepare internal documentation before full adoption.

How the Release Candidate Environment Works

The RC environment operates within a structured release cycle, ensuring that new updates are progressively introduced. When a new feature is ready for release, it is first deployed to the RC environment. Only Developer applications linked to the RC version can access this release. After a one week waiting period—assuming no major regressions are found—the update moves to the stable version, making it available to non-Enterprise customers. After a week, the update reaches the Delayed version, which is linked to Enterprise Production applications. This phased approach ensures that issues are detected early while maintaining a predictable release schedule.

Requirements for Accessing the Release Candidate Environment

Reference the following requirements for accessing the Release Candidate Environment prior to getting started with it.

• Only available to Enterprise plan customers with Developer applications.

• Contact the Beefree SDK team using this contact form and request access to the Release Candidate Environment.

• Customers must be aware that while the RC version is production-ready, it is still subject to final testing and potential bug fixes.

• The program does not allow for customized release schedules per customer; all Enterprise customers follow the same cycle. Customized release schedules are available on VPC plans. For more information, contact the Beefree SDK team using this contact form and request more information about customized release schedules with VPC plans.

Additional Considerations

The Release Candidate Environment is specifically designed for frontend features, the JSON-to-HTML parser, and the JSON Bumper. Backend services are not currently covered under this process. Bug fixes, while critical, may bypass the RC process when necessary to expedite resolutions. By adopting the Release Candidate process, Beefree SDK provides Enterprise customers with greater predictability, quality assurance, and peace of mind in managing their integrations.

Synced Rows

Synced Rows expands on the foundational capabilities of Save Rows and Edit Single Row Mode, helping users manage rows more effectively. Using the merge-rows and synced-rows methods in the Content Services API (CSAPI), you can create an efficient row management workflow. This ensures that when users update content in one row marked as “synced,” those updates are reflected across all connected designs using that synced row.

Prerequisites

• Self-hosted Saved Rows

Key features

• Cross-design synchronization: Sync saved row contents across multiple linked designs.

• Design consistency: Lock rows in linked designs to keep designs uniform.

• Editing flexibility: Convert rows from synced to unsynced, making individual changes as needed.

• Intuitive edit indicator: Look for the pencil icon at the top-right of synced rows, which provides access to editing options

Example use cases

• Auto-updating contacts: Change a contact in one email, and it updates across multiple campaigns.

• Effortless re-branding: Edit your logo once and watch it reflect across all designs.

• Unified transactional footers: Update details like copyright or social links, and it automatically updates in all relevant email templates.

Elements that can be synchronized

• Row details: This includes structure, settings, and styles.

• Content details: Settings and styles of individual content blocks.

• Metadata: Any metadata tied to the saved row.

Edit Single Row Mode

With Edit Single Row Mode you can offer an easier way for your end users to modify a single row with a tailored UI built to edit the row structure, content, and style settings without interfering in the overall design of the email campaign, landing page, or pop-up.

Edit Single Row mode complements both Saved Rows and Synced Rows, because it allows complete control over the content of an individual row (for example, a footer that requires an update) without the need to intervene in a full template's design. This will help you in implementing a more effective way to manage libraries of Saved Rows and Synced Rows with a streamlined design and editing process.

Custom JavaScript

Enterprise customers can request to inject external JavaScript libraries, like FullStory or Heap, into Beefree SDK when the integration is initialized as part of the server-side configuration.

Custom JavaScript requires a complete technical evaluation by the Beefree SDK development team. The assessment will undergo security, technical and compatibility assessments.

How it Works

Contact our Sales team and ask to run a script to get started with custom JS libraries injection. Once you contact us, we will take the following steps to complete your request:

1. Our representative will forward your request to our development team

2. The development team will review the script and approve it

3. The script is enabled by our development team

Creating an application

When you log into the Beefree SDK Console you can immediately see what type of applications you have already created under your Beefree SDK subscriptions. To create a Popup application, head over to the Popup Builder Application section and click on Activate.

Once created, head over to “Details” for all server-side configurations. Paid applications allow you to create child development applications, to ease new feature testing, development, and maintenance.

All builders share the same core functionalities, including authentication and configuration. If you have already integrated our Email builder, you can re-use most of your work using the same configuration and callbacks.

Integrating the Popup Builder

Out-of-the-box, the setup and configuration are the same as Email and Page Builder. This section will cover the settings specific to Popup Builder. Check out our Getting Started guide if you’re new to Beefree SDK or unfamiliar with the configuration basics (as seen in the example below).

beeConfig: {
  uid: 'CmsUserName', // [mandatory]
  container: 'bee-plugin-container', // [mandatory]
  ...
}

Loading Popup Builder with no additional settings will give the end-user a beautifully designed popup and workspace to design their content. However, Popup Builder comes with an additional, robust set of configuration options to customize the workspace. This allows the host application to build a workspace that matches their popup’s look and feel and that of the destination page.

For example, the host app can customize…

• The popup workspace background to view how the popup will look “in context” on the destination page.

• The theme and position of the popup for both desktop and mobile design modes.

Continue reading to learn more on how to customize the workspace, starting with the common settings and working up to a full custom layout.

HTML output

In Email and Page Builder, the Beefree SDK HTML parser service converts your template into an HTML document customized for email or pages, respectively. However, the Popup Builder will not return a full HTML page because the host application is the final destination. In addition, Beefree SDK Popup Builder doesn’t provide the scripts to control the popup’s behavior, such as opening and closing. Rather, Popup Builder provides the HTML “partials” to embed within your popup’s content area or body.

The HTML partial will come with all the CSS required to look as it did in the preview mode. The parser service will wrap the content with a special container to clear all the host application styles and prevent style conflicts. The HTML output is designed to be embedded into any popup framework or application and still render the way it appears in the builder.

Developer resources

Our Github account has some resources that might help you out when testing and integrating the Popup Builder.

Sample code

Examples of different implementations and configurations that you can draw from to speed up your development.

Popup templates

A collection of ready-made templates that you can use right away and add to your application.

Integrating and Testing the Page Builder

When you create an application in the Beefree SDK Console, you’ll be asked to select either Page or Email Builder. Paid applications allow you to create child development applications, to ease new feature testing, development, and maintenance.

Page and Email builders share the same core functionalities, including authentication and configuration. If you already integrated our Email builder, you can re-use most of your work by using the same configuration and callbacks. If this is your first approach to our builders, just follow the Installation section in our documentation. All the documentation in this site applies to both products, except where noted.

All builders are available to Beefree SDK customers under the same all-in-one pricing. Please contact your Customer Success Manager for more details.

The experience

We aim to provide the foundations needed to build a delightful page building experience. We started with the basic features that are already provided to design awesome email messages and tweaked them to work for Web pages.

Once launched as Page Builder, an application will have a few but noticeable differences from the Email builder experience:

• width for pages can be expanded up to 1440px;

• the stage can be scrolled horizontally;

• the sidebar can be collapsed to provide more workspace – useful when working with larger widths;

• there’s a new 6-columns row layout, to take advantage of larger widths;

• the preview includes viewport resize, to test responsiveness on various screen sizes;

• the HTML block allows using scripts, for improved compatibility with embedded content like surveys. This also includes Javascript, although it cannot be executed within the builder.

If you’re on a paid plan, you will also get support for forms and embedded videos.

• You can define and pass forms to the builder, and use the form content block to retrieve and style those forms.

• You can use the video content block to embed and playback videos hosted on Youtube and Vimeo, or point to a hosted video in MP4 format.

Additional resources

Managing forms with the Page Builder

A quick primer on how to include forms in a web page.

Developer resources on GitHub

Our Github account hosts useful resources, including sample code to quick start your integrations.

Get a list of all Templates

/v1/catalog/templates

HTTP Method: GET

Description: Retrieve a list of all the Templates within the catalog, applying filters based on request parameters.

You can execute a search by providing a series of terms within the ‘search’ request parameter. This search will operate on template title, description, category name, collection name, designer name, publication date (‘published_at’), and tags.

The response will encompass a ‘facets’ field, outlining the count of existing Templates across each Category, Collections, Designers, and Tags fields and their sub-fields, considering any applied filters and searches.

The response is paginated, presenting 20 items per page by default. The ‘pagesize’ request parameter enables control over the page size.

Request Parameters

The following table displays a list of request parameters.

Fetch a single Template

/v1/catalog/templates/:slug

HTTP Method: GET

Description: Fetch a single template identified by its slug (in the URL).

The Page Builder includes an expanded Video content block for optimized usage of videos on web pages. Videos are added inside an iframe via the HTML5 video tag.

There are multiple ways to add a video to a page built with Beefree SDK. Additional settings allow the video progress bar and loop playback to be turned on or off.

Embedded

The Embedded mode allows video playback inside the page. It requires the URL of a video hosted on YouTube, YouTube Shorts, or Vimeo.

Hosted video

Same as the embedded option, but the URL provided must point to a self-hosted video in MP4 format. Settings for hiding controls and loop playback apply as well. Please note that the player interface your visitors will experience might slightly vary based on the browser they use.

Thumbnail

As a fallback, you may also use the video block for generating a thumbnail, the same way the block works when building emails. Just enter the URL for a video hosted on YouTube, YouTube Shorts, or Vimeo. A thumbnail linked to the video will be created. You may also style the overlay play icon.

Supported Video Sources

• YouTube (16:9 aspect ratio)

  • Public Videos

  • Unlisted Videos

  • Videos starting at a certain time

• YouTube Shorts (16:9 aspect ratio)

• Vimeo

  • Public Videos

  • Unlisted Videos

  • Cinemascope (21:9 aspect ratio)

Fetch a List of Collections

/v1/catalog/collections

HTTP Method: GET

Description: You can pull up a full list of all Collections in the catalog. Collections are groups of templates with similar attributes or purposes. This overview can help you understand the types of template groupings available.

The response will be paginated, with 200 items per page default for easy navigation. However, you can change this default by adjusting the ‘pagesize’ request parameter to suit your viewing preferences.

Request Parameters

The following table displays request parameters.

Fetch a single Collection

/v1/catalog/collections/:slug

HTTP Method: GET

Description: Access a specific Collection using its unique slug found in the URL. This lets you view detailed information about this particular group of templates, including its associated templates and any related details.

Overview

Besides the client-side configuration parameters that you can set for your instance of Beefree SDK, you also can specify some server-side configuration options.

Access Server-side Configurations

To access server-side configurations, log into your Beefree SDK Console and select the application that you wish to configure.

In the application’s details page, locate the area called Application configuration.

Manage roles is used to manage user roles. For details on this feature, see “user roles and permissions“.

Click on Open configuration to manage the server-side settings like:

• Toolbar options: affect the UI of the editor

• Storage options: determine where the File Manager will store & retrieve images

• Content options: define whether certain content elements (e.g. HTML block) are active or inactive

• Service options: define whether additional services (e.g. photo search) are active or inactive

is based on the concept of unique users of the editor. A unique user is one that is identified by a unique UID, as described below. The system counts unique UIDs within a billing period, and resets the count to zero at the start of the next billing period.

Properties

The UID parameter:

• Is an alphanumeric string passed to Beefree SDK throughout the .

• Has a minimum length of 3 characters.

• Can contain letters from a to z (uppercase or lowercase), numbers and the special characters “_” (underscore) and “-” (dash).

• Make sure that you pass a string, not a numeric value. So even if your UID is a number, pass "12345" and not 12345.

• The UID should not be Personal Data, as indicated in the Beefree SDK License Agreement. Further information about how your use of a Beefree SDK service relates to the EU’s General Data Protection Regulation (GDPR) may be found . Our Privacy Policy, which describes the processing activities carried out by Beefree SDK as Data Controller, is available .

Unique identifier

It uniquely identifies a user of the application. When we say “uniquely”, we mean that:

1. It will be counted as a unique user for .

2. Images (and other files) used by the user when creating and editing messages will be associated with it and not visible to other users (when using the default storage).

Users, sub-users and client accounts

It’s entirely up to you, as the host application, to determine when to use a new UID at the time you initialize the editor for your users. In 99% of the cases: one UID = one CLIENT ACCOUNT in your application. Sub-users of a client account typically share the same UID.

A quick example to help you visualize this.

• We use the UID in the File Manager to identify where images will be stored

• You typically don’t want client ABC to see client XYZ’s images

• So you will use a certain UID for client ABC and another UID for client XYZ

• If there are 5 users within client ABC account in your application, however, it’s OK that they see the same images, since they are likely collaborating on the same emails or landing pages, so you don’t need to use a different UID: all 5 will share the same UID.

Development Applications

UIDs in production are counted separately from UIDs in a . For example, if you have the following UID in both a production and development application, the unique UID will be counted twice toward your plan's allotment.

In this scenario, Beefree SDK will treat these as two distinct users, and count this UID twice—once for each environment. Reference for more information on Beefree SDK plan types and their corresponding uid allotments.

Hosting Options Overview

Saved Rows in Beefree SDK empower users to save, reuse, and organize design elements efficiently, which optimizes the creation process for emails, pages, and popups. With Saved Rows, users can categorize rows by themes or criteria, ensuring easy access and consistency across projects.

Beefree SDK offers two hosting options: and . Each option has unique advantages suited to specific organizational needs, resources, and technical requirements. This guide compares the options, helping you choose the best fit for your team.

Hosted Saved Rows

Hosted Saved Rows offers a fully managed solution, eliminating the need to set up and maintain backend systems. With this option, Beefree SDK handles storage, security, scaling, and updates, allowing your team to focus on delivering a great user experience. In addition to managing storage, this option also provides you with a ready-to-go user interface made available to your application's end users through a toggle in the Developer Console.

This ready-to-go UI enables application end users to:

• Save a row and make it available for reuse in the future

• Add new saved row categories to organize the rows they save

• Edit a saved row's existing name and category

• Delete a saved row

• Update existing saved rows with the option to save them as new saved rows

Key Benefits

• Fully managed by Beefree SDK, and activated through a toggle in the Developer Console.

• Ideal for teams that want a quick setup without maintaining backend systems.

• Offers centralized storage, security, and reliability, while also providing a user interface to save and reuse rows within your application.

Self-Hosted Saved Rows

Self-Hosted Saved Rows gives teams complete control over how Saved Rows are stored, managed, and secured. This option is best for organizations with specific compliance or integration requirements, and those with the resources to manage backend systems effectively.

Key Benefits

• Allows full control over where and how rows are stored.

• Suitable for teams with specific compliance or integration needs.

• Requires development resources for managing row storage, and creating a user interface to manage and reuse rows.

Self-Hosted vs. Hosted Saved Rows

Both options allow end users to save and reuse rows on the frontend, but the best hosting option for your team will depend on your priorities concerning setup complexity, development resources (for storage and building a UI), and ongoing maintenance.

Next Steps

• Explore

• Explore

Overview

Setting up two-factor authentication will keep your developer account extra secure. Two-factor authentication means that users will need to provide two different identifications to log in to their : their regular login credentials, and a token generated by a two-factor authentication app.

When 2FA is set up, users will need to:

• download a two-factor authentication app to their mobile device (e.g. , , , and others);

• use their device and the app to generate a token and log in.

Setup for Account owners

If you’re an account owner (i.e. the user who created the Beefree SDK account), you may require all account users to use two-factor authentication to log in. To do so, go to the Setting & Security section in your personal area and enable Require two-factor authentication at login.

After saving the setting, you will be prompted to scan a QR code with a 2FA application to generate a security token to complete the setup.

When this setting is ON:

• every user will need to enter an authentication token, generated with a 2FA mobile app, to log into the account;

• when you create a new user, the 2FA toggle will be set to ON by default.

When adding or editing a user, you may also decide to turn on or off 2FA for that user, in order to:

• turn on 2FA, when 2FA is OFF at the account level;

• turn off 2FA, when 2FA is ON at the account level.

Setup for Account admins

If 2FA is OFF at the account level, additional users, i.e. admins, can turn on 2FA for themselves, for their peace of mind. They can go to the “Profile” section of their personal area and turn it on.

Width settings

Let’s start by looking at some of the peculiarities of the Popup builder.

In Email and Page Builder, the content area width is saved in the template. For example, if you start with an empty template, a default width that works for most scenarios is chosen, but the designer can adjust the message width slider. If you start with an existing template, the content width was chosen by the template’s designer using the message width slider in the builder Settings tab.

With Popup Builder, the same template may have multiple contexts, and each context will likely have specific size requirements. For example, an exit-intent popup may have a max-width of 600px on a desktop with a classical layout centered on the screen. On the other hand, the host app may display the same template on mobile in the bar style docked at the bottom of the screen with a restricted width of 300px.

Since the content area’s width is tightly coupled to the context and layout, no one size fits all width is saved in the template. Instead, the host app will specify the width settings when the builder loads, based on the context of using the template. Here is a quick example:

workspace: {
  popup: {
    contentWidth: 600,
    contentWidthMobile: 300
  }
}

Two final notes:

• Popup Builder does not currently support fluid 100% width content.

• If you don’t specify a width, the application will apply a default one.

Layout settings

As mentioned before, you will receive a ready-to-go design experience when no settings are provided. The default layout is a classic centered modal with a fixed width.

If the default popup style and layout suit your needs, then your customers are all set to start designing! You can load the builder without additional configuration and use the same standard controls and callbacks to access the HTML and JSON template.

What if you like most of the defaults but want to do some minor adjustments? We have you covered!

Changing the background

You can easily change the background to make the workspace look like the destination page where your customer will embed the popup.

beeConfig: {
  ...
  workspace: {
    popup: {
      backgroundImage: 'https://.../background.png',
      backgroundImageMobile: 'https://.../background.png',
      ...
    }
  }
}

If this option is not set, then we will provide a default skeleton layout. It’s worth noting at this point that you can apply every setting for both desktop and mobile design modes. That means you can have a different background when editing in Mobile Design Mode.

Applying a preset layout

One of the most common needs is changing the popup’s default-centered position to better match the end-user’s use case. Out-of-the-box, the Popup Builder comes with many of the most common popup layouts preconfigured. You can use any available presets “as is” or use them as starting points that you can fine-tune to your satisfaction.

beeConfig: {
  ...
  workspace: {
    popup: {
      layout: 'bar-top'
    }
  }
}

Here is a complete list of preset layouts:

Development Applications

Development applications are available with any Beefree SDK paid plan.

What is a Development Application?

A development application is a child application that is linked to your parent application within the Beefree SDK console. The purpose of these child applications is to create development, QA, or any other type of applications that you can merge your application’s changes to prior to pushing them to production. This empowers you to test new features, even on a higher plan, within a controlled environment prior to releasing them to your application’s end users.

How to Create a Development Application

You can create a development application within your Beefree SDK console. Prior to creating a development application, ensure you have a paid plan with Beefree SDK. Development applications are only available on paid plans.

To create a development application, take the following steps:

1. Log in to your Beefree SDK Developer Console

1. Create a new application

1. Navigate to your dashboard where the new application is located

2. Click the + next to Add a development instance

1. Type in the name of your development application, for example “development environment” or “QA environment”

1. Click Create

2. View the new development application available in your Beefree SDK dashboard

Benefits of Development Applications

There are multiple benefits to utilizing development applications. A few of these benefits are the following:

• Merge and test changes to your application prior to releasing them to your end users.

• Create an environment for different contributors in your development cycle, for example QA Engineers, frontend developers, backend developers, and so on.

• Access next tier Beefree SDK features in your development applications.

• Create as many child development applications linked to your parent production environment as you’d like.

Important Considerations

Consider the information outlined in this section when working with development applications.

Testing next-tier features in your development application

Beefree SDK lets you explore higher-tier features in your development environment for testing purposes. However, these features cannot be deployed to production unless they are included in your current subscription plan.

To use higher-tier features in production, you must upgrade to the appropriate plan.

Development apps inherit the same plan that your production app is on. If you wish to test features that are available on a higher plan, go the application details and click “CHANGE PLAN” in the upper right.

Usage-based fees on development applications

While setting up a development application is a feature on paid plans, please note that usage-based fees still apply. If, in your development application, you're using any of the Beefree SDK features that generate usage-based fees, that usage will count towards your plan's monthly allotment. You'll be charged usage-based fees if your usage (across production and development applications) exceeds your plan's allotment. Learn more about usage-based fees. You can view usage statistics for your development applications by logging into the Beefree SDK Developer Console, locating the development application you are working with, and looking at the Statistics widget on the application details page.

How it works

Our builders offer ready-to-go rows to your end-users, which provide both structure and content to create contents faster. With Edit Single Row mode you can offer an easier way for your users to modify a single row with a tailored UI built to edit the row structure, content, and style settings without worrying about messing up with the overall design of the email campaign, landing page, or pop-up.

Edit Single Row mode complements the Saved Rows as it allows a complete control over the content of individual rows (e.g. the footer that requires to be updated) without the need to intervene into a full template, this will help you in implementing a more effective way to manage libraries of Saved Rows with a streamlined design process.

Initializing the editor in Edit Single Row Mode

type ClientConfig = {
  workspace?: {
    editSingleRow?: boolean
    // ....
  }
  // ....
}

const beeConfig: ClientConfig = {
  workspace:{
    editSingleRow: true
    // ....
  }
  // ....
}


// Create the instance 
function BeePlugin.create(token, beeConfig, (beePluginInstance) => { 
  //.... 

  beePluginInstance.start(template, { shared: false })
}

When a builder application is initialized with this mode enabled the UI will show to the user only properties that pertain to editing a single row, therefore:

• the options to insert custom rows, saved rows, or new default rows are disabled,

• the Settings tab is unavailable, as those properties are specific to the entire document,

• when a row is selected on the editing stage, the action to Delete, Duplicate, Comment, Save are not available.

Implementing the Save action

The following describes the recommended workflow to implement the Save action in your host SaaS application when the Single Edit Row mode is enabled.

In case your application uses the default Toolbar, you can leverage the save button to trigger the sequence of action to correctly save the row, the workflow is the same as the one documented in saving-rows-workflow-for-developers, in short :

1. The user clicks on the save button

2. A contentDialog of type saveRow will be triggered.

In case your application doesn’t use the default Toolbar you will need to handle the row saving in a different way, following a couple of examples:

• Calling the save method. It will trigger the on onSave event with two arguments, one of them is the full message JSON that can be saved as a Saved Row (it’s the same JSON returned by the onSaveRow event).

Example:

myCustomToolbarButton.onClick(() => beePluginInstance.save())
...

onSave: function (json, html) {
	myCustomApi.saveRow(json)
},

• Listening to the onChange event. It will receive the updated full message JSON which again can be saved as a Saved Row.

Example:

onChange: function (json, response) {
	myCustomApi.saveRow(json)
},

Merging saved rows in existing messages

An effective way to update saved rows across multiple templates is by implementing the save action in combination with the Content Services API, to handle a row update across multiple existing templates.

Advanced options are available with Beefree SDK. Learn more about the advanced options you can integrate within your web application. Beefree SDK's advanced options include the following capabilities.

Many digital marketing campaigns start with an attention-grabbing popup. In fact, many such campaigns include a popup, a landing page, and one or more emails.

• A cool popup highlights something that the reader may be interested in

• A landing page provides more information and includes some sort of signup form

• Emails are sent to follow up.

Emails, pages, popups: three pillars of all sorts of digital marketing initiatives. Since Email Builder and Page Builder were already part of the Beefree SDK family, the natural next step was to create a Popup Builder. So here it is! This new version of the builder brings effortless popup creation inside your application.

Why Popups?

A popup is a small window that appears on a website visitor’s screen, asking for an email address in the most basic interaction or other actionable messages when using more sophisticated strategies (targeted promotions, social evidence messages, shopping cart recovery, etc.).

Popups are one of the most used online marketing tools. When done right, they capture visitors’ attention at the right moment, and push them forward in the customer journey. Despite attracting criticism in the past because they create a barrier between visitors and content, there’s plenty of evidence that they work. They will continue to play a strong part in any modern-day marketing strategy. if you’re interested in learning more.

With this in mind, we have developed an embeddable solution for designing popups that you can easily deploy because:

• it’s built from the ground up to integrate seamlessly with your application;

• it’s easy to use, offers tons of design flexibility, and builds upon the same UX your customers already know from our Email & Page Builders;

• all data stays in your application, and you don’t have to ask your customers to use 3rd party tools for building popups. You can leverage our to add forms to popups

Sample workflow

In terms of packaging the final output, Beefree SDK takes care of the Popup design and returns a solid HTML output ready to be injected on a website. On top of that, you can enrich the building experience by creating a workflow that will add to that output:

• Showing/closing behavior (e.g. display after N seconds, exit intent)

• “Additional” styles, for things like

  • Close button

  • Border radius

  • Drop shadows

The good thing: you can pass additional styles to your application, so they will reflect into the editing experience. You will then take the HTML produced by Beefree SDK and apply these styles for the final output.

Main features

Our drag&drop experience, loved by millions of users

There are over 4,500,000 sessions of our drag-n-drop email & landing page builders every month, across hundreds of applications around the world. Popup builder brings the same, great user experience that transforms non-designers in masterful content creators.

What you see is what you get...finally for Popups

You can load your customers' website home page as a background, so they can design a popup in the exact context where it will be used. And with Mobile design mode, your users are one click awaying to seeing and perfecting how the popup looks on mobile devices.

Designed to fit any configuration workflow

Position, size, background color, and more. Customize the builder each time to match how your customer configured their popup inside your application. What this means for you is flexibility, peace of mind, and implementation speed.

Ready-to-go HTML output

Get a solid HTML output ready to be injected on your customer’s website. Your application controls the display and behavior conditions, Beefree SDK takes care of the content.

Drop personalized content in popups, in minutes

Personalization is the secret weapon to attract any audience. With Merge tags and Display conditions your customers can show the right message at the right time, with use cases like product recommendations and personalized discount codes.

Speed up the creation process with shared and pre-made assets

Your customers will never have to recreate the same content over and over again. They can apply the same saved rows already available for emails, landing pages or other popups. Plus, you may also provide custom rows with ready-made dynamic content like coupon codes and best-selling items.

Overview

This page discusses how to use the HTML Importer API endpoint. Follow the instructions outlined in this page to successfully perform API calls.

Prerequisites

Prior to performing an API call, ensure the HTML you are using in the body of the POST request meets the following requirements:

• DOCTYPE declaration

• Include html and body elements

• To prevent character encoding issues during the conversion, include the <meta charset="UTF-8"> tag in the head section of your HTML before converting it.

Steps to perform the API call

Take the following steps to perform the conversion:

1. Ensure your API method is set to POST

2. Enter the endpoint URL: https://api.getbee.io/v1/conversion/html-to-json

   • Note: You can do this by setting {collection} equal to conversion in the following url: https://api.getbee.io/v1/{collection}/html-to-json

3. Authenticate by entering your API key as a Bearer Token in the Auth Type field

4. Ensure your request body's Content-Type is set to text/html

5. Paste the HTML you'd like to convert into the request body field and ensure it meets the requirements outlined in the

6. Click Send

Within a few seconds, you should receive a response containing the Beefree JSON.

Test the endpoint here

You can test the endpoint in the following interactive environment. Ensure you follow the steps outlined in the to successfully execute the API call after clicking the Test it button. You can copy and paste the HTML in the Sample HTML Template to Convert expandable section below, or use your own HTML as a request body for experimenting with the Test it feature.

Form fields that can be edited

The following table provides an overview of the form fields that support the edit form field modal, including a description of each field and an example of its content.

Form fields that cannot be edited

The following table provides an overview of the form fields that do not support the edit form field modal, including a description of each field and an example of its content.

Overview

Hosted Saved Rows offers a fully managed solution, eliminating the need to set up and maintain backend systems. With this option, Beefree SDK handles storage, security, scaling, and updates, allowing your team to focus on delivering a great user experience. In addition to managing storage, this option also provides you with a made available to your application's end users through a toggle in the .

This enables application end users to:

• Save a row and make it available for reuse in the future.

• Add new saved row categories to organize the rows they save.

• Edit a saved row's existing name and category.

• Delete a saved row.

• Update existing saved rows with the option to save them as new saved rows.

Key Benefits

• Fully managed by Beefree SDK, and activated through a toggle in the Developer Console.

• Ideal for teams that want a quick setup without maintaining backend systems.

• Offers centralized storage, security, and reliability, while also providing a user interface to save and reuse rows within your application.

• Allows for advanced controls through configuring .

Webinar Tutorial

Learn more about how to enable and customize Hosted Saved Rows in the following video. The webinar discusses:

• How to enable Hosted Saved Rows

• How to use with Hosted Saved Rows

• How to restrict which end users can save rows

• How to customize the modals related to Hosted Saved Rows

• How to use Hosted Saved Rows with

Reference the to follow along with the webinar tutorial.

Enable Hosted Saved Rows

To enable Hosted Saved Rows for your application, follow these steps:

1. Log in to the .

2. Navigate to the application you'd like to configure Hosted Saved Rows for.

3. Click on Details.

4. Navigate to Application configuration and click View more.

5. Scroll to the Saved Rows section.

   1. Toggle on the Hosted on the Beefree SDK Infrastructure option.
   2. Read the pricing information in the popup closely, because additional fees may apply.*
   3. If you'd like to proceed, confirm you read and understand the pricing to activate the feature.

*Hosted Saved Rows have the following pricing structure:

Note: Visit our to learn more about Hosted Saved Rows pricing.

Once you've successfully enabled Hosted Saved Rows in the , you'll access the following:

• Rows saved by your application's end users will be stored and hosted in the Beefree SDK storage option.

• End users can save rows directly to the hosted infrastructure and retrieve them as needed.

Deactivating Hosted Saved Rows

If you decide to deactivate Hosted Saved Rows:

1. Return to the Beefree SDK Console.

2. Toggle the Hosted on the Beefree SDK Infrastructure option to off.

3. Save your changes.

What Happens When Deactivated

• Hosted Saved Rows are removed from visibility in the builder.

• After 90 days, all Hosted Saved Rows data is permanently deleted unless the feature is reactivated.

Troubleshooting and FAQs

Can I reactivate Hosted Saved Rows after disabling it?

Yes, if reactivated within 90 days, previously Hosted Saved Rows will be restored. To fully restore rows across all applications, re-enable Hosted Saved Rows for each application.

What is a Hosted Saved Row?

Beefree SDK has introduced an updated version of the popular Saved Rows feature called Hosted Saved Rows. With this feature, Beefree SDK is responsible for storing Saved Rows in its own S3 Bucket and handling all the necessary steps for allowing your users to save and reuse rows.

What are the biggest benefits of this feature for your end users?

End users can now easily save and reuse rows across multiple designs, including emails, pages, and popups. They can quickly find and manage Hosted Saved Rows by category.

What is the difference between Hosted Saved Rows and Self-Hosted Saved Rows?

The benefit for your users remains the same—they can save and reuse rows instead of rebuilding them every time. The only difference is that with Hosted Saved Rows, you don't have to develop all the necessary steps within your application on your own. All you need to do is activate the feature through a toggle in the .

Where are the Hosted Saved Rows stored?

We will store your end users' Hosted Saved Rows in a Beefree S3 Bucket. Each row will be exclusively used for the given UID belonging to the subscription.

Color picker palette overview

The builder’s color palette gathers a list of the default colors to display from multiple sources in order to create a convenient palette of color selections when the editor loads.

Specifically, colors are gathered as follows:

• 3 colors from the body (message background, content background, link) + black (#000000)

• custom colors (as many as customers want)

• 7 most recently used colors

Use the options outlined below to customize the default color palette.

Choosing the default colors in the color picker

The builder allows you to configure a custom color palette (per user), by modifying the client-side configuration. This, for instance, allows you to provide users with easy access to their company’s brand colors.

If no color profile is provided, then the builder will continue to suggest a color palette based on the colors used in the template that is being loaded.

Advanced Permissions for the Color Picker

Through setting for the color picker, you can control the visibility of, and access to, color codes, the slider, and swatches that appear within builder. These customization options enable you to control access to various elements of the color picker for different end users of your application.

A few of the benefits of applying advanced permissions to the Color Picker are the following:

• Enhanced brand control – Gain granular control over color selection to ensure brand consistency.

• Improved user experience – Streamline the interface by showing only necessary elements.

A few scenarios in which these advanced permissions are particularly helpful include the following:

• Customizing the color picker UI based on user roles or workflows.

• Hiding unnecessary UI elements to improve accessibility and reduce distractions.

• Enforcing strict brand color guidelines by limiting available color options.

Configuration Steps

Take the following steps

1. Update the beeConfig File: Open the beeConfig file and locate the section for advancedPermissions. Within this section, ensure there is a field for components and add a new entry specifically for the colorPicker.

2. Define Permission Settings: Within the color picker section, specify the necessary parameters that determine user access. Set the relevant parameters to either true or false, depending on whether the feature should be enabled or restricted for the end user.

Code Sample

The following code sample displays an example of how to add advanced permissions for the color picker to your configuration.

Available Settings

The table below outlines the configurable parameters for the color picker.

Disabling the color history

The builder will remember recently selected colors and add them to your color palette. If the browser’s privacy settings allow it, the color picker history will be saved in the browser’s local storage.

If you want the color palette to be static such that recently selected colors are not included, then you can disable the history in your configuration.

Disabling the template's base colors

The builder by default adds colors found in the template’s body section to the color palette.

If you want the color palette to only show the colors you pass in via the bee config document, then you must disable the base colors.

Overview

With Meta Tags, you can now apply various tags to your HTML that can greatly benefit your SEO and accessibility needs.

These Meta Tags include:

• Title

• Description

• Subject

• Preheader

• Language Attributes

For the Email Builder, Meta Tags promote improved deliverability performance. For the Page Builder, Meta Tags promote greater customization and improved search engine results.

Page Builder

The following image displays the Title and Description fields from within the page builder.

Title

A page title, also known as a Title tag, is a short description of a webpage that appears at the top of a browser window and in SERPs (Search engine results page). This is an important element of an optimized SEO page, as it affects the page ranking in search engines. The title tag will be located within the <title> element of a page’s HTML output, and its value will be saved inside the JSON template.

Here is an example of what a Title Tag inside Beefree SDK’s HTML output might look like:

Description

The description tag is located within the <meta> tag element of a page’s HTML, and it has a limit of 190 characters. The tag will be located within the <meta> element of the page’s HTML output, and its value will be saved inside the JSON template.

Here is an example of what a description tag inside Beefree SDK’s HTML output might look like:

JSON Page Builder Example

The following code snippet is an example of what the Meta Tags will look like inside the JSON.

Email Builder

The following image displays the Subject and Preheader fields from within the email builder.

Subject

The subject field has a maximum of 190 characters. Here is an example of what a subject tag inside Beefree SDK’s HTML output might look like:

Preheader

The preheader field has a maximum of 130 characters. Here is an example of what a preheader tag inside Beefree SDK’s HTML output might look like:

JSON Email Example

The following code snippet is an example of what the Meta Tags will look like inside the JSON.

Language Attribute

The HTML lang attribute is used to identify the language of text content on the web. This information helps search engines return language-specific results, and it is also used by screen readers that switch language profiles to provide the correct accent and pronunciation for accessibility purposes.

When loading the builder, the host application can specify in the configuration a list of languages for their users to choose from (e.g. en-US), see the example below where the only option “Italian, it-IT” is provided. If there are no values provided via configuration file, a standard list of common languages will be provided.

Here is an example of what a language attribute inside Beefree SDK’s HTML output might look like:

Managing assets with File Manager

The File Manager can be launched as a standalone application. This means that users can access the File Manager directly, without having to first launch the builder application. This is useful for situations where a user needs to quickly upload or manage assets, but doesn’t need to create a full email, landing page, or popup.

Instead of having to switch between different applications or tools, they can access everything they need from one centralized location. This can make the asset management process more streamlined and efficient, which can ultimately help users be more productive.

Testing and integrating the File Manager

When you create an application in the , you’ll have the option to create a File Manager application.

Paid applications also include the option to create child development applications. These child applications can be used for new feature testing, development, and maintenance. By creating a child application, developers can easily test and iterate on new features without affecting the main application. This can help to minimize downtime and reduce the risk of introducing bugs or errors into the production environment.

The child applications can also be used for ongoing maintenance and updates. Instead of making changes directly to the production environment, developers can make updates and improvements in the child application, test them thoroughly, and then deploy the changes to the main application once they have been fully vetted. This can help to ensure that the main application remains stable and functional, even as new features and updates are introduced.

File manager applications share the same core functionalities as all other builders. These functionalities include authentication and configuration, which are necessary for the development process. If you have already integrated another builder into your workflow, you can easily re-use most of your work by using the same configuration for the file manager application.

For those who are new to our platform, our documentation includes a comprehensive section that provides detailed instructions on how to set up and use our builders. This section is applicable to all products.

File Manager and all builders are available to customers under the same Please contact your Customer Success Manager for more details.

Configure "Insert" and "X" Buttons

This section outlines steps to add the “Insert” and “X” buttons to your application’s user interface. These steps are specifically for the file manager.

Take the following steps to define the `onFilePickerInsert` and `onFilePickerCancel` properties to enable an “Insert” button and “X” button in the file manager user interface:

1. Ensure that you have initialized the Beefree SDK and have a reference to the SDK instance (`bee`).

2. Define the `onFilePickerInsert` property with a callback function that will be invoked when the user wants to insert a file. This function will receive the selected file data as the only parameter. You can use this data to perform any necessary actions, such as inserting the file into the editor or displaying a preview.

Here is an example of how the callback function can be defined:

1. Define the `onFilePickerCancel` property with a callback function that will be invoked when the user wants to cancel the file picker. This function does not receive any parameters. You can use this callback to perform any cleanup actions or provide feedback to the user.

Here’s an example of how the callback function can be defined:

1. Assign the defined `onFilePickerInsert` and `onFilePickerCancel` callbacks to the corresponding properties in the Beefree SDK configuration. Make sure to include these properties when initializing the Beefree SDK.

Here is an example:

By following these steps, you will be able to define the `onFilePickerInsert` and `onFilePickerCancel` properties in the Beefree SDK configuration and enable the “Insert” and “X” buttons in the file manager user interface. You can customize the callback functions to suit your specific needs and perform any desired actions with the selected file data or when the file picker is canceled.

Storage Options

When configuring a builder application with Beefree SDK, you have four image and file storage options:

1. Beefree SDK Storage: Default option. Images are hosted in Beefree SDK’s AWS S3 bucket. Potential fees apply for usage beyond the included limits.

2. Existing Storage Application: Connect your builder to an existing storage application to share storage resources.

3. Own AWS S3 Bucket: Use your own AWS S3 bucket instead of Beefree SDK’s. Follow the documentation to configure this option.

4. Own File System: Integrate your application’s existing file system for storage. This option is available on Beefree SDK paid plans.

Reference the to learn more about how to configure storage for your File manager application.

Overview

Your users will have the ability to rewind and fast-forward to any point in their recent edit history. Once Undo is enabled in the , the application immediately begins tracking changes. Behind the scenes, this is accomplished via a new callback event – – which can also be used “stand-alone” without enabling Undo. No client-side configuration is required to use this feature. Continue reading to learn how to activate and use Undo. And if you can’t wait to try it yourself, you can immediately do so at

How it works

When changes are detected, a compact Undo widget displays in the bottom left corner of the stage:

The widget displays 3 actions:

• Undo and Redo arrows that offer the classic pattern to move back and forth between changes.

• A history icon that expands a timeline of the latest changes:

Timeline

The timeline allows the user to browse through the most recent changes.

All the steps display:

• An icon to identify the content element type (an image, text, etc.)

• A description of what changed, giving the new property value (if any)

• The exact time it happened

All these details provide enough information for users to understand what modification was applied, and, if desired, rewind the message to that state:

When the user selects a previous step, the content or row that triggered the history record displays as the selected item, providing further context.

The timeline for more recent changes is still available, allowing the user to move forward without losing any changes:

The Undo widget currently displays the last 15 edits in the timeline, but users can always rewind to the Message opened state to undo all changes since the message was initially opened in the builder.

We are also doing additional testing to see if the number of recent edits can be increased beyond 15 without negatively impacting the browser’s performance. We will update this section if the number is increased.

The last saved edits are only available at the session level, so they reset every time the builder is loaded. If you need to provide a complete message history, you can build a custom one based on the onSave and onChange events (see below).

Activating the Widget

The Undo option is available at the application level in the . Select your application from the list and open the Application configuration in the bottom-right. The option to enable this widget is available in the Services list:

The widget uses the information to work. However, it doesn’t need a client-side configuration for the callback: once Undo is enabled, the application starts tracking changes even if the is not set in .

Toolbar Options

In the Toolbar Options tab you can:

• control individual settings that affect the top toolbar in the builder

• decide whether to hide the toolbar completely

The toolbar contains all the actions not related directly with content edition, like save, send a test or preview.

You can decide the inner elements from it, from hiding our brand to removing the save button, to create the builder version that better fits in your application.

Not enough? Remove the toolbar completely and offer all the actions with your own UI elements.

Remove Toolbar and Create Custom UI Elements

For example, in our MailUp App for Shopify, we hide the toolbar completely and control the builder (Show preview, Send test, Save) from buttons in the app UI (not in the builder). Here is how it looks.

If you decide to go this route, use the to control the builder from your UI.

Overview

Smart merge tags provide a better way for your customers to leverage personalization when creating content with Beefree SDK.

With Smart merge tags, users can:

• quickly identify merge tags through a specific highlighting

• see human-friendly names instead of the raw syntax – e.g., Customer Name instead of {%customer.name%}.

• select, replace, and style merge tags with just one click

• get sample content for each merge tag, both during editing and preview.

How it works

After enabling Smart merge tags, the builder will:

• highlight merge tags with a dotted border

• display the tag name you passed instead of the raw syntax

When users click on a tag, its border will become solid to signify that it has been selected. After selection, users can style, replace, or delete the merge tag with just one click.

Smart merge tags are easier to identify inside the content you’ve created and will save users tons of time. Furthermore, hiding the syntax will make it impossible for a user to break it while interacting with the overall text element.

On top of this, you can pass sample content for each merge tag, so that users can see an example of the data that will take the place of the merge tags when the web content is rendered:

How to enable it

Smart merge tags are disabled by default. If your application doesn’t have Smart merge tags, you need to activate it. It takes just a few clicks:

• Click Details next to the application you want to configure

  • We recommend you first familiarize yourself with this feature under a DEV or QA application

• Click view more under Application configuration.

• Under the Services section, toggle Enable Smart merge tags ON and click the Save button.

Notice that, at this point, you will be prompted to enable the merge tag preview in the toolbar. You can skip this option when your integration is not using the or you’re not passing sample content for your .

Configuring sample content

After enabling Smart merge tags from your developer account, you need to apply a minor change to the merge tags’ .

The optional previewValue parameter is used to pass to the editor a sample content (text string) for every merge tag.

The value of this new parameter will replace the merge tag in the editor preview, meaning that there’s no need to build a custom preview to display the final result of an email or landing page with rich personalization strings.

Displaying sample content during editing

Sample content strings are not limited to the preview, but can be displayed in the editor’s stage as mentioned above.

The way to do this depends on how your integration manages the .

Toolbar enabled

In this case, you can simply enable the option “Show ‘Merge tag preview’ in toolbar” mentioned above.

When this option is active, the toolbar displays a new action to the user:

The option works as a toggle that alternates between displaying the previewValue and the name parameter inside the merge tag UI.

Toolbar disabled

As with all the actions available in the toolbar, to control this option from your own UI:

Use this method to replicate the behavior described for the standard toolbar.

Saved Rows Overview

This page provides an overview of Saved Rows and their key benefits.

What Are Saved Rows?

Saved Rows in Beefree SDK optimize the content creation process by allowing users to save, categorize, and manage reusable rows for future use. When this feature is enabled, users can simply click the Save icon on a row within their design and store it for later. This ensures quick access to preferred layouts and design elements across multiple projects.

Save Rows are particularly helpful in the following scenarios:

• Standardizing Footers: Save a footer row with contact details, social media links, and copyright information. Use it across multiple email templates to ensure consistency.

• Designing E-Commerce Product Grids: Create reusable rows showcasing product images, descriptions, and call-to-action buttons. Pull these rows dynamically from an e-commerce catalog for up-to-date content.

• Creating Promotional Banners: Save promotional rows with pre-configured styles and messaging. Reuse them across campaigns to maintain branding and reduce setup time.

Benefits of Saved Rows

There are several benefits to utilizing saved rows. This section outlines benefits for both end users and the host applications.

Saved Rows enable end users to:

• Save and reuse content: Create emails, landing pages, and popups, apply their own style and brand guidelines, and save all of that hard work inside of a row and reuse it at a later date. After saving a row, they can still edit the row and make any adjustments to the content blocks inside of it.

• Flexible Categorization: Organize rows into intuitive categories to easily find and reuse them later on.

• Easily Manage Rows: Edit the name and category of a saved row easily. Or, delete rows if they are no longer needed.

Saved Rows enable host applications to:

• Enhance the User Experience: Enable users to save, categorize, and manage rows efficiently.

• Multiple Storage Options: Activate, store, and manage Saved Rows using either or options.

• Customize Permissions: Enable or disable end user permissions to delete, edit, manage, or add Saved Rows.

• Make Saved Rows Available to Select Users: Control which users can and cannot save rows.

How Saved Rows Work

When enabled, Saved Rows allow end users to select a row in their design and save it. This process involves:

1. Selecting a row in the builder.

2. Clicking the Save icon in the toolbar or row properties panel.

3. Storing the row’s structure, content, and styles as a JSON document in your chosen storage solution.*

Using Saved Rows

Once created and saved, end users can reuse saved rows through the builder’s ROWS tab.

There, users can:

• Browse saved rows by category.

• Search for rows using metadata like row names or descriptions.

• Drag and drop rows into their designs for immediate use.

Activation and Storage Paths for Saved Rows

There are two paths you can take to activate and store Saved Rows for your application:

Both paths provide their own set of benefits and limitations. It is important to familiarize yourself with the benefits and limitations of each option to choose the storage and activation solution that is best for you and your application's needs. For more detailed information on both activation routes, reference and Implement .

Learn more about to discover the best option for you.

Beefree SDK offers a comprehensive suite of features that enable your application's end users to save and manage reusable content. Rows are a core feature of the visual builders within Beefree SDK that provide end users with an intuitive avenue for saving and reusing content throughout their design creation workflows. They provide a structured method to house various types of content such as headers, paragraphs, images, and buttons.

Rows are also a fundamental part of how designs are built and structured within the visual builders. In the following GIF, you can see how each row functions as a component of a continuous design.

Rows allow end users to add multiples types of content to a section of a design. End users can either create their own rows from scratch (and save them for reuse on a later day), or they can use pre-designed rows that are pre-loaded into the host application and ready for use. Pre-loaded rows are helpful when providing a template structure that end users can customize as they build their designs.

Providing end users with the option to easily reuse content comes with a host of benefits, including:

• Pre-designed and customizable content: End users can select from rows that already contain content, which they can then customize for their specific needs.

• Flexible structure: Rows help organize different content types in a structured layout, which promotes a clean and efficient design.

• Drag-and-drop functionality: Rows can easily be dragged and dropped onto the stage.

• Continuity with current user experience: End users can add empty structures, which preserves creativity and allows them to build and design from scratch.

• Option to disable empty rows: If preferred, end users can opt to work solely with pre-made rows, focusing on content customization without the need to build layouts from the ground up.

In addition to rows offering a variety of benefits for end users, there are also clear benefits for the host application, including:

• Ready-to-go content delivery: The host application can pass pre-built, ready-to-go rows directly into the builder, reducing the need for end users to create content from scratch.

• Customization control: Host applications can offer a variety of customizable rows, ensuring users follow design guidelines while still providing creative freedom.

• Improved user experience: Pre-designed rows simplify the user interface, making the builder more intuitive and less complex for users.

• Optional removal of empty structures: Host applications can disable empty row options if desired, encouraging users to focus on modifying pre-existing content.

• Efficient content management: Rows enable the host to provide consistent, reusable content blocks that can be updated globally, streamlining content management and maintaining design consistency across the platform.

Understanding the Different Types of Rows in Beefree SDK

This section outlines the different row-related features available within Beefree SDK. Throughout the following pages of the Rows section, we will discuss each of these different row-related features in depth, including what they are, how they look, and how to implement them if they are a good fit for your application and end users.

Custom Rows

The purpose of Custom Rows is to provide pre-configured rows that your end users can drag-and-drop into the builder and start customizing.

The following GIF provides a visual of how Custom Rows look to end users:

Custom Rows are integrated by adding the rowsConfiguration parameter to your beeConfig. The following code snippet is the one used to configure the row in the GIF above.

rowsConfiguration : {
 "externalContentURLs": [
  {
   "name": "External resource",
   "value": "https://bee-playground-backend.getbee.io/api/customrows?ids=1,2,3,4"
  }
 ]
}

Visit the Beefree SDK playground to experiment more with the Custom Rows configuration, and visit the Implement Custom Rows page to learn more about integrating this feature within your application.

Hosted Saved Rows

Hosted Saved Rows allow your end users to save and manage their own rows to be used later–a powerful way to help them streamline their workflows!

Also, Hosted Saved Rows simultaneously provides both a storage solution and user interface your application's end users can engage with to save and manage their rows.

In the following GIF, with Hosted Saved Rows, Beefree SDK provides the user interface and infrastructure to power Saved Rows so you can bring this feature to your end users instantly.

Implementing Hosted Saved Rows takes only a few seconds, because it activated through a toggle in the Beefree SDK Developer Console. The following image shows how the toggle looks like in the Developer Console.

Visit the Implement Hosted Saved Rows page to learn more about customization options and integration details.

Self-hosted Saved Rows

Self-hosted Saved Rows are similar to Hosted Saved Rows on the frontend, but require you to connect your own database on the backend. This feature also provides you with more customization options on the frontend if you'd more granular control over customizing your end user's experience saving and managing rows.

The following GIF shows an example of a customized modal for saving a row within an application. This modal uses both saved rows and content dialog for the customized experience.

Synced Rows

The purpose of Synced Rows is to maintain consistency by synchronizing row updates across multiple designs. A synced row can be reused across multiple designs and each design is updated whenever a synced row is updated. When you edit a synced row, you a redirected to Edit Single Row Mode.

Edit Single Row Mode

The purpose of Edit Single Row Mode is to allow precise editing of rows inside of a dedicated row builder. The GIF above displays an example of Edit Single Row Mode. Visit Initialize Edit Single Row Mode to learn more about how to implement this feature.

Bearer Token Authentication

Beefree SDK's HTML Importer API uses bearer tokens to authenticate requests. You can create, view, and manage your bearer token in the Beefree SDK Developer Console. All requests must be made over HTTPS and contain the following HTTP Header:

Authorization: Bearer {token}

Create a Bearer Token

To use the HTML Importer API, you will need an API Key, which is the bearer token you will use to authenticate, from the Beefree SDK Developer Console.

Take the following steps to obtain your API key:

1. Log in to the Beefree SDK Developer Console.

2. Navigate to the application you'd like to activate the HTML Importer API for.

3. Click on the corresponding Details button.

4. Navigate to the HTML Importer API section of the Details page.

5. Click Create New API Key.

   A pop up will appear asking you to confirm that you understand usage-based fees apply.

6. Click Create Key.

Your API key will appear under the HTML Importer API section of your application details.

Add JavaScript Library

Congratulations on ! Now it’s time to install it. The first step is to add the Beefree SDK library to your application. You can use our to add it. This guide discusses how you can set up a local environment, install the package, authenticate, and get started with Beefree SDK.

Introduction

Beefree SDK is an embeddable no-code content builder that enables your end users to build stunning marketing assets, such as emails, landing pages, and popups, without writing a single line of code.

The following list includes a few key features within Beefree SDK:

• Drag-and-drop visual editors

• File manager

• Multi-user collaboration

• Responsive design capabilities

• Extensive template library

• Secure authentication workflow

This guide provides comprehensive instructions and best practices for implementing Beefree SDK.

Getting Started

This section discusses how to get started with Beefree SDK.

Prerequisites

Prior to integrating Beefree SDK, ensure you have:

1. A Beefree SDK .

2. Node.js (v14 or higher) installed.

3. A modern web browser (Chrome, Firefox, Safari, Edge).

Local Development Setup

To test the SDK locally before production deployment:

1. Clone the demo repository:

2. Install dependencies:

3. Configure environment:

4. Start the dev server:

5. Access at http://localhost:8081

Package Installation

You can install Beefree SDK using either or :

Using npm

Using Yarn

Package Details:

• TypeScript Support: Included

• License: Apache-2.0

• Repository:

Authentication Process

This section discusses the authentication process.

Server-Side Authentication

The secure authentication flow requires a server-to-server call to obtain a JWT token. This process ensures your client credentials remain protected.

Authentication Endpoint

Required Parameters

The following table lists and descibes the required authentication parameters.

Example Implementation (Node.js)

JSON Authorization Response

Beefree SDK Initialization

This section discusses how to initialize Beefree SDK.

Container Setup

Create a container element in your HTML where the editor will render:

Configuration Options

Beefree SDK requires a configuration object with the following essential property:

Full Configuration Reference

The following table explains the container property.

Working with Templates

Loading a Template

Initialize the editor with a template JSON object:

Reference the in GitHub for example templates.

Template Management Methods

The following table lists template management methods that are important for getting started.

Advanced Features

Token Refresh Implementation

Implement automatic token refresh to maintain uninterrupted sessions:

How to use:

1. Get a fresh token from your backend

2. Pass it to updateToken()

Collaborative Editing

Enable real-time collaboration with these additional methods:

How to use:

1. Generate a unique session-id on your server

2. Call join() with the same ID for all collaborators

Troubleshooting

The following list includes the most common issues and steps for troubleshooting them.

• Authentication Failures

  • Verify client_id and client_secret

  • Ensure UID matches between auth and config

  • Check network connectivity to auth.getbee.io

• Editor Not Loading

  • Confirm container element exists

  • Verify container ID matches config

  • Check for JavaScript errors in console

• Token Expiration Issues

  • Implement onTokenExpired callback

  • Test token refresh flow

Frequently Asked Questions

Q: Can I use the SDK without server-side authentication? A: While possible for testing, production implementations must use server-side auth for security.

Q: How do I customize the editor's appearance? A: The SDK supports UI customization through configuration options. Refer to the advanced documentation.

Q: What happens when the token expires? A: When your token expires after 12 hours:

1. The editor will become unresponsive

2. You must proactively:

3. Best practice is to refresh tokens before expiration (recommended at 11 hours)

Q: Where can I find sample templates? A: Visit our for examples.

Conclusion

This comprehensive guide covers all aspects of Beefree SDK integration, from initial setup to advanced features.

Remember to:

• Always use server-side authentication

• Implement proper token refresh logic

• Test thoroughly before production deployment

• Monitor for SDK updates and new features

HTML

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

This endpoint allows you to retrieve the full or partial HTML output of a template (email, page, or popup).

How It Works

To generate HTML from a template's JSON:

1. Capture or store the latest JSON output from the builder using such as onChange or autosave.

2. Send this JSON payload to the HTML endpoint.

3. Receive the HTML string as the response.

Required Request Payload

• page (object, required): The full template structure in Beefree JSON format. This is the same structure returned by the builder or captured from its callbacks.

Notes

• This endpoint bypasses the need for the onSave callback and can be used at any time post-editing.

• Partial HTML rendering is also supported for specific components or modules (if required by your use case).

• The output HTML reflects the current rendering engine used by Beefree, ensuring up-to-date compatibility.

Plain Text

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

This endpoint allows you to retrieve the full or partial HTML output of a template (email, page, or popup).

How It Works

To generate plain text from a template's JSON:

1. Capture or store the latest JSON output from the builder using such as onChange or autosave.

2. Send this JSON payload to the /plain-text endpoint.

3. Receive the plain text as the response.

PDF

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

You can generate a PDF file from valid HTML content using the dedicated PDF generation endpoint. This operation requires a JSON payload with specific fields to configure the output.

Required Request Payload

Field Descriptions

• html (string, required): The full HTML content to convert to a PDF. You can obtain the HTML output of a template by calling the and copying its response into this field.

• page_orientation (string, required): Sets the orientation of the generated PDF pages. Accepted values:

  • "portrait": vertical layout.

  • "landscape": horizontal layout.

• page_size (string, required): Defines the dimensions of the PDF output. Accepted values:

  • "Letter": US Letter format.

  • "A4": A4 paper size.

  • "A3": A3 paper size.

  • "Full": a single continuous page with fixed width (900px) and height determined proportionally to the content.

Steps to generate a PDF

To generate a PDF from a template:

1. Call the /html endpoint to retrieve the template's HTML.

2. Insert that HTML into the "html" field of the request payload.

3. Set your preferred "page_orientation" and "page_size".

4. Send the payload to the PDF generation endpoint.

Image

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

This endpoint allows you to generate an image file (for example, PNG) from a template's HTML. You can control the image output by specifying the dimensions.

Required Request Payload

Rendering

The HTML is rendered using a fixed-size browser window to simulate a real-world preview. Here are the key rendering parameters:

• Window Size: 1920 x 1080 pixels (used for clipping/screenshot area)

• Default Viewports:

  • Mobile: 320px width

  • Desktop: 1024px width

• Clipping Region: defaults to 1920 x 1080 pixels

• Scale Factor: Automatically calculated to match viewport and clipping dimensions.