Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Discover the configuration parameters within Beefree SDK.
Once you have initialized your Beefree SDK application, you can pass a series of configuration parameters to it.
The following code displays an example of a default configuration:
The following table provides a list of the required parameters.
uid
An alphanumeric string that identifies the user and allows the SDK to load resources for that user (e.g. images).
Min length: 3 characters
Can contain letters from a to z (uppercase or lowercase), numbers and the special characters _ (underscore) and – (dash)
It is a string and not a numeric value
It uniquely identifies a user of Beefree SDK. When we say “uniquely”, we mean that:
It will be counted as a unique user for monthly billing purposes.
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).
container
Identifies the id of div element that contains Beefree SDK.
The following table provides a list of the language options for the language parameter. The language parameter is not required and has a default value of en-US
.
Available Languages
English:
en-US
Spanish:
es-ES
French:
fr-FR
Italian:
it-IT
Portuguese:
pt-BR
Indonesian:
id-ID
Japanese:
ja-JP
Chinese:
zh-CN
Traditional Chinese:
zh-HK
German:
de-DE
Danish:
da-DK
Swedish:
sv-SE
Polish:
pl-PL
Hungarian:
hu-HU
Russian:
ru-RU
Korean:
ko-KR
Dutch:
nl-NL
Finnish:
fi-FI
Czech:
cs-CZ
Romanian:
ro-RO
Norwegian (Bokmål):
nb-NO
Slovenian:
sl-SI
The following table provides a list of the optional parameters and their corresponding descriptions.
trackChanges
Track message changes in the editor via the “onChange” callback. See “Tracking message changes” for further details.
false
specialLinks
An array of custom links that may be used in the message (e.g. unsubscribe). See “extending the editor” for further details.
[]
mergeTags
An array of merge tags that may be used in the message (e.g. first name of the recipient). See “extending the editor” for further details.
[]
mergeContents
An array of content elements that may be used in the message (e.g. small blocks of HTML). See “extending the editor” for further details.
[]
preventClose
Whether an alert should be shown when the user attempts to leave the page before saving.
false
editorFonts
Customize the list of available fonts in the editor’s text toolbar and the BODY settings panel. See “Font management” for further details.
See “Font management” for the default object.
roleHash
Identifies the user role:
Minimum length is 8, maximum is 30
Alphanumerical string only: No whitespaces, no special characters such as “_” and “-“
See “Roles and permissions” for further details.
""
rowDisplayConditions
Allows for conditional statements in email messages. See “Display Conditions” for further details.
{}
workspace
Configure the initial workspace for loading the editor. Currently used for AMP content visibility. See “Workspaces” for further details.
{type : 'default'}
contentDialog
{}
defaultForm
{}
commenting
false
commentingThreadPreview
Enables a pop-over preview on the stage for comments.
true
commentingNotifications
Enables notifications of new comments in co-editing.
true
disableLinkSanitize
Disables link validation for URLs, including telephone number or SMS to enable merge content use.
false
loadingSpinnerDisableOnSave
Controls the visibility of the builder in a loading state.
false
loadingSpinnerDisableOnDialog
Controls the visibility of the builder in a loading state.
false
Install Beefree SDK to get started with your implementation.
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.
This section discusses how to get started with Beefree SDK.
Prior to integrating Beefree SDK, ensure you have:
Node.js (v14 or higher) installed.
A modern web browser (Chrome, Firefox, Safari, Edge).
To test the SDK locally before production deployment:
Clone the demo repository:
Install dependencies:
Configure environment:
Start the dev server:
Access at http://localhost:8081
Using npm
Using Yarn
Package Details:
TypeScript Support: Included
License: Apache-2.0
This section discusses the authentication process.
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.
client_id
string
Your application client ID
"abc123-client-id"
client_secret
string
Your application secret key
"xyz456-secret-key"
UID
string
Unique user identifier
"user-12345"
Example Implementation (Node.js)
Important Notes:
The UID must be consistent between authentication and SDK configuration.
Tokens are valid for 12 hours.
Ensure client_secret and client_id aren't exposed in the client-side code.
JSON Authorization Response
This section discusses how to initialize Beefree SDK.
Create a container element in your HTML where the editor will render:
Beefree SDK requires a configuration object with the following essential property:
Full Configuration Reference
The following table explains the container property.
container
string
Yes
DOM element ID for the editor
Initialize the editor with a template JSON object:
The following table lists template management methods that are important for getting started.
load(template)
Load new template
bee.load(newTemplate)
reload(template)
Force reload template
bee.reload(updatedTemplate)
save()
Trigger save callback
bee.save()
saveAsTemplate()
Save as template
bee.saveAsTemplate()
The instance method bee.start(template)
does not need to be called immediately after create
. In a SPA (Single Page Application) or React app, you can create
the editor in a hidden global state but then call the start
method when the template is selected and available. The application loads quickly when all steps are completed consecutively. However, by separating the loading workflow into two parts, the end-user will perceive loading in a fraction of the overall time. Remember, if the client_id
belongs to a File Manager application, bee.start()
can be called without any parameters.
Implement automatic token refresh to maintain uninterrupted sessions:
How to use:
Get a fresh token from your backend
Pass it to updateToken()
Enable real-time collaboration with these additional methods:
How to use:
Generate a unique session-id
on your server
Call join()
with the same ID for all collaborators
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
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:
The editor will become unresponsive
You must proactively:
Best practice is to refresh tokens before expiration (recommended at 11 hours)
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
Welcome to the Beefree SDK technical documentation!
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.
Take the following steps to get started with Beefree SDK in a few minutes:
Add your credentials, the Client ID and Client Secret from step three, inside the placeholders in the code.
Learn more about our three embeddable builders.
Learn more about how our builder AddOns can help you customize your application's offerings.
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.
Browse our sample code to experiment and gain hands-on experience. Get up and running quickly with a simple implementation.
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.
Learn how to create an application within the Beefree SDK Developer Console.
This article will cover steps for the following processes:
Complete the required information to sign up or login.
You will be redirected to the dashboard.
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.
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.
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.
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.
Enter and confirm your billing address.
Enter and confirm your card information by clicking Place Order.
You will be redirected your new Free plan subscription.
You will have the option to activate any or all of the following applications:
Take the following steps to create an application:
Click the Activate button that corresponds with the application you'd like to create.
Type in a name for your new application.
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.
Click on your application's Details button to view your Client ID and Client Secret. Use these to authenticate when you initialize it.
Reference the following related topics to learn more about customizing your applications, creating development instances, and referencing sample code.
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:
Navigate to the application you'd like to update the Client Secret for.
Click on the application's Details button.
Navigate to Application keys within the application's details.
Click Regenerate to generate a new Client Secret.
You will be prompted to a modal and asked to confirm your application's name.
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.
For 24 hours after regenerating a new Client Secret, you will temporarily have access to two Client Secrets—your old one and your new one. After 24 hours, you will only have access to the new Client Secret for your application.
In user interfaces, a workspace is a parameter that changes the appearance, settings, and widgets available in an builder, to help the user to focus on what matters.
In Beefree SDK, workspaces are an optional parameter that can be used to provide an experience focused on context and purpose, and to facilitate the outcome of an editing session.
You can load the builder with a certain workspace, but workspaces can also be changed by the user when editing, on-the-fly.
Switching between workspaces might change:
content visibility on the stage
tiles availability in the content tab
available previews
outputs when saving a content
…and more!
If no workspace is loaded at launch, the builder starts in its “Default” workspace.
We currently offer 3 additional workspaces, and we are planning to launch more as we evolve BEE and its capabilities.
These 3 workspaces revolve around the use of AMP content, and are provided so that you can tailor the experience of creating AMP emails in Beefree SDK.
Stage message
HTML content
HTML & AMP content
HTML & AMP content
HTML content
Content tiles
HTML content tiles
HTML & AMP content tiles
HTML & AMP content tiles
HTML content
AMP sidebar properties
No
Yes
Yes
No
Available in preview
HTML content
HTML & AMP content
HTML & AMP content
HTML content
onSave callback files
HTML
HTML & AMP
HTML & AMP
HTML
Loading a template with AMP content
The onWarning is triggered
Template loads
Template loads
Template loads
Loading a template with HTML content only
Template loads
Template loads
Template loads
Template loads
Availability of the hide on AMP/HTML property
Not available
Yes
Yes
Yes
Behavior for hidden for HTML/AMP content
The onWarning is triggered
Both are visible
Only “hidden for HTML” content is visible
Only “hidden for AMP” content is visible
Here is an example of loading Beefree SDK with a “mixed” workspace:
You can implement a workspace selector within your application, so that users can switch between workspaces, by using the loadWorkspace(type)
method.
First, you need to define template files for the workspaces you want to propose, as JSONs:
Then, you can load those workspaces at runtime:
And here is how to create a simple select to switch workspace:
After you load a workspace, the application will trigger one of these three callbacks:
The additional workspaces for AMP (AMP-only and HTML-only) can become helpful if you want to tailor the user experience of creating AMP emails, by adding:
a workflow where users decides if they want to create a standard message or an AMP-powered message (in the first case, AMP components will be hidden in the builder;
an option to switch between the HTML and the AMP editing of a message.
depending on the subscription plan that they are on (i.e. you could push users to a higher plan based on the ability to use AMP);
depending on the purchase of an optional feature (same);
only if they are “beta” customers, so they see it while keeping it hidden from the rest of your users.
Important: Do not put your Beefree SDK credentials in client-side code.
The Beefree SDK system uses OAuth2 as the authorization framework.
The following code sample displays an example JSON response.
The Beefree SDK authorization service will return a temporary access token if the authentication is successful. The client application can use the full response that contains the token to start or refresh a Beefree SDK session.
The token you receive from the authorization server should be passed to the BeePlugin.create(...) as it is. We strongly suggest not altering it in any way. Also, don’t rely on the token response's content or structure. If you do, any change to the schema could make your integration stop working.
The token expires after 5 minutes for security reasons. Beefree SDK will refresh an expired token automatically for 12 hours without re-authenticating the application. Beefree SDK will trigger the onError
callback when the token can't be refreshed automatically.
The following code sample displays an example of how to call the Beefree SDK endpoint, obtain a token, and then start it.
Ensure to call the authorization endpoint server-side to protect your credentials.
Beefree SDK will keep this session alive for 12 hours from the login. After 12 hours, you have to manage the token expiration, as follows:
Obtain a new token via the new authorization endpoint.
Inject the token obtained from step one via the updateToken
method. Reference examples of this in the following section.
The following code example shows how to inject the token in the current Beefree SDK instance:
The following code example displays how to get the current JSON from the expiration error:
When you set up an onError
callback you will get the error
object as a parameter.
From that object, you can grab the code
property and use it as explained in the table below.
The following code samples display how to handle the 5101 and 5102 errors.
Error management error 5101
Error management 5102
Example error response for unsupported media type Only Content-Type: application/json
is allowed.
Example error response for disabled apps. Contact support if you encounter this error.
Assuming that beePluginInstance
is the instance of your embedded builder application, here are the methods you can call:
If you use a paid plan, you can hide the top toolbar and control the builder from your application’s user interface. For example, it’s up to you at that point to have buttons above or below the builder. Here’s some useful methods for this scenario:
The top toolbar displayed by default within the builder contains buttons that trigger certain actions. These are the callbacks that are triggered when the buttons are clicked.
Allows to exchange data with Beefree SDK using a UI layer you control. See the “” page for the complete reference.
This should contain a structure
object with the form data.
See “” for further details.
Enables commenting on content blocks and rows. See for further details.
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.
A Beefree SDK .
You can install Beefree SDK using either or :
Repository:
Reference the in GitHub for example templates.
Q: Where can I find sample templates? A: Visit our for examples.
Beefree SDK is an embeddable no-code , and 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 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 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 that provides end users with the tools they need to build compelling popups that capture attention.
File manager: A tool to (images, PDFs, and so on).
These builders can easily integrate into your application in minutes. Browse this documentation's latest and implementation guides to get started.
Create an account to access the and obtain your credentials.
to get started. Beefree SDK offers a generous Free plan that includes each builder type mentioned in the previous section.
Create an application and .
Clone the , which includes the code for email and popup builder implementations.
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 in the beeConfig
section of the code.
You can also customize the SDK's configuration inside the under the of the application you created.
Note: Visit the for a comprehensive list of features and the plan type they correspond to.
In addition to our drag-and-drop editors, we also offer a standalone 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 and .
The 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.
Learn more about and .
Get your free Client ID and Client Secret in the to get started. Experiment with customizing a configuration in the playground. When you're ready, install Beefree SDK.
If you need support at any point throughout your integration, . We are here to support you along the way.
In this article, we will discuss how to sign up for an account in the , create an application, and obtain your Client ID and Client Secret.
The first step to embedding Beefree’s visual builders in your software is to.
Take the following steps to sign up for a Beefree SDK account and subscribe to the :
Navigate to the .
Note: If you already have an account, navigate to the .
Important: Keep in mind that Beefree SDK will not change you for using the Free plan. However, there are charges related to . Ensure you review our plans and familiarize yourself with these cost structures as you proceed to use the Free plan.
Once that’s done, you will be able to . Your dashboard will look like the following image.
With your Client ID and Client Secret, you can use our to experiment with a simple integration of Beefree SDK. You can also get started with .
Log in to the .
Create
When you load a Beefree application inside the host application, you pass a 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.
Updating available categories for
Refreshing a for authorization
Changing for the current user
Updating settings for the editor’s
Here is an overview of the different workspaces and their differences. Please for more information on using AMP in Beefree SDK.
In addition, omitting the workspace, or loading the “default” workspace for certain users, has the effect of disabling AMP for those users, even when AMP content is enabled in the . This way, you can decide to make the feature available to customers of your application:
The Authorization Process is an important step throughout your . This steps validates your Beefree SDK credentials and provides you with a token. Take the steps outlined in this document to ensure you accurately complete the authorization process.
Beefree SDK requires the host application to pass a container parameter in the This is the only required parameters for the configuration.
The following code sample shows an example of this parameter in the .
To initialize your instance of the Beefree SDK builder, call the /loginV2
endpoint shown in the sample code below with your Client ID, Client Secret, and UID. The Client ID and Secret are available on the application details page of the . UID represents your user as described in .
Reference to learn more about UID.
Note: When a refreshable token expires, Beefree SDK receives a and attempts to refresh it automatically. 401 errors are expected and part of the process.
Once you obtain the token, the object is passed to Beefree SDK to set up your customization options, for example setting the editor’s language to “Spanish”.
Then, you can use Beefree SDK methods to on your page.
Example error response for an invalid UID. Look at the properties of .
Example error response for invalid credentials. Obtain your credentials using the .
AI Writing Assistant with Multiple Provider Options
Partner AddOns
Custom AddOns
Content Services: Export plain text, transform JSON to HTML, and manage brand styles.
Template Catalog: Add templates to your application.
AI Collection: Use the AI collection to get metadata, SMS, and summary text.
Full-stack application built with NextJS
Official NPM package of Beefree SDK
A simple HTML sample client to start playing with Beefree SDK
Beefree SDK simple React starter
Templates to accelerate the set-up of your Beefree SDK integration.
Explore methods
Developer Console
Playground
Install Beefree SDK
Configuration Parameters
Create an Application
Authorization Process
5101
Expired token cannot be refreshed
You need to do a new login and update the token in the current Builder instance using updateToken
method.
5102
Expired token must be refreshed
You need to do a new login and create a new Builder instance using the new token, BeePlugin.create()
and the current JSON template present in this event
Example scenarios:
The version is outdated
Beefree SDK releases a security fix and every client must refresh
beePluginInstance.preview()
Triggers the message preview behavior within the builder.
beePluginInstance.togglePreview()
Open/close the message preview behavior within the builder.
beePluginInstance.toggleStructure()
Controls the visibility of the structure outlines in the message editing portion of the builder.
beePluginInstance.save()
Invokes the onSave
callback function. The application will pass two files to the function: a JSON file with the message structure (for later editing) and a ready-to-send HTML file.
beePluginInstance.saveAsTemplate()
Invokes the onSaveAsTemplate
callback function. The application will pass to the function a JSON file with the message structure (for later editing).
beePluginInstance.send()
Invokes the onSend
callback function. The application will pass to the function a ready-to-send HTML file.
beePluginInstance. toggleMergeTagsPreview()
Controls the visibility of sample content for merge tags in the message editing portion of the builder.
File Manager
Storage Options
Configure Your AWS S3 Bucket
beePluginInstance.start(templateToLoad)
beePluginInstance.load(template)
Loads the JSON template string specified in the template
parameter.
beePluginInstance.reload(template)
Loads the JSON template string specified in the template
parameter. Unlike beePluginInstance.load(template)
, the reload method does not trigger a loading dialog. This method helps quickly reload a template seamlessly for specific use cases, such as using a custom undo/redo feature or injecting custom content in real-time.
onSave
Fired when the Save button is clicked.
JSON and HTML documents
onSaveAsTemplate
Fired when “Save as template” is clicked.
JSON document
onAutoSave
Fired automatically based on autosave
configuration parameter value.
JSON document
onSend
Fired when the “Send a test button” is clicked.
HTML document
onLoad
Fired when the JSON is loaded in the builder.
JSON document
onError
Fired every time an error occurs.
Error message
onPreview
Fired every time the preview button is pressed.
Status (Boolean)
onTogglePreview
Fired every time the preview is opened or closed.
Status (Boolean)
onChange
Fired every time a change on the message is performed.
onRemoteChange
Triggers during co-editing sessions. It notifies the frontend about changes made by other users in the session.
Note: This is for users B, C, D, and so on, while onChange
is specific to the main user, User A, making the change.
onComment
Fired every time a thread or comment changes.
onFilePickerInsert
Object with file info
onFilePickerCancel
None
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 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.
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.
You can create an additional subscription within the Beefree SDK Developer Console.
To achieve this, take the following steps:
Navigate to your dashboard
Click Add new subscription on the upper right-hand side of the screen
Type a name for your next subscription and click Next
Choose a plan and click Select plan
Confirm the plan you selected
Finalize your additional subscription
Learn how to manage users within the Beefree SDK Developer 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;
change the company’s name, also in Settings & Security.
Learn about the different environments available through Beefree SDK and how to get started to with each.
Development applications are available with any Beefree SDK paid plan.
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.
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. This will make the functionality accessible to you.
To create a development application, take the following steps:
Create a new application
Navigate to your dashboard where the new application is located
Click the + next to Add a development instance
Type in the name of your development application, for example “development environment” or “QA environment”
Click Create
View the new development application available in your Beefree SDK dashboard
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 without any additional costs
Create as many child development applications linked to your parent production environment as you’d like
While access to next tier Beefree SDK features in your development applications is available to you, it is important to remember that you cannot push any next tier features in your development application to your production environment. Your production environment should only include the features reflected in your current plan subscription. If you find that you would like to push a next tier feature from your development application to your production application, you need to upgrade to the subscription plan that corresponds to those features.
Beefree SDK allows you to access next tier features within your development application to test them out and see if they are a good fit for your application’s needs. However, it is important to consider that if you plan to push those features to your production environment, that you have the right subscription and permissions to do so.
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.
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.
This section discusses how to get started with Beefree SDK.
Prior to integrating Beefree SDK, ensure you have:
Node.js (v14 or higher) installed.
A modern web browser (Chrome, Firefox, Safari, Edge).
To test the SDK locally before production deployment:
Clone the demo repository:
Install dependencies:
Configure environment:
Start the dev server:
Access at http://localhost:8081
Using npm
Using Yarn
Package Details:
TypeScript Support: Included
License: Apache-2.0
This section discusses the authentication process.
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.
client_id
string
Your application client ID
"abc123-client-id"
client_secret
string
Your application secret key
"xyz456-secret-key"
UID
string
Unique user identifier
"user-12345"
Example Implementation (Node.js)
Important Notes:
The UID must be consistent between authentication and SDK configuration.
Tokens are valid for 12 hours.
Ensure client_secret and client_id aren't exposed in the client-side code.
JSON Authorization Response
This section discusses how to initialize Beefree SDK.
Create a container element in your HTML where the editor will render:
Beefree SDK requires a configuration object with the following essential property:
Full Configuration Reference
The following table explains the container property.
container
string
Yes
DOM element ID for the editor
Initialize the editor with a template JSON object:
The following table lists template management methods that are important for getting started.
load(template)
Load new template
bee.load(newTemplate)
reload(template)
Force reload template
bee.reload(updatedTemplate)
save()
Trigger save callback
bee.save()
saveAsTemplate()
Save as template
bee.saveAsTemplate()
The instance method bee.start(template)
does not need to be called immediately after create
. In a SPA (Single Page Application) or React app, you can create
the editor in a hidden global state but then call the start
method when the template is selected and available. The application loads quickly when all steps are completed consecutively. However, by separating the loading workflow into two parts, the end-user will perceive loading in a fraction of the overall time. Remember, if the client_id
belongs to a File Manager application, bee.start()
can be called without any parameters.
Implement automatic token refresh to maintain uninterrupted sessions:
How to use:
Get a fresh token from your backend
Pass it to updateToken()
Enable real-time collaboration with these additional methods:
How to use:
Generate a unique session-id
on your server
Call join()
with the same ID for all collaborators
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
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:
The editor will become unresponsive
You must proactively:
Best practice is to refresh tokens before expiration (recommended at 11 hours)
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
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):
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.
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.
Using this simple, client-side example, you can literally try out Beefree SDK in 2 minutes…
Create a new application: you will find your keys in the project’s details page
Open index.html
with your favorite code editor
Locate client_id
and replace “YOUR_CLIENT_ID” with yours
Locate client_secret
and replace “YOUR_CLIENT_SECRET” with yours
Save the file
Before using the code samples listed below in a production environment, please consider the following:
The client-side sample is not safe for a production environment (it was conceived as a quick way for you to test the application). Someone would be able to easily steal your application credentials (just viewing the source code of the page). To keep those credentials safe, authorization must be managed sever-side, as the .NET sample does.
These code samples use a limited set of features and configurations: they can be a good starting point to start developing around Beefree SDK, but they are not an exhaustive showcase of everything you can do.
All sample code is provided “as is”: it may contain defects, it may not follow best practices (although we try to!), and it should only be considered as point of reference.
An overview of page builder within 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.
Learn more about what Beefree SDK's embeddable no-code email builder is, how to test it out, and how to integrate it into your SaaS application.
Beefree SDK’s embeddable no-code email builder offers a solution that empowers creators to design visually striking, high-converting emails with ease. By removing technical barriers, it enables teams to build, customize, and launch campaigns faster, maximizing results without the need for hard coding. This allows marketers, designers, and content creators to focus more on designing and refining their email strategies, rather than spending time coding emails from scratch.
The email builder within Beefree SDK is a no-code drag-and-drop editor that enables end users to design beautiful emails that resonate with their audiences. Within the email builder, end users have access to both simple email creation tools, such as adding content blocks, and advanced email creation tools, such as dynamic content, merge tags, display conditions, html blocks, and so on. Beefree SDK’s email builder was created with email marketers, copywriters, designers, and other content creators in mind. It provides them with an environment to intuitively create emails without having to write a single line of code, while being able to easily export their design’s HTML code if they ever need it. Overall, Beefree SDK’s email builder democratizes the email creation process by providing a no-code route for your application’s end users to create visually stunning and appealing emails for their audiences.
In the following GIF, you can see an example of differently customized experiences.
On a foundational level, the Email builder includes the capabilities detailed in the following table.
There are various tools you can use to experiment with and test out the Email builder to learn more about it.
The following resources are a great start to learn more:
You do not need a Client ID or Client Secret to experiment with the Email builder in this environment.
You do not need a Client ID or Client Secret to experiment with the Email builder in this environment.
To integrate the Email builder, take the following steps:
Obtain your Client ID and Client Secret
Authenticate
Starts the builder, loading the templateToLoad
JSON string with the template structure (if specified). If using the NPM package, you have additional options to pass here as defined on the .
Read more about onRemoteChange
and . Read more about .
Fired when the “insert” button is clicked. This property must be defined by the host application for the insert button to appear within the user interface. Available for only.
Fired when the “X” button is clicked. This property must be defined by the host application for the cancel “X” button to appear within the user interface. Available for only.
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 .
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.
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.
Log in to the
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 ();
Log in to your
A Beefree SDK .
You can install Beefree SDK using either or :
Repository:
Reference the in GitHub for example templates.
Q: Where can I find sample templates? A: Visit our for examples.
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.
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 .
Obtain your application keys (Client ID and Client Secret) (there is a free plan).
the client-side sample code.
Open it in your browser and get creative
Make sure you first and get your application keys (Client ID and Client Secret).
Email marketing remains one of the most effective digital channels, delivering an impressive —for every $1 spent, businesses see an average return of $36. In a landscape where personalization and quick execution are critical, no-code email builders like Beefree SDK make it easier for teams to create and optimize these high-performing, targeted campaigns. Personalized campaigns, which , are more easily executed with tools that free teams from coding, allowing them to concentrate on strategy and design. By simplifying the email creation process, Beefree SDK enables creators to spend less time on technical tasks and more time driving results through impactful, strategic designs.
Embedding Beefree SDK’s email builder is quick and easy. Once you embed the SDK within your application, you’ll already have access to a host of default features that are instantly available to your application’s end users. In addition to these default features, Beefree SDK also offers a variety of optional features you can easily activate by simplifying toggling them on in the Developer Console. If you want to customize the email builder further, you can also integrate with our, , add , and much more. You can reference of the level of customization that is possible with Beefree SDK.
Note: Additional capabilities and features can be added on top of these through , toggle on options in the , , , , and more.
You do need a to experiment with the Email builder in this environment.
in the
within the Developer Console
Use the to and embed Beefree SDK
Visit to learn more about installing Beefree SDK.
Demonstrates integrating the Beefree SDK into a full-stack NextJS application with database integration and user authentication.
NextJS, Python, SQLite
The official NPM package for Beefree SDK, complete with installation instructions and configuration tips.
Typescript
Code from our latest webinars showcasing how to use Saved and Synced Rows feature within the Beefree SDK.
ReactJS
A collection of free email, landing page, and popup templates designed for easy integration with the Beefree SDK.
JSON
A simple HTML app demonstrating the basic implementation of the Beefree SDK for client-side applications.
HTML, JavaScript
The stage where the end user drags and drops the content tiles and designs their email.
The content types end users can drag and drop as tiles onto their stage to add to their designs. The Free email builder comes with the following Content tiles (more are available on higher plans):
Title
Paragraph
List
Image
Button
Divider
Spacer
Social
Dynamic content
Icons
Table
When an end user clicks on content on the stage, the Content properties will appear in the sidebar. This is where they can customize the content on their stage. Customization options include Text color, Link color, Line height, Letter spacing, Block options, and more.
End users can drag and drop Rows onto the stage, too. Rows store groups of content within the email design. An end user needs to drag and drop a row onto the stage before they can add Content tiles. Once the rows are added, they can drag and drop Content tiles onto them.
Users can customize Rows with Row properties. Customizable options include Backgrounds, Borders, Column Structure, and more.
Settings enable end users to apply general customization options to their email designs.
A few of the actions included with the email builder include:
Preview
Send test
Save as Template
The text editor appears when you click on a text-type content on the stage. The options include adding Merge tags, Special links, and more.
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.
The Embedded mode allows video playback inside the page. It requires the URL of a video hosted on YouTube, YouTube Shorts, or Vimeo.
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.
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.
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)
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.
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.).
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;
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.
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.
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.
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.
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.
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.
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.
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.
The following sections will look at how to customize the workspace, starting with the common settings and working up to a full custom layout.
Let’s start by looking at some of the differences between Page Builder and Popup Builder.
Content Width
HTML output
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 the builder’s 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. You’ll find an example in the common settings section below.
Popup Builder does not support fluid 100% width content.
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 SDKPopup 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.
Now that we covered the basic differences between Popup Builder and our other applications let’s discuss what you should expect when the builder starts.
As mentioned above in the Getting Started section, you will receive a ready-to-go design experience if 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 you 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 make some minor adjustments? We have you covered!
Easily change the background to make the workspace look like the destination page where you’ll embed the popup.
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. We’ll show you how later!
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.
Here is a complete list of preset layouts:
Classic Popup
classic-center
classic-top-right
classic-top-left
classic-bottom-right
classic-bottom-left
This is our default layout and works great for alerts and exit intents.
Drawer or Slide-in panel
drawer-left
drawer-right
Side panels, or drawers, can be used to design menus or display ads.
Bar or Docker
bar-bottom
bar-top
This is great for cookie approval dialogs.
Another useful preset available is changing the popup’s styles from the default to better match the end-user’s use case. For example, if you’re using the popular Bootstrap CSS framework, you can select the “Bootstrap Theme” as your default. As with the default layouts, you can use any of the available preset themes “as is” or use them as starting points that you can fine-tune to your satisfaction.
Here is a complete list of preset themes:
Custom
custom
This is our default layout and works great for alerts and exit intents.
Bootstrap
bootstrap
This will a popup that looks like the popular Bootstrap CSS modal.
jQuery
jQuery
This will be a popup that looks like the popular jQuery modal. Many of the latest CSS systems use a style similar to the original jQuery.
Material
material
This will be a popup that looks like the popular Material CSS modal.
As mentioned above, the content area’s width is tightly coupled to the layout, no one size fits all width is saved in the template. All Popup Builder preset layouts come with a default width, which you can override with the following configuration settings.
This page explores and answers the following questions:
How can I monitor what my customers do in the builder?
How can I tell when a message has actually been updated?
This section discusses use cases for tracking message changes.
In today’s software, knowing how customers use an application is essential if you want to provide a good user experience (UX) and eliminate friction points. It’s also a valuable resource to understand where to invest future development effort and build something that customers love.
onChange tracking gives you – the host application – the opportunity to get this information when your customers are creating designs in the builder.
You can use the onChange callback to:
Understand if your customers are actively working on the message they opened (or if instead they temporarily abandoned that task to work on something else).
Discover if they are using one of the great new features that your team recently enabled.
Dismiss or confirm a bug by reproducing a customer’s steps.
Now you can invoke the Autosave event only when something has been added or updated, resulting in a better message recovery experience.
Why is having a historical log of message changes so important? As with the previous cases, this will allow you to provide a better overall user experience. Creating a good email message or campaign typically involves input from several people or departments before it’s finally ready to send, but that can lead to inadvertent mistakes that might cause hours of work to be lost. Saving the differences between versions of a message created during the email production workflow – and allowing your users to compare & restore them – could be a huge time-saver in those cases.
When one of your users adds or updates text or images, the onChange callback returns the new input to your application, allowing you to trigger a complementary function based on it.
The use cases change from application-to-application, but the feature is flexible enough to accommodate a wide variety of scenarios. Here are just a few:
Content suggestions
Prevent unwanted content
Link validation
Link reputation check
Custom HTML validation
Set up an alternative workflow when conditional syntax is applied
…
When you enable onChange
and your end users edit their message, the callback provides you with:
Information on the new content or section
The action that was performed on existing content
The JSON update (as the entire page, as well as JSON patches)
Add trackChanges
and set it to true
.
The onChange
callback, with the related response function.
The following code provides an example callback function for onChange
.
Consider the following when using the onRemoteChange
callback:
The following code provides an example callback function for onRemoteChange
.
This section discusses how to configure onChange
and onRemoteChange
.
This parameter defines when the tracking is active in the builder.
The onChange
callback is triggered every time the builder tracks a change in the message. It returns the message JSON and a response JSON which contains all the information needed to handle any of the use cases described above.
The following table lists the parameters in the onChange and onRemoteChange callback response schema and their corresponding types and values.
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.
A quick primer on how to include forms in a web page.
Our Github account hosts useful resources, including sample code to quick start your integrations.
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.
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:
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:
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.
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!
You can easily change the background to make the workspace look like the destination page where your customer will embed the popup.
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.
Here is a complete list of preset layouts:
This feature is available on Beefree SDK only.
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.
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
This section provides the information you need to get started integrating in your SaaS applications. For more advanced settings, see .
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 if you’re new to Beefree SDK or unfamiliar with the configuration basics (as seen in the example below).
Continue to if you’d like to customize more than the position, background, and content area width.
This feature is available on Beefree SDK only.
This page discusses how to effectively track message changes in the Beefree SDK. It explains how you can use the onChange
function to monitor real-time JSON updates, enabling efficient application updates and debugging, if needed. It also covers how to implement the onRemoteChange
function to track edits made by other users, ensuring that team projects remain synchronized and consistent. By leveraging these two callbacks, you can develop a workflow for tracking design changes your end users make, whether they are within single session or a session.
How can I tell when a session has been updated?
So you might be asking: “Isn’t this similar to the existing feature?” The simple answer is “No!”.
The function is triggered at regular intervals, whether anything has even changed since the last Autosave event or not, which could result in the user seeing a ‘recovery dialog’ window even if there weren’t any changes between the previously saved message and the most recent automatically saved one.
Note: onChange
is also the foundation on which the feature was built on.
To enable tracking message changes, you need to add the following in the :
(Optional) Add and set the onRemoteChange
boolean to true
for multi-user message tracking during .
The onRemoteChange
callback is a bit different than onChange
, because it monitors and tracks the changes of other users (those who are not the primary user) during . Using this callback allows you to monitor the changes of all end users in the same session.
onChange
and onRemoteChange
have the same .
onChange
and onRemoteChange
have the same .
When you create an application in the , 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 . All the documentation in this site applies to both products, except where noted.
All builders are available to Beefree SDK customers under the same . Please contact your Customer Success Manager for more details.
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.
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 .
01
Text Block
02
Image Block
03
Button Block
04
Divider Block
05
Social Block
06
Dynamic Content Block
07
HTML Block
08
Video Block
09
Form
10
Icons
11
Menu
14
Row
16
Message
18
Spacer
22
Paragraph
23
List
26
Table
00
Dropped
01
Dragged
02
Deleted
03
Duplicated
04
Changed
05
Opened
06
Closed
07
Locked
08
Saved
09
Restored
10
Content area background color
11
Do not stack on mobile
12
Row background image
13
Background Center
14
Background Repeat
15
Background Full width
16
Row Display condition
17
Reverse stack order on mobile
20
Text color
21
Link color
23
Text edited
24
Line height
25
Content area width
27
Background color
28
Default font
30
Padding All sides
31
Padding Left
32
Padding Right
33
Padding Top
34
Padding Bottom
40
Hide on mobile
41
Video url
42
Play icon type
43
Play icon color
44
Play icon size
50
Align
51
Automatic image resizing
52
Full width on mobile
53
Image width
60
Alternate text
61
Dynamic image src
62
Dynamic image toggle
63
Change image
64
Image link
70
Button Align
71
Button Link type
72
Button width
73
Button Auto width
74
Button Background color
75
Border radius
80
HTML edited
81
Border All sides
82
Border Left
83
Border Right
84
Border Top
85
Border Bottom
90
Divider Line toggle
91
Divider Width
92
Divider Height
93
Divider Align
95
Icon Name
96
Icon Alternate text
97
Icon Url
98
Icon spacing
99
Icon Align
128
Background Video
129
Paragraph Spacing
130
Font Weight
131
List Type
132
Start List
133
List Spacing
134
List Indent
135
List Style Position
0100
Text dropped
module
0101
Text dragged
module
0102
Text deleted
module
0103
Text duplicated
module
0120
Text color {{value}}
string
Hex color code (e.g. #FFFFFF)
0121
Link color {{value}}
string
Hex color code (e.g. #FFFFFF)
0123
Text edited
string
HTML
0124
Line height {{value}}
string
Value as percent (e.g. 150%)
0130
Padding Add sides {{value}}
string
Value in pixels (e.g. 25px)
0131
Padding Left {{value}}
string
Value in pixels (e.g. 25px)
0132
Padding Right {{value}}
string
Value in pixels (e.g. 25px)
0133
Padding Top {{value}}
string
Value in pixels (e.g. 25px)
0134
Padding Bottom {{value}}
string
Value in pixels (e.g. 25px)
0140
Hide on mobile
boolean
true | false
0200
Image dropped
module
0201
Image dragged
module
0202
Image deleted
module
0203
Image duplicated
module
0230
Padding Add sides {{value}}
string
Value in pixels (e.g. 25px)
0231
Padding Left {{value}}
string
Value in pixels (e.g. 25px)
0232
Padding Right {{value}}
string
Value in pixels (e.g. 25px)
0233
Padding Top {{value}}
string
Value in pixels (e.g. 25px)
0234
Padding Bottom {{value}}
string
Value in pixels (e.g. 25px)
0240
Hide on mobile
boolean
true | false
0250
Align {{value}}
string
left | right | center
0251
Automatic image resizing
boolean
true | false
0252
Full width on mobile
boolean
true | false
0253
Image width {{value}}
string
%
0260
Alternate Text
string
text value
0261
Dynamic image
string
Image path
0262
Dynamic image toggle
boolean
false (only triggered when disabled)
0263
Change image
string
Image path
0264
Image link
string
Url
0300
Button dropped
module
0301
Button dragged
module
0302
Button deleted
module
0303
Button duplicated
module
0320
Text color {{value}}
string
Hex color code (e.g. #FFFFFF)
0324
Line height {{value}}
string
Value as percent (e.g. 150%)
0330
Padding Add sides {{value}}
string
Value in pixels (e.g. 25px)
0331
Padding Left {{value}}
string
Value in pixels (e.g. 25px)
0332
Padding Right {{value}}
string
Value in pixels (e.g. 25px)
0333
Padding Top {{value}}
string
Value in pixels (e.g. 25px)
0334
Padding Bottom {{value}}
string
Value in pixels (e.g. 25px)
0340
Hide on mobile
boolean
true | false
0370
Align {{value}}
string
left | right | center
0371
Link type {{value}}
string
Url
0372
Button width {{value}}
string
%
0373
Auto width
boolean
true | false
0374
Background color {{value}}
string
Hex Color Code (e.g. #FFFFFF)
0375
Border radius
string
Value in pixels (e.g. 5px)
0381
Border Add sides {{value}}
string
Value in pixels | Border Style | Hex color (e.g. 1px solid #C7702E)
0382
Border Left {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
0383
Border Right {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
0384
Border Top {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
0385
Border Bottom {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
0400
Divider dropped
module
0401
Divider dragged
module
0402
Divider deleted
module
0403
Divider duplicated
module
0430
Padding Add sides {{value}}
string
Value in pixels (e.g. 25px)
0431
Padding Left {{value}}
string
Value in pixels (e.g. 25px)
0432
Padding Right {{value}}
string
Value in pixels (e.g. 25px)
0433
Padding Top {{value}}
string
Value in pixels (e.g. 25px)
0434
Padding Bottom {{value}}
string
Value in pixels (e.g. 25px)
0440
Hide on mobile
boolean
true | false
0490
Line
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
0491
Width {{value}}
string
Value as percent (e.g. 150%)
0492
Height {{value}}
string
Value in pixels (e.g. 25px)
0493
Align {{value}}
string
left | right | center
0500
Social dropped
module
0501
Social dragged
module
0502
Social deleted
module
0503
Social duplicated
module
0530
Padding Add sides {{value}}
string
Value in pixels (e.g. 25px)
0531
Padding Left {{value}}
string
Value in pixels (e.g. 25px)
0532
Padding Right {{value}}
string
Value in pixels (e.g. 25px)
0533
Padding Top {{value}}
string
Value in pixels (e.g. 25px)
0534
Padding Bottom {{value}}
string
Value in pixels (e.g. 25px)
0540
Hide on mobile
boolean
true | false
0595
Name {{value}}
string
Icon Name
0596
Alternate Text {{value}}
string
Icon Alternate text
0597
Image Url
string
Icon Url
0598
Icon spacing {{value}}
string
Value in pixels (e.g. 0 0 5px 15px)
0599
Align {{value}}
string
left | right | center
0600
Dynamic content dropped
module
0601
Dynamic content dragged
module
0602
Dynamic content deleted
module
0603
Dynamic content duplicated
module
0604
Dynamic content changed
string
value
0640
Hide on mobile
boolean
true | false
0700
HTML dropped
module
0701
HTML dragged
module
0702
HTML deleted
module
0703
HTML duplicated
module
0740
Hide on mobile
boolean
true | false
0780
HTML edited
string
HTML
0800
Video dropped
module
0801
Video dragged
module
0802
Video deleted
module
0803
Video duplicated
module
0830
Padding Add sides {{value}}
string
Value in pixels (e.g. 25px)
0831
Padding Left {{value}}
string
Value in pixels (e.g. 25px)
0832
Padding Right {{value}}
string
Value in pixels (e.g. 25px)
0833
Padding Top {{value}}
string
Value in pixels (e.g. 25px)
0834
Padding Bottom {{value}}
string
Value in pixels (e.g. 25px)
0840
Hide on mobile
boolean
true | false
0841
Video url
string
Video Url
0842
Play icon type {{value}}
string
Play icon type (e.g. Round outline)
0843
Play icon color {{value}}
string
light | dark
0844
Play icon size {{value}}
string
Value in pixels (e.g. 25px)
1400
Row dropped
row
1401
Row dragged
row
1402
Row deleted
row
1403
Row duplicated
row
1410
Content background color {{value}}
string
Hex Color Code (e.g. #FFFFFF)
1411
Do not stack on mobile
boolean
true | false
1412
Row background image
string
Image path
1413
Center
boolean
true | false
1414
Repeat
boolean
true | false
1415
Full width
boolean
true | false
1416
Display Condition
object
Display condition object
1417
Reverse stack order on mobile
boolean
true | false
1430
Padding Add sides {{value}}
string
Value in pixels (e.g. 25px)
1431
Padding Left {{value}}
string
Value in pixels (e.g. 25px)
1432
Padding Right {{value}}
string
Value in pixels (e.g. 25px)
1433
Padding Top {{value}}
string
Value in pixels (e.g. 25px)
1434
Padding Bottom {{value}}
string
Value in pixels (e.g. 25px)
1474
Background color {{value}}
string
Hex Color Code (e.g. #FFFFFF)
1481
Border Add sides {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
1482
Border Left {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
1483
Border Right {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
1484
Border Top {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
1485
Border Bottom {{value}}
string
Value in pixels | Border Style | Hex color 1px solid #C7702E
1625
Content area width {{value}}
string
Value in pixels (e.g. 25px)
1626
Background color {{value}}
string
Hex Color Code (e.g. #FFFFFF)
1627
Content area background color: {{value}}
string
Hex Color Code (e.g. #FFFFFF)
1628
Default font
string
Font
1529
Link color {{value}}
string
Hex Color Code (e.g. #FFFFFF)
1605
Message opened
page
JSON template
1609
Message restored (e.g. undo or redo history)
page
JSON template
13130
Button Font Weight
string
14128
Row Background Video
string
Video URL
22130
Paragraph Font Weight
string
Font Weight value
Classic Popup
classic-center
classic-top-right
classic-top-left
classic-bottom-right
classic-bottom-left
This is our default layout and works great for alerts and exit intents.
Drawer or Slide-in panel
drawer-left
drawer-right
Side panels, or drawers, can be used to design menus or display ads.
Bar or Docker
bar-bottom
bar-top
This is great for cookie approval dialogs.
What if the default styles and standard settings aren’t enough? No worries! In the following sections, we will look at styling your popup to make it look and feel more like the one real visitors will interact with.
A theme is simply a set of custom styles that give the popup its look and feel. Separate from your layout, Popup Builder comes with some preset themes. The primary is our default theme that is loaded when no settings are specified. We also provide an empty theme that has no styles, which you can use a blank canvas to create your own theme. This is one of the most powerful features of Popup Builder, and we’ll be covering custom styles in depth below.
Here is a preview of the configuration:
To understand the best way to apply your styles, let’s start by inspecting the underlying HTML structure so you can view where the system will map your styles.
Here is a quick break down of what each div does:
This is where you will apply any styles related to how the popup looks, such as border-radius, drop shadows, background colors, or padding.
The header is sometimes used to add a close icon to a popup or display a title.
The div that holds the editable content of your Beefree application.
You can use this div to show a traditional footer for your popup or position some icons outside the popup container (e.g., a close button).
The above HTML structure is represented in your bee config as the following JSON object.
Add styles to the JSON section that corresponds to the HTML element you want to style.
For example, if you want to apply styles to the div with id popup-container, then you would add the styles to the following JSON:
We’ll go deeper into styling in the following sections.
You may be wondering at this point if you have to design an entire theme to get started. Well, you can if you want to, but thanks to the order of operations, you don’t have to. You can start with our default theme and pass in the styles that you want to override. Any style you provide will take priority over any of the defaults.
We said that you could start from scratch if you want, and the easiest way to do that is by using our theme parameter. This allows you to avoid overriding every default style and gives you an empty canvas to build your own theme.
Now that you have seen what the HTML looks like and have some idea where to apply your styles, let’s look at how you get your styles into the editor. The best way to show you is by example, so let’s get started with some common use cases!
Using the schema JSON above and your HTML structure knowledge, you probably guessed that the border is defined on the popup container. So here’s what that would look like:
Example:
After looking at a couple of samples, you may notice these parameters are looking familiar. That’s because every layer of our schema maps to a layer of HTML with the same name AND can be styled with any valid CSS property.
Basically, CSS properties are the same as CSS used by web developers in style sheets, but instead of dashes to separate words, it uses a camel case.
Example:
The CSS property of the style box-shadow would be boxShadow.
Why not use CSS styles as defined by CSS3 specification directly? Well, simply put, CSS properties are better suited for JSON and can easily be shared with any FE application using the popular React framework.
We covered the default layout settings in Setting layout and size section. To recap, the layout determines the type of popup (e.g., a bar) and its location on the screen (e.g., bottom, top, or side). Our research team looked into it, and it turns out, nearly all popups fall into one of the most popular layouts, which we’ve included as presets. But, when that’s not enough, the configuration option customLayout can be used to make minor adjustments to a preset layout or create an entirely new layout from scratch.
Here is a preview of the configuration:
The popup is positioned in the workspace using divs and CSS flexbox. We created a layout structure that mimics an HTML page to map your page’s styles to the workspace.
Layout HTML:
Here is a quick break down of what each div does:
We will apply the styles placed here to the document HTML tag.
We will apply the styles placed here to the HTML body tag
This is the main container div of the workspace.
The wrapper of the popup is used entirely for positioning the popup within the workspace main div.
Example:
code
string
Unique identifier for the event created by combining the content code with the action code.
description
string
A text description of the event in the chosen language. (e.g. Image Block Padding Left: 5px)
value
string
If available, this is the new value. (e.g. If padding changes to 5px, then the value returned is “5px”)
patches
array
You can enable your users to add forms in Beefree SDK with two methods:
Your application passes a single JSON form, potentially including all the fields that may be required in a form. You are in control of which fields are visibile when the form is dragged. From there, users have a vast control on how to customize the form, by:
adding or removing fields
rearranging their order
renaming their labels
editing their type
This is the quickest way to get started using forms. You may also decide to include such forms inside templates provided by your application.
With a content dialog, you have full control over the experience of adding a form. A few examples:
users can select a form from a predefined list
users can browse a list of forms and pick one
users can pick a form and have configuration options (e.g. define a layout) before adding it
Here is an example of form selection built with a Content Dialog.
Once the content dialog returns a form to the application, users can then change the form content properties in the builder, by adding and removing fields, rearranging their order. and customizing their labels and style
You may even want to go a step further and use the Content dialog to load your UI for form creation, on top of the builder; your users will be able to create a new form and add it to the web content they’re building, without interrupting their workflow.
Form builders typically offer different options to get an embed code:
if the embed code is a script, it will not appear in the stage when building the web content. Due to security reasons, we need to remove such scripts during edit mode. The form will appear regularly both in the preview and in the final HTML output. An example of this behavior is the embed code produced by Typeform;
If the embed code lives in an iframe, it will be visible during editing as well. For example, Jotform and Google Forms offer this kind of embedding option.
Once a form is added to the web content, the user has these options to manage fields:
Add and remove fields (unless they are marked as required)
Rearrange their order
Rename their labels
Finally, users can apply various styling options to the form:
change font type, size, and style;
change colors for text and input backgrounds
change size for field inputs
define borders and paddings
position field labels on the top or on the side of the input fields
style buttons
and more . . .
When managing fields in a form block, users can click on the “Edit” action to change field types and properties. To facilitate the user, the icon next to the label highlights the current field type.
A modal window will pop up:
From this modal, users can:
change field type
change general field properties
label (available also in the sidebar)
placeholder (not available for date, multiple/single choice, dropdown)
required field
read-only field
Clicking on “Type” will open a dropdown with all the available field types:
All fields can be edited, unless:
you defined the field in the JSON form as not editable, using the canBeModified
attribute
the field type is
Submit
Hidden
File upload
Label (a special field type with plain text)
Now, let’s have a closer look at the field types that can be configured with the “Edit field” modal.
Email / Phone / Text / Url
These are the easiest field types to configure, as they only have the optional Placeholder property.
The email and URL types will check at form submission, through HTML5 validation, that the value entered is a formally correct email/web address.
Single choice / Multiple choice / Dropdown
Users need to enter the values that will be displayed to visitors. To do this, they will add those values under Options:
They can either:
Enter a single value, which will be both the label and the value passed to the host app in the form.
Enter couplets such as label | value to differentiate the label shown to visitors from the value passed to your app after form submission. In the example above, users will select Milan from the dropdown at the city they want to visit, but your app will receive “A” as the response for that field.
The Multiple choice type can also be used to create checkboxes, e.g. privacy policy acceptance. In this case, no value should be specified, and any external URL should be added in the field label, like in this example:
Date
This type has no additional properties. The date format of the value returned to the host app will be coherent with browser locale information.
Visitors will enter the date using the browser’s date picker. Otherwise, they can input the date directly, following the automatically generated placeholder for the expected date format.
Number
This type has the option to enter a minimum and/or a maximum allowed value. If not entered, the field will accept any number.
Number fields have a “spinner” input that visitors can use to cycle through allowed values. Visitors can also input a number directly, but the HTML 5 validation will verify if the submitted number falls into the permitted interval.
Long text
This type is just like a text field, but it’s meant for longer inputs. It has an additional “row height” property to define the default height for the text area – which can be adjusted by the visitor by dragging the bottom right corner. Here is how a long text field looks like in a form:
Beefree SDK just passes the data back to the host application. It doesn’t save anything or touch any of the data.
required field;
response length, for strings (“must be less than” or “must be higher than” n characters);
response value for numbers (minimum or maximum value allowed);
correct type (i.e. the field must contain a number, email address, or some other specific preset type);
check against a regular expression that defines a pattern the entered data needs to follow.
Any other post-submission validation and action must be defined and performed by your application, for instance:
validating whether the data is acceptable, i.e. email already registered;
saving it into a database;
passing it to a 3rd application;
performing other actions (e.g. sending an email notification).
Learn how to implement the different methods to pass forms to the Builder
A closer look at how to structure a JSON form
dive into some sample forms and quick start your integration;
download templates that include those forms;
get a validation JSON schema to test your forms with.
An AI model receives the description and generates a Simple Schema-compatible template.
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.
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.
Explore how to implement customization options for a form's layout.
This document outlines how you can customize a form’s layout, and discusses the available layout customization options. These options allow you to adjust various elements of forms to improve your end's user experience creating them. Form layout options ensure your application's end users have more tools to create a more effective presentation of their forms.
Key form layout customization options include:
Multiple choice and radio button orientation: You can adjust the orientation of multiple choice and radio button elements, choosing between horizontal or vertical alignment to suit your design preferences or space constraints.
New layout presets: Three layout presets are available: horizontal, vertical, and grid. These presets define the overall structure of the form, allowing you to easily apply a consistent layout across fields.
The form field width includes the following customization option:
Form field width property: A new boolean property, fullWidth
, enables you to manage form field widths. When set to true
, the field will expand to 100% width. When set to false
, it the field width is set to 50%.
The following video provides a visual representation of these customization options and how they function within the user interface.
Prior to getting started, ensure you have the following:
For this implementation, there is a field called orientation
in the JSON at the field object level. This field controls the layout orientation for multiple-choice and single-choice fields, which include radio buttons and checkboxes. The orientation
field accepts the following two values:
horizontal
vertical
The following JSON display an example of the updated structure for a radio button field with the orientation
field included:
Take the following steps to configure the orientation
field:
Locate the form field object in the JSON: Find the field you want to configure, such as a radio button or checkbox field. This will be under the "fields"
key within the JSON structure.
Add the orientation
property: Inside the field object, add a new property called orientation
.
Set the value: Assign the orientation
field a value of either "horizontal"
or "vertical"
, depending on how you want the options displayed in the form.
Save the changes: After making the necessary updates to the JSON structure, ensure that the changes are saved.
Test the form: Once the JSON is updated, test the form to ensure that the options are displayed in the correct orientation. If the field is missing, check if the default horizontal orientation is applied.
These steps will allow you to effectively control the layout orientation of multiple-choice fields in your forms.
The layout of the form fields can be controlled using a new layoutPreset
field. This field is located in the structure
object of the JSON and supports three possible values:
vertical
horizontal
grid
JSON Structure Example
Here is an example of a form JSON structure utilizing layout presets:
The following list shows the available options for layout presets.
Vertical: Fields will be stacked vertically, one on top of another.
Horizontal: Fields will be aligned horizontally, side by side.
Grid: Fields will be organized into a grid layout, allowing for more complex positioning.
Take the following steps to configure the layoutPreset
field:
Locate the structure
object in the JSON: Find the structure
key within the form’s JSON definition where the fields and layout are defined.
Add or modify the layoutPreset
field: Inside the structure
object, add a new property called layoutPreset
.
Set the desired value: Assign the layoutPreset
field one of the following values to control the layout of the form:
"vertical"
: Stack fields vertically.
"horizontal"
: Align fields horizontally.
"grid"
: Organize fields in a grid format.
Example:
Configure field properties (if applicable): If you are using the grid
layout, you may also need to adjust other field properties like fullWidth
to control the width of individual fields. For example, set "fullWidth": true
to make a field span the full width of the grid column.
Save and test the form: After setting the layoutPreset
, save the updated JSON structure and test the form layout to ensure the fields are displayed according to the selected preset.
By following these steps, you can easily configure and control the layout of your form fields using the new layoutPreset
field.
fullWidth
FieldA new boolean field, fullWidth
, has been introduced within each form field object. This field is applicable only when the layout preset is set to grid
. If a layout other than grid
is used, the fullWidth
field will be ignored or removed from the JSON structure.
In a grid layout, setting fullWidth
to true
will cause the form field to span the entire width of the grid column, while setting it to false
will restrict the field's width to a smaller portion of the grid.
fullWidth
Field in JSONTake the following steps to configure the fullWidth
field:
Ensure the layout preset is set to grid
: The fullWidth
field only functions when the form’s layout preset is set to "grid"
. Verify that the "layoutPreset"
field in the JSON is set to "grid"
.
Locate the desired form field: In the JSON structure, find the field you want to configure, such as an email or text field.
Add the fullWidth
field: Inside the form field object, add a new property called fullWidth
.
Set the boolean value:
Set fullWidth
to true
to make the form field span the entire width of the grid column.
Set fullWidth
to false
if you want the form field to occupy half or a portion of the grid column.
Example:
Save the changes: After adding or modifying the fullWidth
field, save the updated JSON structure.
Test the form in grid layout: Ensure that the form’s layout is set to grid
and that the field's width behaves as expected.
By following these steps, you can effectively configure the fullWidth
property to control the width of form fields in grid layouts.
Layout Widget: End users can change the layout preset using a layout widget available in the form sidebar.
Field Width Widget: When the form is using the grid
preset, the fullWidth
field can be modified by users through a field width widget available in the Manage Fields section or the Edit Form Modal.
A form is defined through the structure
object, which includes its main properties.
This is the object that the host application passes to Beefree SDK, and it includes fields
, layout,
and attributes
along with a title
and a description
string values that you can use. The appearance of the form, in terms of styling of labels / fields / buttons (spacing, colors, etc…) is handled directly in the application and is saved in the design’s JSON file. Therefore, the same form can be used in different designs, and have message-specific styles.
Let’s now examine the anatomy of a Beefree SDK form structure.
This object contains the general form attributes as strings: all of them are standard HTML5 attributes.
action
string
method
string
target
string
accept-charset
string
autocomplete
string
enctype
string
novalidate
boolean
dir
string
If you want to use a single form, you can use the optional canBeRemovedFromLayout
and removeFromLayout
attributes to determine (respectively) if that specific field can be removed from the layout by the user, and if it should appear in the stage when the form is dragged in.
canBeRemovedFromLayout
all fields
boolean
true
This attribute indicates that a field can be toggled off by the user. If unspecified, it will be applied as true, allowing the user to switch it on or off in the builder UI.
It’s a best practice to add canBeRemovedFromLayout: false
to mandatory fields (e.g., the email address field in a sign-up form) so that they can’t be excluded in the HTML form.
removeFromLayout
all fields
boolean
false
If you want to leverage the full power of Beefree SDK forms and use a content dialog to feed the form to the editor’s stage, the layout
array will determine how the fields will appear to the user.
Each layout
element is an array itself and represents a single line of fields. This allows different layout dispositions, including multi-column.
Probably the best way to represent this is with an example:
The form title is a string value. It is not displayed to the user while working in the editor but provides extra information that can be used later for troubleshooting. Likewise, description as a string value that is not displayed to the user while working in the editor, but provides extra information that can be used later for troubleshooting or internal reference.
To embed Google ReCaptcha in a Form you need a Google API key for ReCaptcha, the key has to be enabled for a specific website URL or domain; this is crucial because otherwise the script will load but will fail its validation, returning API key errors.
Here’s what’s needed in the submit action when passing a form configuration:
In addition, you have to add an HTML block that imports the reCaptcha library inside the template that encapsulates the form:
Here’s a sample JSON config for the submit button:
Ensure you keep the following in mind:
Make sure HTML sanitize is OFF (this is the default value).
Remember that the reCaptcha UI elements will be visible neither in the Beefree SDK work area nor in the Preview, but they will be integrated when the page will be published. Furthermore, the page has to be hosted on the domain that was enabled on the Google Developers Console when setting the reCaptcha.
This page provides a comprehensive list of HTML form field types, detailing their unique attributes and options, along with global attributes that apply to all fields.
List of Global Attributes and their corresponding explanations:
accesskey
: Defines a shortcut key to activate or focus an element.
class
: Assigns one or more class names to an element, used for styling and script interaction.
contenteditable
: Indicates whether the content of the element is editable.
dir
: Specifies the text direction (ltr
, rtl
, or auto
).
disabled
: Disables an element, making it not selectable.
readonly
: Prevents modification of the element’s content while still allowing interaction.
draggable
: Allows the element to be dragged.
hidden
: Hides the element.
id
: Assigns a unique identifier to an element.
name
: Specifies the name of the form control. Reference the mdn web docs on the name attribute to try it and learn more about its specifications.
itemid
: Provides a unique identifier for items when using microdata.
itemprop
: Specifies properties for microdata.
itemref
: References other items related to the current item for microdata.
itemscope
: Defines the scope of an item for microdata.
itemtype
: Defines the type of an item for microdata.
lang
: Declares the language of the element’s content.
tabindex
: Defines the tab order for focusable elements.
title
: Provides additional information about an element, often used as a tooltip.
value
: Specifies the value of the input element.
The checkbox
field allows users to select multiple options from a list. It is often used to toggle between two states, like "checked" or "unchecked."
checked
(boolean): Specifies whether the checkbox is selected by default.
options
: An array of options, each with:
value
(string)
label
(string)
The color
field allows users to select a color from a color picker.
autocomplete
(string): Specifies if the browser should provide autocomplete suggestions.
list
(string): Refers to a <datalist>
that provides predefined color options.
required
(boolean): Specifies that the field must be filled before form submission.
The datalist
field provides a list of predefined options for other input fields, enhancing usability by offering suggestions.
No unique attributes.
options
: An array of options, each with:
value
(string)
The date
field allows users to select a date, displayed as a date picker.
autocomplete
(string): Specifies if the browser should suggest previously entered dates.
max
(string): Sets the maximum date allowed.
min
(string): Sets the minimum date allowed.
required
(boolean): Specifies that a date must be selected before submission.
step
(string): Specifies the granularity of selectable dates (e.g., steps in days).
The datetime-local
field allows users to input both a date and a time.
autocomplete
(string)
max
(string): Sets the maximum allowed date and time.
min
(string): Sets the minimum allowed date and time.
required
(boolean): Requires a date and time before form submission.
step
(string): Specifies the granularity of selectable times (e.g., steps in minutes).
The email
field is used for inputting one or more email addresses.
autocomplete
(string)
maxlength
(string): Specifies the maximum number of characters allowed.
minlength
(string): Specifies the minimum number of characters required.
multiple
(boolean): Allows multiple email addresses.
placeholder
(string): Displays a hint to the user.
required
(boolean): Requires an email address before form submission.
size
(string): Sets the visible width of the input.
The file
field allows users to upload one or more files from their device.
accept
(string): Specifies the types of files accepted by the server (e.g., image/png
).
capture
(string): Allows capturing images/audio from the camera/microphone if supported.
multiple
(boolean): Allows selecting multiple files.
required
(boolean): Specifies that at least one file must be uploaded.
The hidden
field stores data that the user cannot see or interact with but is submitted with the form.
autocomplete
(string)
The image
field creates a graphical submit button using an image.
alt
(string): Provides alternate text if the image cannot be displayed.
height
(string): Specifies the image URL.
src
(string): Defines the height of the image (in pixels).
width
(string): Defines the width of the image (in pixels).
The label
field associates a text label with a form control, improving accessibility.
No unique attributes.
The month
field allows users to select a month and year without choosing a specific day.
autocomplete
(string)
max
(string): Specifies the latest allowed month.
min
(string): Specifies the earliest allowed month.
required
(boolean): Ensures a selection is made before form submission.
step
(string): Defines the interval for month selection.
The number
field allows users to input numeric values.
autocomplete
(string)
max
(number): Sets the maximum allowed value.
min
(number): Sets the minimum allowed value.
required
(boolean): Requires a numeric value before submission.
step
(number): Specifies the allowed increment for numbers.
The password
field allows users to input masked text (e.g., passwords).
autocomplete
(string)
maxlength
(string): Limits the number of characters allowed.
minlength
(string): Sets the minimum number of characters required.
pattern
(string): Specifies a regular expression for validation.
placeholder
(string): Provides a hint to the user.
required
(boolean): Specifies that the field must be filled.
size
(string): Defines the visible width of the input.
The radio
field allows users to select one option from a group.
checked
(boolean): Indicates whether the radio button is selected by default.
required
(boolean): Specifies that one option must be selected before form submission.
options
: An array of options, each with:
value
(string)
label
(string)
The range
field allows users to select a numeric value within a range, often displayed as a slider.
autocomplete
(string)
max
(number): Sets the maximum allowed value.
min
(number): Sets the minimum allowed value.
step
(number):Defines the granularity of the range (e.g., steps in increments of 1 or 10).
The select
field creates a dropdown list that allows users to choose one or more options.
autocomplete
(string)
multiple
(boolean): Allows multiple selections if set to true.
required
(boolean): Specifies that the user must select at least one option.
size
(string): Defines the number of visible options in the dropdown.
options
: An array of options, either:
option
elements, with:
value
(string)
label
(string)
optgroup
elements, containing groups of options.
The search
field allows users to enter search queries with specialized input handling.
autocomplete
(string)
dirname
(string): Submits the text directionality of the search field with the form.
maxlength
(string): Limits the number of characters allowed in the input.
minlength
(string): Specifies the minimum number of characters.
placeholder
(string): Provides a hint about the expected input.
required
(boolean): Ensures that a search term is entered before submission.
The submit
field creates a button that submits the form data.
data-sitekey
(string): Used in conjunction with reCAPTCHA to verify form submissions.
data-callback
(string): Defines a JavaScript function to be executed after submission.
data-action
(string): Defines an action to be associated with the submit button.
width
(string): Defines the width of the submit button.
The tel
field allows users to enter telephone numbers.
autocomplete
(string)
maxlength
(string): Limits the number of characters allowed.
minlength
(string): Sets the minimum number of characters required.
pattern
(string): Provides a pattern for validation (e.g., for formatting telephone numbers).
placeholder
(string): Displays a hint about the expected input.
required
(boolean): Specifies that a telephone number must be entered before submission.
size
(string): Defines the visible width of the input.
The text
field allows users to input text.
autocomplete
(string)
maxlength
(string): Limits the number of characters allowed.
minlength
(string): Specifies the minimum number of characters.
pattern
(string): Provides a regular expression for validation.
placeholder
(string): Displays a hint for the expected input.
required
(boolean): Ensures that a value is entered before form submission.
size
(string): Specifies the visible width of the text input.
The textarea
field allows for multi-line text input, offering more space than the text
field.
autocomplete
(string)
cols
(number): Defines the visible width of the textarea in characters.
rows
(number): Defines the visible height of the textarea in lines.
maxlength
(string): Limits the number of characters allowed.
minlength
(string): Sets the minimum number of characters required.
placeholder
(string): Provides a hint about the expected input.
spellcheck
(string): Enables or disables spell checking.
wrap
(string): Controls text wrapping behavior (e.g., "hard"
or "soft"
).
required
(boolean): Specifies that input is mandatory before form submission.
The time
field allows users to input a time (hours, minutes, and optionally seconds).
autocomplete
(string)
max
(string): Sets the latest allowable time.
min
(string): Sets the earliest allowable time.
required
(boolean): Requires a time to be entered before form submission.
step
(string): Specifies the time granularity (e.g., steps in seconds).
The url
field is used for inputting valid URLs.
autocomplete
(string)
maxlength
(string): Sets the maximum number of characters allowed.
minlength
(string): Specifies the minimum number of characters required.
placeholder
(string): Provides a hint for the expected input.
required
(boolean): Ensures that a valid URL is entered before form submission.
The week
field allows users to select a specific week within a year.
autocomplete
(string)
max
(string): Specifies the latest week that can be selected.
min
(string): Specifies the earliest week that can be selected.
required
(boolean): Requires a week to be selected before form submission.
step
(string): Specifies the granularity of week selection.
There are three types of pre-built reusable content you can provide your application's end users with. These are the following:
The following code snippet provides a sample rowsConfiguration
.
This section explains each of the properties listed in the rowConfiguration
code snippet.
These properties are the following:
You can add pre-built default rows to your builder by setting the defaultRows
property to true
in your beeConfig
.
Default rows are a set of rows that contain sample content. That’s why we also call them sample rows. They may be used as a supporting feature for starting templates, or to speed up the process of building a message from scratch.
Allowed values: boolean
, can be set to true
or false
.
Default value: false
They are presented as follows in the builder’s default theme (the screenshot shows the first 2 default rows):
Allowed values: boolean
, can be set to true
or false
.
Default value: true
Will always be included as the last element if omitted in the configuration.
They are presented as follows in the builder’s default theme (the screenshot shows the first 4 empty rows with unique structures):
This property is used to specify which type of row should be pre-selected when the end user opens the Rows selection in the visual builder. You have several options for what value to assign to this property, and its role is to simplify the end user's interaction with the builder by focusing their attention on a specific type of row by default.
Possible values for selectedRowType
:
'defaultRows'
: This value will automatically select the default rows that come with the builder, which usually contain pre-designed content that users can easily modify and adapt. It helps users start with a pre-configured structure and quickly adjust it to meet their needs.
'emptyRows'
: This value pre-selects an option for the user to start with empty rows. This is useful for users who prefer to build their layouts entirely from scratch, without any predefined content or structure.
The handle of a row in externalContentURLs
:
You can also pass the handle of a row that is listed in externalContentURLs
to pre-select a row from an external source. A handle in this context refers to the unique identifier or name used to reference a specific row from an external list. Think of it as a unique key that allows the system to identify which external row to load or pre-select.
For example, if you have external content rows listed in externalContentURLs
, such as "Rows list 01" or "Rows list 02," you can pass their respective handle (typically a string like "Rows list 01"
) as the value for selectedRowType
. This will automatically load and pre-select that specific external row, saving the user the step of manually selecting it from the list.
The externalContentURLs
property accepts a row's name and url. You can add multiple items to the property. Each item in the list defines an option available in the Rows drop-down.
name
: the text displayed in the Rows drop-down
value
: URL that will be called by the builder when the user selects the corresponding name in the drop-down. The URL must return a set of rows as a JSON object.
The following image displays an example of how the name
value appears in the drop-down menu.
Empty rows: When the end user clicks the Empty option in the drop-down menu, they will be redirected to a list of row structures to choose from.
Default rows: When the end user clicks the Default option in the drop-down menu, they will be redirected to a list of default rows to choose from.
A handle acts like a reference key to point to a specific row in an external list. Handles are typically unique names or identifiers that can be used to quickly access specific rows from an external content source, ensuring that the correct row is fetched and displayed to the user. For instance, in the following configuration:
If you want to pre-select "Rows list 01" from the external content list, you would set selectedRowType: 'Rows list 01'
, where 'Rows list 01'
is the handle of that specific external content row. The handle here refers to the name or a unique identifier that the system recognizes and uses to select the correct row from the external content list.
Custom Rows are a powerful way to provide “ready-to-go” content directly into the builder. Think products, blog articles, events, coupons. And don’t forget that Saved Rows your customers might have will be loaded as Custom Rows the next time they load the builder.
All this content is crucial to make the most out of the Beefree SDK experience, and that’s why you can add UI elements in your app’s interface to:
jump right to a Custom Rows category, without the need for the user to go into the Rows tab, click on the dropdown and select the category;
provide additional information on the available rows, either through a tooltip or by showing a Content dialog with all the information and the links to the rows.
With this feature, you will reduce the friction needed to discover and access the builder’s Custom Rows. To do so, you’ll use the loadRows
event, which will trigger the Custom Rows content dialog.
Here’s an example of our Beefree product, which integrates Beefree SDK, taking advantage of this method to load custom rows from its UI.
The toolbar in the application contains explicit call-to-action text links to load footers, which correspond to different categories of Custom Rows in the application.
When users click on “Mailchimp Footers”, the Custom Rows Content Dialog is triggered, meaning that the builder opens a communication channel with your application. In this case, no additional UI will be displayed, as the host application provides the URL to the rows associated with that call-to-action. This way, the Rows tab will be immediately selected, with the “Mailchimp Footers” category already selected:
But what if you wanted users to select the email footers they need from a large catalog of pre-built content? In that scenario, you could have a more generic “Load footers” call-to-action in the toolbar.
Clicking on “Load Footers” will once again trigger the Custom Rows content dialog, but this time the application could provide a dialog window where users can browse or search through available footers, and get some additional context on them. Here is a visual example of how it might look like, but as with all content dialogs you have complete freedom on what to show:
When users click on MailChimp, the modal window fades off, the builder switches to the “Rows” tab, and the MailChimp Footers are shown, ready to be dragged into the message.
You can trigger the Custom Rows content dialog via the loadRows
instance event.
Once the Content Dialog is triggered, you have two options, as explained in the How it works section:
Immediately return the rows URL, without displaying the Content Dialog. This is useful if you have a menu and already know which rows to load based on the interaction by the end user with you application’s UI.
By letting you establish an interaction layer between the editor and your application (e.g., you show a modal window), it allows your users to locate/build/insert new rows, thus making the Rows tab in the editor dramatically more flexible and scalable.
To start using it, you need to add the contentDialog object to beeConfig, or add the externalContentURLs parameter if you already use this feature in your editor configuration.
Here is an example of the syntax that needs to be added to the editor configuration document (beeConfig):
From the perspective of your users, this additional configuration adds a new item (using your text label) in the Rows drop-down.
Here is a visual example of how the “Search products” label will be shown, at the bottom of the Rows drop-down.
You can use this event to display a form where the user can search for new items to insert in the message. Here is a visual example:
You could also ask the user to enter parameters that will affect the very structure of the rows (JSON documents) that will be imported into the editor, affecting the way they will display:
You can also mix both forms in a 2-step pattern.
When the selection is made, you must return to the resolve function a URL containing the result (row’s list).
The response must match the same format used to define the externalContentURLs in beeConfig:
This response will:
Create a new drop-down choice with the provided name
Display the rows provided by the URL in the rows panel
Notice that in the rows list, names returned by the Content Dialog display as highlighted elements to give them further visibility over starting choices.
The Content Dialog can be used as many times as the user needs and, depending on the response, the behavior may change:
This overwrites the existing results, keeping the same name in the drop-down. This behavior perfectly matches our example above, where the host application returns “Your search results” every time the content dialog is resolved.
This creates a new drop-down choice, keeping the previous results as selectable elements. Previous results are available directly in the drop-down.
Here is a visual example:
In our example, we are using this event to display a search form and transfer the user selection to the editor as custom rows.
The form is part of the application, so we are using the same elements and styles that users of the application are used to.
These same rows can then be fed back into the editor by leveraging Custom Rows.
To do so, the host application must make them available in a reachable location specified through the externalContentURLs parameter.
The rows are displayed based on your rows configuration, so you can categorize them, creating multiple lists of rows to improve the user experience.
Here is an example of a rows configuration that displays saved items divided into usage categories:
And here is another example where saved rows are organized based on the campaign type:
The following is an example of the response schema when the editor calls one of the provided URLs:
This page provides an overview of Saved Rows and their key benefits.
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.
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.
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.
When enabled, Saved Rows allow end users to select a row in their design and save it. This process involves:
Selecting a row in the builder.
Clicking the Save icon in the toolbar or row properties panel.
Storing the row’s structure, content, and styles as a JSON document in your chosen storage solution.*
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.
There are two paths you can take to activate and store Saved Rows for your application:
When using the standard, empty rows, users are forced to start from scratch every time they introduce a new row.
A set of pre-built rows may accelerate message construction, providing users with commonly used structures filled with sample content. For example, a set of headers, footers, news sections, etc.
With Custom rows you – the host application – are in control of the content that is included. In some cases, providing canned text can speed up the email creation process and provide consistency across all the communications.
Imagine, for example, the case of a CRM where customer success representatives can quickly build curated emails selecting from a number of pre-built text blocks.
In addition to the empty rows that have always been part of the Beefree SDK system, we now provide a set of default rows that you can add to your application with a simple configuration parameter.
They feature a series of popular structures, filled with placeholder text, images, and buttons.
For some users, they may work better than empty rows as they allow them to immediately visualize what they can accomplish with a specific structure.
Does your application onboard users asking for company or brand information?
If so, you can use custom rows to provide footers with legal information already applied (and centralized), header designs that already include the company logo, etc.
Other common use cases:
Approved promotional material
QR codes or barcodes
Advertising content
Product recommendation templates
Check how to configure these sample rows below under Rows configuration > Parameters > Default rows
Create custom rows with content from different sources like blogging platforms, content management systems, etc.
This will allow your customers to save time and reduce errors by avoiding copying and pasting text, links, and images.
Additionally, this helps you ensure that only reviewed and approved contents, provided by a common repository, are used in the message creation.
Transform products from your e-commerce catalog into custom rows, using product images, text, and call to actions to create a promotional message with a few clicks.
You can divide the products into categories and feed them into the builder as different arrays of custom rows.
Or you can use different sets of custom rows to provide different layout options in order to add design flexibility.
In this tutorial, you will learn how to implement Saved Rows in an application that has embedded Beefree SDK.
When the feature is enabled, a new Save icon is added to the action icons when a row is selected:
The same action is also available in the row properties panel when a row is selected:
By clicking on this icon, users trigger a request to the host application to store the row’s JSON document, which includes:
row structure and settings;
contents and their settings;
all style settings.
It is entirely up to the host application:
where to store the JSON documents that describe these saved rows;
if and how to display them to users of the application;
whether to allow users to edit them individually
There are two data structures that are important to understand and utilize when working with both Custom Rows and Self-hosted Saved Rows.
These structures are the following:
The following code shows a row with metadata
and columns
objects.
The metadata
section of the rows schema allows you to keep track of row-specific information.
name
: The saved row’s title displayed in the Rows panel.
A string of plain text that identifies the row.
Displayed in the row card when the row is shown in the Rows panel.
Used for text searches within the Rows panel
Recommended metadata
category
: A category can be useful for organizing your feeds on the Rows tab.
id: A handle that identifies the row in the host application’s data storage.
idParent: Useful to track rows that were saved from previously saved rows. Keeping track of where a row came from allows you to implement additional editing features.
dateCreated: The date the row was created: useful for filtering/sorting rows for content management purposes in your application. It can also help with technical support tasks.
dateModified: The date a saved row was updated: useful for filtering/sorting rows for content management purposes in your application. It can also help with technical support tasks.
userId: To let your application decide whom can edit or saved rows.
tags: Useful to create filters, management, search, and in general to organize the content in your application.
A reference of form fields that can be edited and that cannot 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.
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.
Read this page to learn more about important the core concepts of implementing Self-hosted saved rows.
Saved Rows allows end users to select a row in a design and save it for later use. More specifically, it allows end users to submit a request to the host application to save a piece of content and turn it into a reusable element. The host application, using externalContentURLs
, can feed these saved elements back to the builder as rows that can be dragged into other designs.
In the following video tutorial, you will learn how to implement Self-hosted Saved Rows in an application that has embedded Beefree SDK.
When the Self-hosted Saved Rows feature is enabled, a Save icon is added to the action icons when a row is selected. The following image displays an example of a row with the Save icon enabled in the upper right-hand corner.
The Save icon is also available in the Row properties panel when a row is selected. The following image displays an example of this.
By clicking on the Save icon, the end user triggers a request to the host application to store the row’s JSON document.
This JSON document includes the following:
Row structure and settings.
Contents and their settings.
All style settings.
The host application needs to determine the following:
Where to store the JSON documents that describe these saved rows.
If and how to display them to end users of the application.
Whether to allow end users to edit them individually.
When and how to feed them back to the builder, using the externalContentURLs
parameter.
Locate the application you'd like to activate Self-hosted Saved Rows for.
Click the application's corresponding Details button.
You will be prompted to the Application Details page.
Click the View more link under the Application configuration heading.
Navigate to the Saved Rows section.
Toggle on the Self-hosted on your own infrastructure option.
Click Save on the upper right-hand corner to save your changes.
Why? Because you may decide to make the feature available to different users of your application:
depending on the subscription plan that they are on (you could push users to a higher plan based on the ability to save a row for later);
depending on the purchase of an optional feature (same);
to allow “beta” users to see it while keeping it hidden from the rest of your users;
etc.
Here’s how to do so:
Add the configuration parameter saveRows to the beeConfig document:
Set it to false for all users that cannot saved rows.
Here is a simple example:
The following GIF provides a quick visual example of the end user experience:
When the saved row action is triggered by the user, the builder starts the following sequence:
Metadata Content dialog Used to collect data from the host application and add it to the row object. Metadata helps your application to identify a row, overwrite a previously saved version, etc.
Saved Rows Callback. Function that returns the row to the host application.
The following describes the recommended workflow to implement saved rows in a host SaaS application.
Select the row you want to save and make note of the new save icon.
Click the save icon to trigger a Metadata Content Dialog. To successfully handle this step, you must complete these tasks:
Add a Metadata Content Dialog object to your beeConfig. This configures your handler.
Implement the handler method to open a dialog (e.g., modal window) to collect any metadata you wish your users to input when saving a row.
The dialog should contain a form and complete the following specs:
Save the row returned in the Metadata Content Dialog’s args object.
Collect metadata from the end-user, such as row name.
Merge the metadata with the row, so it can be immediately returned to the application.
Return a metadata object to the application so the stage can immediately use the data.
The application will update the selected row on the stage with the returned metadata.
The application will trigger the onSaveRow callback with the following details:
JSON of the selected row
HTML preview of the selected row
Page Partial of the selected row contained in a page. Use this JSON document to allow users to edit a saved row independently of any message or landing page that might use it.
The application will refresh the Rows panel to reload the selected rows data feed.
Host app will listen for onSaveRows callback and update the previously saved records with the HTML preview.
The rows are organized in lists that are displayed based on your rows configuration. Use the metadata submitted by your users to categorize them, creating multiple lists of rows: this can significantly improve the user experience.
The following code sample shows an example of a rowsConfiguration
that displays saved rows organized by category:
In this code snippet example, the Rows tab will show:
Empty rows
Default rows
Headers
Footers
Product grids
Main article
… retrieving the arrays of JSON documents for custom rows (externalContentURLs) from the URLs specified.
These custom rows names (Headers, Footers, Product grids, etc.) could be the result of a “Category” metadata entered by the user at the time the row was saved. The input could be the result of:
The user writing a new category name for the selected row.
The user selecting from a list of existing categories, previously created by the user, or set up by you.
Here is another example that shows saved rows organized in the Rows tab based on the campaign type:
You can set a category's maximum rows using the following configuration"
Accessing, and organizing saved rows is intuitive with Saved Rows Management. With this feature, we’ve introduced a new action in the list of saved rows that your application can intercept to handle changes in this list itself. This means you can now delete, rename, or re-organize your saved rows, right inside the builder.
Saved Rows Management also comes with the ability to load any external rows via an instance method instead of an external URL. In addition, since you can now access rows through your application, you don’t need to perform authentication.
To start, define a hook in your application configuration. The hook method should be named getRows
and will be nested under the hooks
object, as follows:
Following that, amend your rowsConfiguration
object with the additional parameters:
The handle
parameter to utilize in your getRows
handler from the previous step
The isLocal
parameter to let the application know to use the hook handler
When the getRows method is invoked, utilize the 3rd parameter to obtain an argument containing the handle value of the row being requested. Use the handle to determine which set of rows should be returned.
Finally, we can call the resolve method, passing in an array of savedRows.
The following is the basic structure of the row’s JSON schema. Simply put, the schema is the structure of your saved rows data feed.
The metadata section of the rows schema allows you to keep track of row-specific information.
A string of plain text that identifies the row.
Displayed in the row card when the row is shown in the Rows panel.
Used for text searches within the Rows panel
category A category can be useful for organizing your feeds on the Rows tab.
id A handle that identifies the row in the host application’s data storage.
idParent Useful to track rows that were saved from previously saved rows. Keeping track of where a row came from allows you to implement additional editing features.
dateCreated The date the row was created: useful for filtering/sorting rows for content management purposes in your application. It can also help with technical support tasks.
dateModified The date a saved row was updated: useful for filtering/sorting rows for content management purposes in your application. It can also help with technical support tasks.
userId To let your application decide whom can edit or saved rows.
tags Useful to create filters, management, search, and in general to organize the content in your application.
An example Metadata Content Dialog configuration can be found below.
The metadata resolve function now accepts an options
object in which you can pass the property synced
to determine if the row needs to be saved and treated by the builder as synced.
When the Metadata Content Dialog is completed, the application triggers the Saved Rows callback. The callback returns the following details:
rowJSON JSON of the selected row.
rowHTML HTML preview of the selected row
pageJSON Page Partial of the selected row contained in a page (for editing a row as an independent piece of content).
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.
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.
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:
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.
The following video tutorial discusses what Saved Rows are, how reusable content can support your end users throughout their content creation journeys, and how you can implement Hosted Saved Rows in your application.
To enable Hosted Saved Rows for your application, follow these steps:
Navigate to the application you'd like to configure Hosted Saved Rows for.
Click on Details.
Navigate to Application configuration and click View more.
Scroll to the Saved Rows section.
Toggle on the Hosted on the Beefree SDK Infrastructure option.
Read the pricing information in the popup closely, because additional fees may apply.*
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:
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.
Once you successfully enable Hosted Saved Rows within the Developer Console, your application's end users will have access to a new Save icon for each row, and other options for managing the rows they save.
The Hosted Saved Rows UI includes the following experience for end users:
End users can save a row using the Save icon.
They have the ability to name and categorize rows.
They can edit a row's name or category and save those changes.
End users can decide to reuse or delete rows through the Rows tab in the side panel.
They can also use the vertical three dots to add and manage categories.
The permissions you can control for Hosted Saved Rows through Advanced Permissions are the following:
canDeleteHostedRow
: Allows or prevents deleting hosted rows.
canEditHostedRow
: Enables or disables editing of hosted rows.
canManageHostedRowCategory
: Controls whether end users can manage row categories.
canAddHostedRowCategory
: Determines if end users can add new categories.
Keep the following behaviors in mind when setting advanced permissions:
If both canDeleteHostedRow
and canEditHostedRow
are set to false
, the row menu will be hidden.
If both canManageHostedRowCategory
and canAddHostedRowCategory
are set to false
, the category management menu will be hidden.
The following configuration displays an example of the rows
object inside of advancedPermissions
:
Take the following step to disable access for specific users:
Set saveRows
to false
for users who shouldn’t have access.
The following code provides a simple example of how to add the saveRows
configuration parameter and set it to false
to make the feature unavailable to select users.
The following image shows the save icon when the end user clicks on the row.
The following image does not show the save icon when the end user clicks on the row. This behavior occurs after adding saveRows
to your beeConfig
and setting it to false
.
Similar to how you may want to restrict which end users can save rows based on subscription type, plan type, and so on, you can also control which users have access to the ROWS tab within the builder altogether. By default, the ROWS tab is available within the builder.
You can remove the ROWS tab by:
Add the defaultTabsOrder
parameter to your beeConfig
and set it to: ['content', 'settings']
or ['settings', 'content']
.
Keep in mind the defaultTabsOrder
is a string array (string[]
).
The tab order represented in the snippet below with content
first and settings
second, results in the visualization displayed in the image after.
In the following image, the ROWS tab is no longer available to the end user. In the following image, the ROWS tab is no longer available to the end user and the order of the tabs are Content first and Settings second.
The tab order represented in the snippet below with settings
first and content
second, results in the visualization displayed in the image after.
In the following image, the ROWS tab is no longer available to the end user and the order of the tabs are Settings first and Content second.
How to enable Hosted Saved Rows
How to restrict which end users can save rows
How to customize the modals related to Hosted Saved Rows
An array of patches in the JSON Patch specification. JSON Patch is specified in from the IETF.
The Form block is available for the and the
by passing in the a single, default JSON form, potentially including all the fields your application supports, and then have customers build and style forms with our form content block.
by implementing a on top of the form content block and building a user interface on top of the builder, so that your users can either browse and select pre-built forms or build a new form.
The Content Dialog feature is available on Beefree SDK only.
If you want to pass more than one form to the builder, you can do so by implementing a on top of the form content block.
The HTML Block is available on Beefree SDK only.
As an alternative to the above-mentioned methods, your users can add an HTML block and easily embed forms created with available on the market (e.g. Typeform, JotForm, etc.).
Besides, end users can , when the “edit” action is available.
You can implement client-side validation in your JSON forms using the built-in , to validate things like:
Visit our to:
Superpowers & Enterprise Plans: Access to Simple Schema for and .
All Paid Plans: Access the through the (CSAPI).
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.
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:
This template is passed to the /v1/conversion/simple-to-full-json
.
Using for AI-driven design creation offers the following benefits:
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 .
This feature is available on all and applies only to and builders.
Page builder or Popup builder application within your
The Submit field will always have fullWidth
set to true
, and the corresponding widget will be disabled to ensure it spans the full width. For more details on the end user experience, reference the .
To take a look at real-world examples and samples, you can head to .
An object that lists all the form fields included in the form with its relative properties. The order in which they appear only matters if you to an application. If you want to use the content dialog to feed forms in the builder, the order is not relevant and you can set the form layout in the layout array.
Beefree SDK supports the vast majority of standard HTML5 form
fields. A few of them (such as color
, datetime
, datalist
) have mixed browser support, so please make sure to check before using them.
To see them in action, you can find a few examples on . Head over to if you need the full list of allowed field types, along with the available attributes and options for each of them.
This attribute indicates that a field is toggled off by default when the form is loaded. This behavior is particularly useful to simplify the user experience when you implement forms in the builder through a .
reCAPTCHA is a free service from Google that helps protect websites from spam and abuse. To learn more about reCAPTCHA, visit the or Google site.
The following global attributes are applicable across all field types. They define essential properties related to accessibility, content structure, behavior, and presentation. Reference the Global attributes and Attributes sub-sections of the to try out the attributes and learn more about their specifications.
The following sections list the unique attributes for each field type. Reference the to try out and learn more about unique attributes outlined in the subsequent sections.
Note: apply to each of the field types listed in the following sections.
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
In this page, we will look at a sample rowsConfiguration
that incorporates defaultRows
, emptyRows
, selectedRowType
, and externalContentURLs
. The will discuss the steps to .
: Set of empty rows. The same rows available when rowsConfiguration
is not included. End users can use these empty rows to structure and customize their own content within.
: A set of rows that contain sample content. End users can use the sample content as inspiration for customizing them with their own look and feel.
: Specify which type of row should be pre-selected when the end user opens the Rows selection in the visual builder.
: Each item in this list defines an option available in the Rows tab drop-down.
You can add pre-built empty rows to your builder by setting the emptyRows
property to true
in your beeConfig
. Empty rows are a set of rows that aren't prefilled with content. However, they offer a general structure for content to be placed within them. These are the same rows available to end users when the rowsConfiguration
parameter is not included in the .
In the drop-down menu, you can see a visual example of each pre-built content type mentioned in this article and in :
My Saved Rows: When the end user clicks the My Saved Rows option in the drop-down menu, they will be redirected to a list of rows they created and at a later time.
Custom rows: The MailChimp Footers, HubSpot Footers, and Sendgrid footers are additional options added to the drop-down through the . When an end user clicks on any of these three options, they will be redirected to the lists of rows available in that external resource.
Visit to learn more about editing, deleting, categorizing, and managing rows within the builder.
Interact with the end user, as described in our documentation, and eventually return a URL of custom rows.
allows you to build user interfaces that let your users locate & insert additional content (Custom Rows) while they are working on their message.
Note that Content Dialog may be used to load other content types, as merge tags, special links, or display conditions. .
When the user clicks on the new menu item (e.g., “Search products” in the example above), what you define in the handler (a function with a -like signature) is triggered.
Rows can be saved directly in the editor using the . These rows are returned to the host application as JSON objects that you can store based on your application logic.
With the introduction of Saved Rows Management, we’ve also introduced the ability to load external rows with an instance method. See for more details.
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
Multiple Storage Options: Activate, store, and manage Saved Rows using either or options.
*Beefree SDK offers for this: or .
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.
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
The discusses, on a very high-level, the differences between key row-related features offered within Beefree SDK. This page provides more detailed information on pre-building and saving reusable content.
By enabling the feature, your end users will be able to save design elements that they want to use in other designs in the future.
To display saved rows in the Rows tab, add them to the list of rows available to users by leveraging the .
Reference to learn more about how to configure these sample rows.
Saved Rows allows users to select a row in a message and save it for later use. More specifically, it allows users to submit a request to the host application to save a piece of content and turn it into a reusable element. The host application, using the feature, can feed these saved elements back to the builder as rows that can be dragged into other messages.
Also, see the !
when and how to feed them back to the builder, using the feature.
Reference the or the to learn more. Throughout the subsequent pages, these two schemas and their applications will be referenced and discussed more thoroughly.
Reference the to learn more.
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
You can also reference the in our GitHub repository used throughout this video.
Take the following steps to enable Self-hosted Saved Rows in the :
Log in to the .
The following image displays where the toggle is located in the .
Once the feature has been turned on at the global level, in , you may want to disable Saved Rows on a per-user basis. This can be accomplished via the client-side configuration document that you feed to an application when initializing the builder for a certain user.
Enable Saved Rows in the . as mentioned above.
Visit the to learn more about the end user experience with saved rows. You can also reference the to learn more.
Enable Saved Rows in the as described above.
Load a .
To display saved rows in the Rows tab, add them to the list of rows available to users by leveraging .
For more information on setting a category's maximum rows, visit.
Visit the to learn how to configure edit and delete row options for your application's end users.
NOTE: The row schema is complex and we do not recommend creating rows programmatically. Therefore, there is no schema reference of the row itself. However, you can add your own parameters to the row’s metadata or use our to generate them programmatically from existing content.
The metadata content dialog is triggered by the save icon in Beefree SDK. This step is required to provide Beefree SDK with information about the row, such as its name and/or id. The Metadata Content Dialog is added in the same manner as other Content Dialogs, such as Merge Tags. Please review the section for more details about how to use Beefree SDK’s Content Dialog feature.
With you can offer an easy way for your end users to edit saved rows individually, using a tailored UI built to modify 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.
Enabling a more modular approach to saved rows simplifies how users can design and act on content: updating small details in a saved row, saving it, then deploying it to existing templates becomes a matter of minutes. If you want to learn more about how to leverage Edit Single Row mode to safely modify a Saved Row, take a look at the .
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
Custom Rows are integrated by adding the rowsConfiguration
parameter to your . The following code snippet is the one used to configure the row in the GIF above.
Visit the to experiment more with the Custom Rows configuration, and visit the to learn more about integrating this feature within your application.
takes only a few seconds, because it activated through a toggle in the . The following image shows how the toggle looks like in the .
Visit the page to learn more about customization options and integration details.
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 and for the customized experience.
The purpose of 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 .
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 to learn more about how to implement this feature.
This feature is available on Beefree SDK and above.
With Hosted Saved Rows, you can provide your end users with the option to save and manage reusable content directly within the builder. Hosted Saved Rows can be activated through a toggle within the , which makes it an excellent option for those who are interested in a fast implementation of . Once you toggle this feature on, your end users will be able to save the rows they create within the builder, and reuse them easily in the future. They can also perform actions to manage the rows that they save, such as renaming them, deleting them, categorizing, or recategorizing them. This page covers you need to take to successfully implement .
Log in to the .
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:
Reference the for more information on the end user steps and experience.
Hosted Saved Rows includes to control how rows and categories are accessed and managed. These permissions allow you to define user capabilities, such as editing or deleting rows.
Once Saved Rows is enabled globally in the , you can disable it for specific users using the saveRows
parameter in the beeConfig
document. This lets you control access based on subscription plans, feature purchases, or beta testing.
Reference the to learn more about other customizations that are compatible with Hosted Saved Rows. The webinar discusses the following topics:
How to use with Hosted Saved Rows
How to use Hosted Saved Rows with
Reference the to follow along with the .
Visit the to also learn more about the following topics:
Checkbox
Allows the user to select one or more options.
"Subscribe to newsletter"
Color
Allows the user to select a color from a palette.
"#ff5733"
Date
Allows the user to input a date.
"2024-09-21"
Allows the user to input an email address.
"example@email.com"
Number
Allows the user to input a numerical value.
"42"
Radio
Allows the user to select one option from a set.
"Option 1"
Select
Provides a dropdown menu for the user to choose from.
"Choice A"
Tel
Allows the user to input a phone number.
"(555) 123-4567"
Text
Allows the user to input a single line of text.
"John Doe"
Textarea
Allows the user to input multiple lines of text.
"This is a message..."
URL
Allows the user to input a web address.
"https://example.com"
Submit
Creates a button that submits the form.
"Submit"
Datalist
Provides a list of predefined options for an input field.
"Option 1, Option 2"
Datetime
Allows the user to input both a date and time.
"2024-09-21T14:30"
File
Allows the user to upload a file.
"Upload a document"
Hidden
Stores hidden data that the user does not see.
"userID=12345"
Image
Displays an image as a form button.
"Submit (image icon)"
Label
Defines a label for an input element.
"Username"
Month
Allows the user to input a month and year.
"2024-09"
Password
Allows the user to input a password.
"********"
Range
Allows the user to input a value within a range.
"50 (from 0 to 100)"
Search
Allows the user to input search text.
"Search query"
Time
Allows the user to input a time.
"14:30"
Week
Allows the user to input a week and year.
"2024-W38"
Allotment
Not available
Not available
100 Hosted Rows
250 Hosted Rows
1000 Hosted Rows
Price for extra unit
$0.35/Hosted Rows
$0.25/Hosted Row
$0.20/Hosted Row
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.
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.
The following describes the recommended workflow to implement the Save action in your host SaaS application when the Single Edit Row mode is enabled.
The user clicks on the save button
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:
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
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.
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.
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.
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
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 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.
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.
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.
Control
Managed by Beefree SDK
Full control over storage and management
Setup Complexity
Done through a toggle in the Developer Console
Higher setup complexity requiring backend development
Ready-to-go user interface for end users to create and manage Saved Rows
Done through a toggle in the Developer Console
Requires development and use of Content Dialog
Security Responsibility
Managed by Beefree SDK
Fully managed by your team
Maintenance
Beefree SDK handles scaling and updates
Ongoing maintenance and updates required
Time-to-Market
Faster due to managed solution
Longer due to backend and frontend setup
This page discusses the ways that you can manage reusable content within the builder. There are different row management options, such as delete, edit, or display rows, available to you and your application's end users. Throughout this page, we will discuss these options and how you can implement them.
There is no limit to the number of rows passed to the builder in each array of custom rows.
However, the builder UI will only display the first 30 items (i.e., the first 30 rows in the array).
The rest of them will not show until the user performs a search that matches them. If the search matches over 30 items, the first 30 are displayed.
This filtering is applied to prevent performance degradation in the browser.
The search is performed against all elements of the array (i.e., both visible and hidden), and the first 30 items (i.e., the first 30 rows in the array that match the search criteria) are shown.
All textual content included in the selected array – including image file names – is used to find a match.
The order of the JSON nodes in rowsConfiguration
defines the order in which the lists of custom rows will display in the drop-down. It also determines which list of rows will be used as default (selected) when the user clicks on the Rows tab for the first time during the session.
The first ordering factor refers to the type of row (empty, default, custom). That’s defined by how the following parameters are listed in rowsConfiguration:
emptyRows
defaultRows
externalContentURLs
You would list defaultRows
before emptyRows
to obtain the order shown in the following screenshot:
The order inside the externalContentURLs
node defines the order of the Custom rows.
In the above example configuration:
emptyRows
will be the first item in the drop-down and the default selection when clicking on the Rows tab.
defaultRows
will be the second item in the drop-down.
The lists of rows defined in externalContentURLs
will follow their ordering in the drop-down.
It’s up to you – the host application – to decide what’s available and in which order.
Note the following row type requirements when configuring your rowsConfiguration parameter:
emptyRows
and defaultRows
are not required.
This allows you to load just Custom rows through externalContentURLs
, if needed, controlling which rows end users can drag and drop into the builder.
The maxRowsDisplayed
parameter enables you to define the number of rows displayed under each user-created category in the application's sidebar, without affecting the "Empty" and "Default" categories. It directly influences the number of saved rows an end user sees when they click on a category in the sidebar.
You can set the maxRowsDisplayed
parameter in the rowsConfiguration
object in the Beefree SDK Configuration as follows:
The following section discusses how to configure the Saved Rows Management categories.
Accessing, and organizing saved rows is intuitive with Saved Rows Management. With this feature, there is an available action in the list of saved rows that your application can intercept to handle changes in this list itself. This means you can delete, rename, or re-organize your saved rows inside the builder.
Implementing Saved Rows Management Actions requires some development effort from the host application. This section outlines what you need to know for each action.
To get started, you will need to create a content dialog in your application configuration parameters. The content dialog method should be named onDeleteRow
and be nested under the contentDialog
object, as follows:
Following that, amend your rowsConfiguration
object with the additional parameters:
The handle
parameter to utilize in your onDeleteRow
handler from the previous step
The optional behaviors
parameter to set management permissions
Here’s an example:
When the onDeleteRow
method is called, utilize the 3rd parameter to obtain an argument containing the handle value of the row being requested, as well as the row metadata. Use the handle and the row’s metadata to determine which row should be deleted.
Finally, we can call the resolve
method, passing the value true
if you want to refresh the rows, or false
if you want to keep the side panel’s current listing.
To get started, much like with deleting rows, you will need to create a content dialog in your application configuration parameters. The content dialog method should be named onEditRow
and be nested under the contentDialog
object, as follows:
Following that, amend your rowsConfiguration
object with the additional parameters:
The handle
parameter to utilize in your onEditRow
handler from the previous step
The optional behaviors
parameter to set management permissions
Here’s an example:
When the onEditRow
method is called, utilize the 3rd parameter to obtain an argument containing the handle value of the row being requested, as well as the row metadata. Use the handle and the row’s metadata to determine which row should be edited.
Finally, we can call the resolve
method, passing the value true
if you want to refresh the rows, or false
if you want to keep the side panel’s current listing.
Saved Rows Management also provides errors and warnings for your application, so you can handle all cases gracefully.
You can call the reject
method, passing the message you want to display.
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
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.
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.
Prior to implementing Synced Rows, review the following prerequisites:
When a row is saved with the synced
property, it becomes a “synced row.” To maintain consistency, synced rows cannot be edited within a design. Instead, they function as reference points, ensuring uniformity across all linked designs. The host app must load the row’s JSON using Single Row Edit Mode to edit synced rows. Any modifications to synced rows can be propagated to all linked designs with the help of the CSAPI’s merge-rows
and synced-rows
methods.
Unsynced saved rows, in contrast, allow for edits that don’t impact other designs. They’re ideal for making design-specific changes without influencing other designs that might share the same base row.
As previously mentioned, a synced row is a saved row designated synced
when saved. To set a row’s synced property, adjust the JSON response from the saveRow
Content Dialog.
You might need to modify the saveRow
handler from the Metadata Content Dialog step in your app’s Save Rows workflow.
If you need a refresher, check out:
Here’s a sample implementation for the Metadata Content Dialog, offering the synced row option:
The JSON returned to the builder includes the user’s input and selections from the UI. The configuration below shows the new synced row setting applied to the options argument of the resolve method.
Look for the pencil icon at the top-right of synced rows. Rows without this icon are standard saved rows. The icon provides a clear visual cue for quickly identifying and editing synced rows.
To edit a synced row, click the pencil icon. Editing options appear in the sidebar panel. Inside, you’ll find a CTA button and optional text.
The CTA button opens the editSyncedRow
Content Dialog, allowing the host application to interact with the end-user and receive their selection.
The host application has complete control over the content dialog and UX. However, the content dialog must always return a boolean value of true
or false
to trigger one of the following outcomes:
If true
, the row remains synced to disable content editing in the design before closing the dialog.
If false
, the row updates to enable editing and remove the synced property before closing the dialog.
For example, a content dialog might present users with two options:
Edit the row across all designs.
Unsync the row, turning it into a standard saved row.
The first option, to edit the row across all designs, allows users to make changes to the synced row that will be reflected in all designs that use it.
The second option, to unsync the row, converts the synced row into a standard saved row. This means that any changes made to the row will only affect the design in which it is being edited. This option is useful when the user needs to make specific changes to a single design without affecting other designs that may use the same saved row.
The user’s selection from the above example editSyncedRow
content dialog UI is returned to the builder as a boolean value. Below is an example of the editSyncedRow
configuration for the UI above. Note the boolean value false
in the resolve method unlocks the row:
The following animation shows this example of edit synced rows workflow in action. We’ll dive into this process in the following sections.
Suppose a user selects “Edit and update everywhere” from the content dialog. How does the host app ensure seamless editing and synchronization of the row?
Here’s a breakdown of the typical workflow the host app adopts:
User edits: Users generally hit ‘Save’ to confirm their edits once they modify the synchronized row. Simultaneously, the host app can proactively track these edits using the onChange
method.
Synchronization timing: The decision on when to synchronize changes across all designs rests with the host application. Given the potential need to propagate edits to multiple designs, holding off until the user indicates their wish to exit is customary.
Initiation of synchronization: The synchronization is initiated as soon as the user signifies their satisfaction with the edits, either through the ‘Save’ or ‘Save & Exit’ options.
Background syncing: Given the possible existence of numerous linked designs, a background process is usually set in motion to update all other templates.
In the fifth step of the sample workflow, the goal is to bring the user back to their ongoing design with the updated content. This is achieved using the CSAPI’s merge-rows
method.
The merge-rows
method functions as a sophisticated “find and replace.”
i.e., To synchronize content, the host app forwards a request comprising the outdated template, the newly edited row, and a succinct query detailing which row(s) the API should target for replacement. The “query” is a standards-based JSON Path query typically referencing a globally unique identifier that was added to the saved row during the Metadata Content Dialog step.
To update rows across all designs, keeping track of the templates where rows have been dropped is crucial. There are two principal methods to associate rows with templates:
Using the onChange
method
Upon adding a synced row into a design, the onChange
callback method supplies the row’s metadata. The metadata will contain the row’s guid
, which can be used to link the synced row to the guid
assigned to the template by the host app. Commonly, this is achieved by establishing an index record within the app’s database linking the template’s guid
with the row’s guid
.
Leverage the synced-rows
method
The specific objectives of the host application steer the choice between these methods. Whatever the choice, the primary focus is meticulously tracking the row across all linked templates, ensuring accurate and efficient updates.
By configuring advanced permissions for Synced Rows, you can manage the visibility of and access to the Edit Synced Row toolbar button. These customization options enable you to define whether end users can:
View the Edit Synced Row button.
Click the Edit Synced Row button.
Edit Synced Rows using one of the following options:
Converting a Synced Row to a Saved Row.
A few of the benefits of applying advanced permissions to Synced Rows are the following:
Limit who can modify synced rows to ensure centralized control.
Hide unnecessary editing actions for users who only need to reuse existing content.
Prevent accidental edits to shared content, maintaining consistency across templates.
Sure! Here's a clearer and more user-friendly version of your configuration steps, based on the code you shared:
Follow these steps to enable or customize the editSyncedRow
option in your Beefree SDK configuration:
Open your codebase and locate where you configure the Beefree SDK.
If it doesn’t already exist, add the advancedPermissions
object to your configuration.
Inside advancedPermissions
, add the following nested structure:
Set the Properties:
show
: Set to true
to display the edit button for Synced Rows, or false
to hide it.
locked
: Set to true
to make the edit button read-only, or false
to make it clickable.
Save your changes and test your implementation to confirm the desired behavior.
The following table outlines the configurable parameters for Synced Rows.
show
boolean
Controls the visibility of the Edit Synced Row button.
Default value is true
.
locked
boolean
Determines whether the Edit Synced Row button is clickable.
Default value is false
.
The following code snippet shows an example configuration where show
is set to true
and locked
is set to false
. In the subsequent image, you can see this configuration results in a clickable Edit Synced Row button that is visible in the toolbar.
The following image shows a clickable Edit Synced Row button in the toolbar.
The following code snippet shows an example configuration where show
is set to true
and locked
is set to true
. In the subsequent image, you can see the configuration result, which is a visible Edit Synced Row button that can't be clicked in the toolbar.
The following image shows a visible Edit Synced Row button in the toolbar, but it is not clickable.
The following code snippet shows an example configuration where show
is set to false
and locked
is set to true
. In the subsequent image, you can see this configuration results in a toolbar without the button.
The following image shows a toolbar without the Edit Synced Row button.
Read this page to learn more about the core concepts of implementing self-hosted saved rows, and to follow along in a tutorial with an example of how to implement it.
Clone the the sample project demo to follow along with the steps outlined on this page.
In this guide you will:
Enable the saved rows feature in your developer console.
Configure the Beefree SDK with the proper hooks.
Build a frontend with content dialogs (for saving, editing, and deleting rows).
Manage metadata (names, categories) for each saved row.
Create API endpoints (GET, POST, PUT, DELETE) on your backend.
Set up a database to store row data.
Connect your frontend with the backend through these endpoints.
Test your endpoints using tools like Postman or Insomnia.
Each step below is designed to build upon the previous ones, guiding you from initial setup to the final integration. This guide explains not only what to do, but also why each step is important and how it interacts with the other parts of the overall solution.
Note: Self-hosted saved rows is a highly customizable feature. While this guide provides one approach to implementing Self-hosted saved rows, it is important to note that there are several ways you can customize this implementation based on your application's needs. While this guide mentions core implementation concepts, such as toggling the feature on, setting up the beeConfig
accordingly, and so on, it is also important to note it mentions approaches that you can customize, such as designing frontend modals, configuring your database, and so on.
Overview and Context
Creating the user interface for end users to create, save, and manage saved rows.
Creating, configuring, and connecting your own database to store the saved rows data.
Creating CRUD operations with your own API endpoints.
Enabling this toggle is a prerequisite for all the integration steps outlined in the subsequent sections. Without this toggle, none of the custom hooks or API endpoints will function properly.
Steps to Complete
To enable Self-hosted saved rows for your application, follow these steps:
Navigate to the application you'd like to configure Self-hosted saved rows for.
Click on Details.
Navigate to Application configuration and click View more.
Scroll to the Saved Rows section.
Toggle on the Self-hosted on your own infrastructure option.
Overview and Context
The Beefree SDK must be configured with custom hooks to handle your saved rows. This involves defining a client configuration type and setting up a configuration object that includes your custom getRows
handler. This step is crucial because it connects the SDK with your backend API, allowing it to fetch and update saved rows dynamically.
Code Snippet
Reference the Type Definition & Client Config in the following code snippet.
Additional Context
By correctly configuring Beefree SDK, you guarantee that the editor will know how to fetch and display saved rows. The getRows
hook becomes the bridge between the editor and your data source, while the rowsConfiguration
object provides the necessary settings for displaying external content based on categories.
Overview and Context
Next, you will create the user interface (using a framework like React) that interacts with Beefree SDK. This step involves building modals for saving, editing, and deleting rows. The frontend is responsible for gathering user input and communicating with the backend, so the UX needs to be both responsive and intuitive.
Key Tasks
This step covers the following key tasks:
Fetch saved rows and categories during the component's mounting phase.
Implement modal dialogs that capture user input (e.g., row name, category) and trigger backend updates.
Code Snippet
The following code snippet is for the Save Row Modal.
Code Snippet
The following code snippet shows an example interaction.
Additional Context
This step ties together your user interface with the Beefree SDK and backend. By using modal dialogs for CRUD actions, users can interact with the saved rows feature directly within the Beefree SDK editor.
Overview and Context
Managing metadata is critical for organizing and retrieving saved rows. Metadata such as the row's ID, name, and category allow you to group rows, edit them, and build dynamic external content URLs. In this step, you'll update and refresh external content URLs based on current categories and see how the Beefree SDK configuration uses this data.
Key Tasks
Define the metadata structure (ID, name, category) in your saved rows.
Create a function to update the external content URLs whenever categories change.
Ensure that the Beefree SDK's configuration (rowsConfiguration
) is dynamically updated with these URLs.
Code Snippet
The following code snippet shows an example of updating external content URLs.
Supplementary Code Snippet
The following code snippet shows an example Beefree SDK Row Configuration.
Additional Context
Managing metadata effectively allows you to organize saved rows into logical groups. When a new category is added or updated, refreshing the external content URLs ensures that the editor displays the correct endpoints for fetching rows. This dynamic behavior is crucial for maintaining data consistency across your frontend and backend.
Overview and Context
The backend API endpoints serve as the communication bridge between your frontend and database. These endpoints are responsible for creating, reading, updating, and deleting saved rows. Proper endpoint implementation ensures that user actions in the frontend correctly update the database and that the Beefree SDK editor receives the latest data.
Key Tasks
This section covers the following key tasks:
Set up an Express server.
Implement CRUD endpoints (GET, POST, PUT, DELETE) to handle row operations.
Validate incoming data to ensure that required metadata (name and category) is present.
Code Snippet
The following code snippet shows a POST Endpoint example.
Additional Context
Overview and Context
Using SQLite in this example, you must set up a database to persist saved rows. Creating the appropriate table schema ensures that all necessary data (such as metadata and row content) is stored reliably. This database will be accessed by your API endpoints to perform CRUD operations.
Code Snippet
The following code shows shows the SQLite Table Creation.
Additional Context
A well-defined database schema is essential for data consistency and performance. In a production environment, you might choose another database system, but this SQLite example provides a simple starting point to demonstrate the concept.
Overview and Context
To enable real-time data interactions, your frontend must connect to the backend via HTTP requests. This connection allows the Beefree SDK editor to fetch saved rows and update data based on user actions. The integration of fetch calls in your React component ensures that the user interface is always synchronized with the underlying data store.
Code Snippet
The following code snippet shows Connecting via Fetch.
Additional Context
By establishing these fetch connections, the frontend remains dynamic and responsive. Changes in the backend are quickly reflected in the UI.
Overview and Context
Before testing your Saved Rows implementation, it's important to test each endpoint to verify that the CRUD operations work as expected. Using tools like Postman or Insomnia allows you to make API requests and ensure that both the backend and frontend are interacting correctly.
Testing Steps
In this example, this step covers testing each of the following endpoints in Insomnia.
GET /rows: Verify that all saved rows are returned.
GET /rows/:category: Confirm that rows for a specific category are fetched.
GET /categories: Check that the unique list of categories is correct.
POST /rows: Ensure that a new row is added when metadata is provided.
PUT /rows/:id Validate that an existing row is updated correctly.
DELETE /rows/:id Confirm that a row is removed successfully.
By following this guide you have:
Enabled self-hosted saved rows in your developer console.
Configured the Beefree SDK with a custom getRows
hook.
Managed metadata (name and category) for each row, and integrated dynamic external content URLs into the Beefree SDK configuration.
Created complete API endpoints (GET, POST, PUT, DELETE) on an Express backend.
Set up an SQLite database (or your preferred database) to store row data.
Connected the frontend to the backend using standard HTTP requests.
Tested your endpoints to ensure a smooth integration.
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.
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.
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 restrict which end users can save rows
How to customize the modals related to Hosted Saved Rows
To enable Hosted Saved Rows for your application, follow these steps:
Navigate to the application you'd like to configure Hosted Saved Rows for.
Click on Details.
Navigate to Application configuration and click View more.
Scroll to the Saved Rows section.
Toggle on the Hosted on the Beefree SDK Infrastructure option.
Read the pricing information in the popup closely, because additional fees may apply.*
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:
Allotment
Not available
Not available
100 Hosted Rows
250 Hosted Rows
1000 Hosted Rows
Price for extra unit
$0.35/Hosted Rows
$0.25/Hosted Row
$0.20/Hosted Row
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.
If you decide to deactivate Hosted Saved Rows:
Return to the Beefree SDK Console.
Toggle the Hosted on the Beefree SDK Infrastructure option to off.
Save your changes.
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.
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.
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.
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.
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.
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.
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)
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.
You can directly save and retrieve rows using your own database.
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.
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.
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:
Ensure that you have initialized the Beefree SDK and have a reference to the SDK instance (`bee`).
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:
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:
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.
When configuring a builder application with Beefree SDK, you have four image and file storage options:
Beefree SDK Storage: Default option. Images are hosted in Beefree SDK’s AWS S3 bucket. Potential fees apply for usage beyond the included limits.
Existing Storage Application: Connect your builder to an existing storage application to share storage resources.
Own AWS S3 Bucket: Use your own AWS S3 bucket instead of Beefree SDK’s. Follow the documentation to configure this option.
Own File System: Integrate your application’s existing file system for storage. This option is available on Beefree SDK paid plans.
Beefree SDK provides robust APIs for managing rows. These API endpoints enable operations such as saving, retrieving, syncing, merging, and organizing rows, making them essential for maintaining design consistency and managing shared rows.
Merge Rows API endpoints
Purpose: Updates linked rows across multiple designs by replacing outdated content with new versions. Ideal for batch-updating designs or maintaining consistent synced rows.
Synced Rows API endpoint
Purpose: Retrieves all rows marked as "synced," ensuring centralized tracking of synced rows across templates.
Index Rows API endpoint
Purpose: Generates metadata for template rows, enabling better organization and search capabilities. Create structured catalogs of rows with attributes like categories, names, or tags.
Merge Rows
Endpoint: POST https://api.beefree.io/v1/{collection}/merge-rows
Index Rows
Endpoint: POST https://api.beefree.io/v1/{collection}/merge/index
Retrieve Synced Rows
Endpoint: POST https://api.beefree.io/v1/{collection}/synced-rows
Retrieve Synced Rows: Use the Synced Rows
endpoint to identify synced rows across designs.
Modify a Synced Row: Update the row and submit changes using the Merge Rows
endpoint.
Verify Updates: Confirm that updates are reflected in all linked templates based on the Merge Rows
response.
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.
Note: Beefree SDK does not manage heic files at this time.
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.
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.
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.
A new feature becomes available in the File Manager when this is active.
It leverages an integration with popular stock photo services to offer users of the builder the ability to search through a large repository of high-quality images.
The images are free to use under the Creative Commons Zero (CC0) license.
When this is active, adds a toggle to the toolbar that allows a user to simulate the current design in dark mode.
When this is active, advanced users of the builder can set an image as background when editing a row.
When this is active, advanced users of the builder can set a video as the background when editing a row.
Requires “Row background video” to be enabled.
Enables the possibility for users to upload videos.
Requires “Row background video” to be enabled.
Enables a user to search for free stock videos to use in the File Manager.
When enabled, adds a new row option to keep the horizontal layout on mobile devices. Useful when working with nav bars, icons, and other horizontal design elements.
When enabled, it adds a new property in the “Content properties” section of any content block that supports it. This widget allows users to hide a content block either on mobile or on desktop devices.
When you enable Custom Social Icons in the Social module, users will be able to upload their own social media icons as a new “Add a custom icon” feature will now be available in the Social content block’s property panel.
When enabled, it will give users the ability to Undo or Redo any changes that have been made to the email, including the ability to rewind and fast-forward to any point in their recent edit history.
When enabled, an editor to apply image effects and transformations is available in the image module and row background images.
When enabled, adds a new row option to revert the stacking order of columns on mobile. Useful for layouts with alternating visual & text: applying it will ensure that, on mobile, images are consistently on top of their accompanying copy.
We use third-party tools to aggregate anonymous usage data. It helps us develop a better product by assessing locations, devices, browsers, etc.
This can be turned off if necessary.
When you disable the HTML sanitization service, you’re removing all restrictions on what users of the builder can add inside the Custom HTML content block.
The sanitize service checks and ‘cleans up’ custom HTML, which can be an important measure to prevent the inadvertent introduction of unsafe content or the usage of HTML tags that may impact the message delivery rate. However, it can also have an undesired side effect when the host application needs custom HTML tags or attributes to manage specific scenarios.
Please use caution when disabling this service.
Specifically, when HTML sanitization is disabled, we strongly recommend that you add an alternative code review process. To that extent, the onChange event can help the host application intercept the content as soon as it is inserted, and perform a check on it before the user exits the builder. Alternatively, you can use the onSave event to trigger an HTML review on your end at the time the HTML is saved in your system.
The client-side configuration exposes a parameter to override the global setting in the control panel. You cannot disable the HTML sanitization service in the client-side configuration, due to security reasons, but you can enable it per user via the forceSanitizeHTML parameter.
The sanitization service allows the following tags and attributes:
a, abbr, acronym, address, b, bdo, big, blockquote, button, caption, center, cite, code, colgroup, dd, del, dfn, dir, div, dl, dt, em, fieldset, font, form, h1, h2, h3, h4, h5, h6, i, ins, kbd, label, legend, li, map, menu, ol, optgroup, option, p, pre, q, s, samp, select, small, span, strike, strong, sub, sup, table, tbody, td, textarea, tfoot, th, thead, u, tr, tt, u, ul, var, video, source, style, img, br, hr, area, base, basefont, input, link, meta, col, iframe
In this section, you can activate restrictions for the file manager:
Specify which file formats your users can upload in File Manager.
Set a maximum allowed size, different from the default of 20MB.
Please note that the first option will not ask for file extensions, but will instead present file categories such as image, video, text, etc. We have mapped these categories to the most used MIME types that can be referenced in HTML documents.
Custom S3 Bucket is a Beefree application configuration feature that allows you to easily connect your own Amazon Web Services S3 bucket to your Beefree application.
By leveraging this feature, you will be able to store and manage your customers’ assets without having to build a new File System Provider, but rather by providing a compliant folder structure and filling out a simple form.
Our default file system provider uses two first level folders to manage assets:
Images folder – It defines where the user’s images will be stored.
Thumbnails folder – Is used by our API to store the thumbnails of the uploaded images.
These folders can be root folders or can be part of a more complex directory structure.
A few notes and recommendations:
These folders should not be parents/children between themselves.
For performance reasons, you should use a dedicated bucket and place these folders in the root.
As an additional configuration option, you can provide shared files to your users, something that we do in the free version of the Beefree editor at beefree.io. These images are shown to all your customers as read-only assets.
The most common use case is providing sample images for the user’s first experience with the editor. Other use cases include providing application-specific images or documents that must not be deleted by the user.
To use this option you need to set-up two additional folders:
Shared images folder – This is the folder that your users will browse through the file manager.
Shared thumbnails folder – While the user images thumbnails are created when the images are uploaded, there is no automatic thumbnail creation for shared images. You must provide your own thumbnails using these settings:
200px as max. width/height (this guarantee a correct preview in the file manager)
Name: original_image_name.ext_thumb.png (so the thumbnail for cat.jpg must be cat.jpg_thumb.png)
PNG: use only PNG as image format
Take the following steps to configure Access keys in the Developer Console:
Navigate to the application you'd like to configure a custom S3 bucket for.
Click the Details button for that application.
Navigate to Application configuration and click View more.
You will be redirected to Storage options.
Toggle on Configure your own S3 storage system to enable the option.
Complete the required fields.*
Click the Test S3 settings button.
The following JSON is of the Permissions policy assigned to the AWS user.
The URLs for accessing files in your S3 bucket vary depending on whether the "Custom URL" field is set in the Developer Console:
If "Custom URL" is empty: URLs will follow this format:
If "Custom URL" is set (e.g., https://my-cdn/
):
URLs will be generated like this:
Public Access:
For the generated URLs to work, the bucket’s permissions should allow public access to the files.
Using a CDN as "Custom URL":
If you’re using a CDN (e.g., CloudFront) in the "Custom URL" field, you can restrict the bucket's access to only the CDN. In this case, the bucket itself doesn't need to be publicly accessible, as access is controlled through the CDN.
Ensure that bucket permissions are configured appropriately based on the type of URL being generated.
You can enable the move icon for files within the File manager. This move icon allows your end users to move their files between folders, locations, and so on within the File manger. They can access the move icon directly on the file within the File manager. The move icon is a folder with an arrow pointing right inside it. End users click this icon to initiate the process of relocating the corresponding file to a new destination.
If you are using a Custom AWS S3 Bucket, take the following steps to enable this feature for your File manager.
Take the following steps to enable the Move icon for your end users:
Navigate to the application you'd like to activate it for.
Click on the Details button.
Select the View more option located under Application configuration.
Navigate to the Services section.
Toggle on the Enable moving files between folders in file manager option.
The Move file option will automatically become available for your end users.
If a file an end user trying to move or copy has the same name as an existing file, the File Manager will show a pop-up asking how to handle the conflict.
The end user will have the following options:
Cancel: For this option, nothing will happen, and the operation will be stopped.
Keep Both: This option lets them keep both files. The new file will be saved with a slightly different name, adding a number at the end. For example, if the original file is called "pizza.jpg," the new one will be named "pizza_1.jpg."
Replace: Selecting this will replace the old file with the new one, meaning the existing file will be overwritten.
These options help them decide what to do when file names clash, ensuring they have control over how their files are managed.
To implement the new Move File feature in your application, follow these steps to change your file path from the old format to the new format. This change is important because it allows the host application to enable the Move File feature within the File Manager without breaking old URLs. Here's how to make the transition:
Understand the Changes: The file paths will change from /your-path/UID/user-path/filename.jpg
to /your-path/new-internal-id/random-path/filename.jpg
. This new structure decouples the logical path you see in the File Manager from the physical path in the storage, supporting the "move file" feature. For example, you can move the file in the File Manager, and the URL will remain the same.
Activate Move Feature: Once you are onboarded, activate the Move Feature inside your SDK Console to utilize the new file paths. Follow the steps outlined in the previous section to complete this process.
Decoupling Logical and Physical Paths: The new path structure separates the logical path (what you see in the File Manager) from the physical path (where the file is stored). This allows for more flexibility and new opportunities for future features.
Enable the Move File Feature: By adopting the new path structure, you can use the Move File feature in the File Manager, which allows you to move files without changing their URLs.
Existing Paths: Existing paths are not affected. The task done was to collect paths in the new database and keep files where they are.
Newly Uploaded Files: New uploaded files will be stored using the new path structure.
Logical and Physical Path Separation: The new path structure decouples the logical path you see in the File Manager from the physical path in the storage. This supports the "move file" feature, allowing you to move files in the File Manager without changing their URLs.
Changes: The key difference between the two paths is that the new path uses a random part to enhance security and reduce predictability, making it harder for unauthorized users to guess the URLs of stored files.
By following these steps, you can ensure a smooth transition to the new file paths and take full advantage of the Move File feature in your application.
This is a description of the form fields and what information you will need to provide in each of them:
Important: If you change the custom URL, the new URL is immediately used for all images.
Configure the Images Path
Field Name: Images path
Example Value: your-images-folder
Format: Type the folder name where images should be stored.
Example: userlist
Configure the Thumbnail Path
Field Name: Thumbnail path
Example Value: your-thumbnails-folder
Format: Type the folder name where thumbnails should be stored.
Example: usrlistthump
Configure the Shared Images Path
Field Name: Shared images path
Example Value: your-shared-images-folder
Format: Type the folder name for shared images.
Example: usersShared
Configure the Shared Thumbnails Path
Field Name: Shared thumbnails path
Example Value: your-shared-thumbnails-folder
Format: Type the folder name for shared thumbnails.
Example: usersSharedThumb
Test the Configuration
Click Test S3 settings to validate the setup.
If successful, your files will be stored in the specified root-level folders in your S3 bucket.
To store images and thumbnails inside a single nested folder within your S3 bucket in the Beefree SDK Developer Console, complete the following fields using your preferred nested folder names in the correct format:
1. Images Path
Field Name: Images path
Example Value: inner/your-folder-name
Format: Use a parent folder (for example, inner/
) followed by the subfolder name where images should be stored.
Example: inner/userlist
2. Thumbnail Path
Field Name: Thumbnail path
Example Value: inner/your-thumbnail-folder-name
Format: Use a parent folder (for example, inner/
) followed by the subfolder name for thumbnails.
Example: inner/usrlistthump
3. Shared Images Path
Field Name: Shared images path
Example Value: inner/your-shared-images-folder-name
Format: Use a parent folder (for example, inner/
) followed by the subfolder name for shared images.
Example: inner/usersShared
4. Shared Thumbnails Path
Field Name: Shared thumbnails path
Example Value: inner/your-shared-thumbnails-folder-name
Format: Use a parent folder (for example, inner/
) followed by the subfolder name for shared thumbnails.
Example: inner/usersSharedThumb
The button will become active once all required fields have been correctly filled out. It allows you to test your settings before saving the updated configuration. We recommend that you do so before saving any changes.
If you’ve just linked your custom bucket, you may find that you need to create your own thumbnails. Thankfully, this is an easy process.
For starters, the thumbnails in the File Manager are PNG files that are resized to 200×200 px.
Here is an example of thumbnail generation with image magick:
As a quick example, we’ll be using this custom bucket configuration:
bucket_name : my-custom-bucket
path_images : /path/to/images/
path_thumbnails : /path/to/thumbnails/
…And starting the editor with this UID:
uid : my-uid
When uploading image1.jpg
in root dir, this key will be created in the custom bucket: s3://my-custom-bucket/path/to/images/my-uid/image1.jpg
. Following that, a thumbnail will be generated with name image1.jpg_thumb.png
with key: s3://my-custom-bucket/path/to/thumbnails/my-uid/image1.jpg_thumb.png
.
And one more example:
When uploading image2.jpg
in mydir
inside the root dir, this key is created in the custom bucket: s3://my-custom-bucket/path/to/images/my-uid/mydir/image2.jpg
. Similarly to above, a thumbnail will be generated with name image2.jpg_thumb.png
with key: s3://my-custom-bucket/path/to/thumbnails/my-uid/mydir/image2.jpg_thumb.png
.
When you configure a builder application, you have four options for image & file storage:
An existing builder application: to connect the selected application’s storage to an already existing application. After selecting this option the two applications will share their storage.
End users can upload images, PDFs, and other documents to the builder. For instance, they can link a button to download a PDF report.
There are no charges for storing images & other documents.
There are no charges for delivering images & other documents up to a total of 5TB of delivery traffic per 30-day period.
Above 5TB of data traffic recorded in a 30-day period, you will be billed $0.01 per GB of data transferred.
You can enable the move icon for files within the File manager. This move icon allows your end users to move their files between folders, locations, and so on within the File manger. They can access the move icon directly on the file within the File manager. The move icon is a folder with an arrow pointing right inside it. End users click this icon to initiate the process of relocating the corresponding file to a new destination.
If you are using the Beefree AWS S3 Bucket, take the following steps to enable this feature for your File manager.
If you are using your own AWS S3 bucket, take the following steps to activate the Move File feature:
Ensure that your FSP is updated to the latest version.
Locate the Move File configuration toggle.
Toggle the feature on.
The Move Feature will be available in your application.
When you use the Beefree SDK S3 storage, your images are delivered via a Content Delivery Network (AWS Cloudfront), and AWS bills us based on the traffic generated by those assets when you send emails or publish web pages created with Beefree SDK. A large amount of monthly traffic (5TB) is included in your Beefree SDK paid subscription at no charge.
If you exceed the 5TB monthly traffic allotment, we ask you to cover the cost of the service (for a few of our customers that generate a lot of image data traffic, that cost has grown to exceed their Beefree SDK subscription fee). Also, note that this scenario is quite rare: it applies to less than 3% of our customers.
If you’re on a paid plan, billed monthly, the counter will reset on the same days as your UIDs and CSAPI calls, i.e., on the day your subscription to Beefree SDK is renewed.
If you’re on a paid plan, billed yearly, the counter will reset on the 1st day of each month.
If you’re on a free plan, the counter will reset on the 1st day of each month.
You can always see when the current period starts and ends in your application details, in the Statistics widget:
You’ll be billed annually by summing up any paid traffic you may have accumulated during the past 12 months, unless such total were to exceed $1,000. In that case, we will send you an invoice. The same is true for additional user fees (UIDs) and additional API calls.
All traffic generated is charged to the shared storage. E.g.: an Email Builder application shares its storage with a Popup and a Page applications. In this case, the Email Builder application will be charged for the traffic generated by Email + Popup + Page.
It’s not possible to link a development app to a production app.
An app can be linked to another just once.
The same shared storage can be shared across different applications within the same subscription
No, this is not possible. You can either connect production apps included in the same subscription or dev apps included in the same subscription.
As you may have noticed, when you create a new Beefree application, it comes with a default cloud storage option for files (images or files that the message uses or links to). This approach may fit well for applications that offer content creation for the first time, especially if they don’t need to share these files with other areas of the host application.
If you do want users to be able to access the same image and file directories that they use elsewhere in your application, we have a solution.
It can be built with your preferred technology: just be sure to follow our instructions to ensure successful communication between the two systems.
Once successfully connected, when a user uploads a file or creates a new folder in the Beefree File Manager, this API will perform these actions in your storage, instead of our default cloud storage. Directories permissions, root directory to use, how thumbnails for images are generated, etc.: you decide.
In order to let your Beefree application consume your FSP (File system provider) API, you will need to provide a Base URL to reach the API.
Base URL: https://myfsp.com/path/to/your/base/endpoint
Note that:
the Base URL must not end with a trailing slash (/)
it must be hosted on the HTTPS protocol
In the event of a successful response, the API returns a “success” status code (ex. 200 OK
) and a JSON object such as the following:
In the event an unexpected error occurred during request processing (i.e. missing mandatory request data), the API returns an “error” status code and a JSON object such as the following:
Authentication is managed using Basic Authentication type. The Beefree SDK system’s resource server works as a proxy for FSP (File system provider) and consumes FSP API endpoints adding the following fields to HTTP Request Headers. Please note that the API must use HTTPS to grant secure connections and safe data transfer.
You can enable the move icon for files within the File manager. This move icon allows your end users to move their files between folders, locations, and so on within the File manger. They can access the move icon directly on the file within the File manager. The move icon is a folder with an arrow pointing right inside it. End users click this icon to initiate the process of relocating the corresponding file to a new destination.
Complete the following tasks to enable the move files feature for your custom FSP:
This section will show samples of successful requests to FSP (File system provider) API. A response contains metadata about directory and files.
In this section, we define the following types of metadata:
The following table lists the fields, descriptions, types and examples for the FSP API response common meta.
The following table lists the fields, descriptions, notes and examples for the FSP API response file-specific meta.
The following table lists the fields, descriptions, notes and examples for the FSP API response directory-specific meta.
Description: Use this to list the directories within the File manager.
The following code shows an example request for listing directories.
The following code shows an example response for listing directories.
Each resource returned by the API has a meta
field with metadata. Directory content is returned into items
field as array of metadata of contained resources.
Some notes about resources access management in the previous example:
/shared/
cannot be renamed, because it is contained in a ro
directory
/mydir/
cannot be renamed, because it is contained in a ro
directory
user cannot “CRUD” resources in /shared/
, because it is ro
user can “CRUD” resources in /mydir/
, because it is rw
Description: This response tells the user interface (UI) whether or not to show the move icon for files within the File manager.
The can-move
property controls whether or not the move button is visible within the user interface (UI).
Take the following steps to display the move icon for file within the File manager:
In the response of the listing endpoint, add a new field named can-move
within the extra
object for each file item.
The can-move
field has a boolean value indicating whether the file can be moved. You can set this value to true
or false
.
The following code shows an example request for listing directory content.
The following code snippet shows an example of the can-move
property set to true.
The following table shows the response metadata and its corresponding type and description.
Description: When the move button is pressed, the "move dialog" appears and the usual listing URL is called.
The following image shows an example of the move dialog. This dialog appears after the end user clicks on the move icon for a file. In the image, you can see that the move dialog includes a list of directories for the end user to select from in order to relocate the file.
The following code shows an example of the GET
request that occurs when the move icon is pressed within the File manager and the "move dialog" appears. This GET
request includes the x-bee-fsp-flags: move
header, which is responsible for this behavior.
The move dialog only shows folders. The GET
request will return the full response, including the folders and the files. However, the response will only show items with "mime-type": "application/directory"
. The File System Provider recognizes this call by the x-bee-fsp-flags: move
header.
For the move dialog to work effectively, it is important that you limit the size of the response. Ensure that the response to this request only contains folders and not any files.
Description: Use this when creating a new directory within the File manager.
The following code shows an example request for creating a new directory.
The following code shows an example response for creating a new directory.
in order for the create directory operation to succeed, the containing directory must exist, and the contained (new) directory must not exist
directory names will match the following regular expression: [ a-zA-Z0-9._- \(\)]+
Description: You can only delete empty directories. Use this to delete a directory when it is empty.
The following code shows an example request for deleting a directory.
The following code shows an example response for deleting a directory.
Description: Use this method when uploading a file to the File manager.
The following code shows an example request for uploading a file.
The following code shows an example response for uploading a file.
If an upload has a name conflict with an existing file in the target folder, the FSP must decide how to manage this conflict:
Return an Error: Notify the user about the conflict and do not proceed with the upload.
Ask the User: Prompt the user for instructions on how to handle the conflict.
Overwrite File: Replace the existing file with the new upload.
Rename and Complete: Complete the upload using a different name, usually by appending a suffix. Ensure the metadata is consistent with the newly created file.
Ask the user what to do:
The FSP can prompt the user for action only if the conflict_strategy
field is set to ask
. In this scenario, the FSP must return a 3400
error code, instructing the Builder to display a dialog to the user.
Example response:
When the user clicks the keep or replace buttons, a new upload request is sent to the FSP with the conflict_strategy
field set to either keep
or replace
.
If there's a filename conflict, the FSP should return a 3401
error code. This instructs the Builder to show a toast notification to the user and prompt them with a dialog.
Uploads are proxied by Beefree’s resource APIs, which enforce the maximum file size configured by the Console. Uploads from various sources are handled as follows:
Image Editor: POST to /editor_images/{filename}
. Filename is a UUID.
Page Builder Favicons: POST to /favicon_images/{filename}
.
Stage: POST to /editor_images/{filename}
.
Description: Use this to delete a file within the File manager.
The following code shows an example request for deleting a file.
The following code shows an example response for deleting a file.
Description: When the move icon is clicked in the File manager, the File System Provider (FSP) will receive this call. It is a PATCH on the URL of the file to move.
An example of a conflict is when you are moving a file from one folder to another, but the destination folder has an existing file with the same name as the file being moved to that folder. For example, you want to move a pizza.jpg file to a folder that already contains a pizza.jpg file. In this scenario, there is a conflict because both files cannot have the same name.
The PATCH Method enables you set a conflict_strategy
that resolves scenarios like these when they occur.
The following code shows an example of this method.
This is the response you will see in the event that a file was not successfully moved to a new location, and an error occurred.
In the event a name conflict occurs, the File manager displays a dialog to the user. You have three options to select from to resolve this conflict using the conflict_strategy
which is passed to the FSP.
These three conflict resolution options are the following:
cancel ( "conflict_strategy": "" ): nothing happens
keep both ( "conflict_strategy": "keep" ): move the file, in order to keep both files our implementation appends a suffix to the new one. For example, the pizza.jpg file will become pizza_1.jpg ( _2 , _3 , ...)
replace ( "conflict_strategy": "replace" ): move the file, it overwrites the old file with the new one
In case of errors, the API returns a JSON object structured like this:
Thumbnail generation is up to the developer of the file system provider.
The thumbnail
field is optional, so if you don’t want a thumbnail for your file, do not pass the field and the Beefree system will show you a generic icon based on the mime type you passed.
The thumbnail image must be contained in a 200px by 200px virtual square (see pictures below).
In this box, you can enable additional content blocks that will appear in the Content panel inside the editor.
Currently, you can manage these content blocks:
If you’re configuring a Page Builder application, there are a few differences in what these blocks allow:
the HTML Block also allows script and iframe tags;
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)
the Menu block allows menu items to be set as “internal links,” pointing to any content block in the page that is configured as a “block identifier.”
There is also an additional option for turning on the Form block.
Please note that you need to implement one of the two methods indicated in this article for the Form tile to appear in the Content tab of the editor:
You can enable AMP blocks that will become available in the “Content” tab of your application's Email Builder. To enable this feature, toggle on Enable AMP Carousel in the AMP Content section of your application's configuration options.
Please note that AMP content is not available for Page Builder.
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
Edit Single Row mode complements the 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.
In case your application uses the default , 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 :
Calling the . It will trigger the on 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 event).
Listening to the event. It will receive the updated full message JSON which again can be saved as a Saved Row.
An effective way to update saved rows across multiple templates is by implementing the save action in combination with the , to handle a row update across .
If you're on the Essentials plan, for free to try this and other Core-level features.
Synced Rows expands on the foundational capabilities of and , helping users manage rows more effectively. Using the merge-rows
and synced-rows
methods in the , 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.
With 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.
complements both and , 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 and with a streamlined design and editing process.
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.
Explore
Explore
Note: To sync rows, visit the .
The search field allows users to narrow down the content shown after they select a list of .
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
Synced Rows expands on the foundational capabilities of and , helping users manage rows more effectively. Using the merge-rows
and synced-rows
methods in the , 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.
: Implement first, because it establishes the foundation for a row management workflow.
& : Familiarizing yourself with Edit Single Rows Mode and CSAPI will provide you with a mechanism to edit and manage synced rows, which will support your implementation workflow. However, they are not strictly necessary to implement Synced Rows.
A comprehensive reference of the editSyncedRow
Content Dialog settings, such as the CTA button label and optional text, can be found in our .
Initialization: The host app launches the Edit Single Row Mode in a new builder instance to enable editing of the synchronized row. Our is available for reference for a deeper understanding.
Redirection & Synchronizing changes: After editing a row, the host app usually performs a synchronous . The user will then be redirected to their ongoing design, where they can see their edits reflected in the synced row.
For an example on how to use the merge-rows
method, visit our .
For those rows incorporated into designs before the implementation of the onChange
tracking method, CSAPI’s synced-rows
method is available. Use the synced-rows
method get a list of all the synced rows inside a template with their corresponding rowIdentifier
values. To learn more about how to use this endpoint, visit our.
Adding to Synced Rows is available for Superpowers and Enterprise plans. If you're on the Core plan, to the Superpowers plan for free. In your development application, you'll be able to try Advanced Permissions with Synced Rows. This is available for Email, Page, and Popup builders.
Redirecting to the builder to edit the Synced Row, and save changes applied globally.
Important: This guide includes sample code snippets from a . You can reference the code for this sample integration in . As you read along in this tutorial, you can copy, edit, and customize the sample code for your own use and experimentation.
Before writing any code changes, ensure you first activate the Self-hosted on your own infrastructure toggle in your . This global setting tells Beefree SDK that your application will handle:
This is in contrast to the other toggle in the Saved Rows section of the Application Configurations within the Developer console, , which .
Log in to the .
This endpoint not only creates new rows but also validates incoming data, ensuring data integrity. Similar endpoints (PUT, DELETE, GET) must be implemented to support full CRUD functionality. You can reference the full code for each endpoint in the sever.js file in .
Built user-friendly modals with to save, edit, and delete rows.
Each step is interconnected: enabling the feature makes it available in Beefree SDK, the frontend's modals interact with backend endpoints, and the dynamic configuration ensures that data remains consistent and up-to-date. The full code files (including the complete Beefree SDK configuration, server code, and database set up) are available in this . This guide shows more concise, focused snippets to help you quickly understand the implementation while leaving the complete examples for additional reference in the repository.
This feature is available on Beefree SDK and above.
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:
Allows for advanced controls through configuring .
How to use with Hosted Saved Rows
How to use Hosted Saved Rows with
Reference the to follow along with the webinar tutorial.
Log in to the .
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:
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 .
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.
When you create an application in the , you’ll have the option to create a 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.
Reference the to learn more about how to configure storage for your File manager application.
Learn more about .
Please note that server-side configurations are only available on .
If you decide to go this route, use the to control the builder from your UI.
Please note that server-side configurations are only available on .
When toggled on, this option scales the background image to fit the background dimensions of the entire document. This feature is best used with high-resolution images. More information .
For and .
When this setting is enabled, users of the builder can specify both a static placeholder image and a dynamic image URL when adding an image content block. This allows for scenarios such as personalized birthday cards, countdown timers, dynamic ads, and many other user cases in which an image is built dynamically at the time it is served. .
When enabled, the display conditions widget will show as a row option. The widget can be used to apply the conditions created by the host applications or to add new syntax manually. .
More on
This will allow users to select a row in the current message and save it for later use. More .
When enabled, adds an option in the file manager to import images from different social networks and storage services. We use for this feature. Filestack may log the user’s IP address. If this is in conflict with your privacy policy, turn the feature off.
This feature allows users to leave comments and start discussion threads inside an email or page, to collaborate asynchronously. .
Learn more about for custom limitations on File manager.
Their name is restricted by .
This section discusses how you can configure your own custom S3 bucket within the , and also provides an example JSON of the Permission policy.
Prior to configuring your custom S3 bucket, ensure you configure Access keys in the .
Log in to the .
*The following image shows an example of the required fields within the for configuring your own S3 bucket:
Log in to the .
Once you have set up a compliant folder structure, you can use the form in the to connect your application. It’s one of the available server-side configurations for your Beefree application (Application details > Open configuration > Storage options).
To store images and thumbnails in separate folders at the root of your S3 bucket in the , follow these steps:
The following image shows an example of how to configure single folders in the bucket root inside of the .
The following image shows an example of how to configure a single nested folder in the bucket root inside of the .
If your Beefree application is currently using the default S3 bucket, you wish to switch to your own bucket, and you have files that you want to transfer between the two, please please and submit a support ticket.
Beefree SDK storage: unless you select another option, images will be hosted in Beefree SDK’s own AWS S3 bucket. for details about potential fees associated with this option.
Your own AWS S3 bucket: instead of using Beefree SDK’s AWS S3 bucket to store & deliver files, you can use your own. See .
Your own file system: if your application already has a place where images and other assets are stored, you can leverage it. This option is only available on Beefree SDK paid plans. See using .
When working with your own custom file system provider, there are many considerations to keep in mind. Follow the steps outlined in the documentation to ensure you configure this feature successfully for this storage option.
Reference to learn more about the end user experience with the File manager.
If you need more control on what files users should be able to upload, you may activate in the Privacy & Security section of your app’s configuration. In alternative, you may consider .
By default, images used in emails and pages created with the builder are stored in Beefree SDK’s file storage system. Beefree SDK uses service for storage, and leverages Amazon’s Content Delivery Network () for fast content delivery.
Beefree SDK customers that exceed 50 GB of image data traffic on the Free plan in a given month will be moved to our .
Navigate to the .
For the moment, only subscriptions on paid plans will be notified by our Customer Success team. If you’re on a free plan, you may check your usage by logging into the , and going into the application details, in the Statistics widget.
You can switch to or .
Please contact your account manager for this. If you are not sure how to do this, please and submit a support ticket asking for your usage history.
We created a way to connect to a custom file system provider, allowing you to use your own file storage, no matter which technology you use. A custom file system provider is an API that will allow a Beefree SDK application to perform actions with files outside of the Beefree SDK system, connecting your file system to the .
The API uses JSON as the input and output data format: Responses are .
In the event a request fails, the API returns the error codes described in the .
User information is segmented by .
Ensure you save the username
, password
, and base URL
in the Configuration section of the .
Add a can-move
field in the extra
object in the . Reference the Listing Directory Content section for steps on how to complete this.
Modify the listing response to limit its content when the request includes the x-bee-fsp-flags: move
header. Reference the for steps on how to complete this.
Implement a PATCH method for file URLs with conflict_strategy
management. Reference the for steps on how to complete this.
The final step in activating the within your File manager is to configure a conflict resolution strategy. This strategy is triggered when there is a file conflict within the File manager.
The following response is the same as the . This is the response you will see in the event that a file was successfully moved to a new location.
To read the full list of possible errors, please refer to .
In case you don’t want to develop your own thumbnail generation procedure, you can use a service like to create a thumbnail URL.
the Video block allows for video playback, either embedding a YouTube, YouTube Shorts, or Vimeo video or pointing to a hosted video (). Supported video formats are:
The method is available for all plans, including free
The method is available for paid plans only.
We currently provide an content block. After enabling the toggle, you will need to configure an .
general attributes
style, id, class, data-*, title
a
href, name, target
img
align, alt, border height, hspace, src, vspace, width, usemap
table
align, bgcolor, border, cellpadding, cellspacing, width
tbody
align, valign
td
align, bgcolor, colspan, height, rowspan, valign, width
tr
align, bgcolor, valign
tfoot
align, valign
th
align, bicolor, colspan, height, rowspan, valign, width
thead
align, valign
li
type
map
name
area
alt, coords, href, shape, target
div
itemscope, itemtype
meta
itemprop, content
video
autoplay, controls, height, loop, muted, poster, preload, src, width
source
media, src, type
Authorization
Authentication used is Basic. A string formatted as username:password and encoded in base64 is passed
X-BEE-ClientId
The ClientId (to identify the integrator)
X-BEE-Uid
The uid (ex. useful to identify the user of an integrator)
mime-type
application/directory for directories and specific mime-type for files
string
“application/directory”, “images/png”, …
name
resource name
string
“my file.jpg”
path
absolute path to resource in FSP
string
“/absolute/path/to/my file.jpg”, “/absolute/path/to/my directory/”, …
last-modified
UNIX time with (milliseconds) of last modification of this resource
int
1445401740000
(stands for: Wed, 21 Oct 2015 04:29:00 GMT)
size
size (in byte) of the resource, this is zero (0) for directories
int
2048
permissions
defines the access grants to the resource, can be ro
for read-only access or rw
for read-write access
string
ro
or rw
extra
generic extra data (for future extensions)
object
public-url
Public url of this file
This field must be url-encoded
string
thumbnail
Public url of the thumbnail of this file
This field is optional and must be url-encoded
string
item-count
number of contained items (directories + files)
This parameter is optional, if you don’t have this data, feel free to pass zero 0
int
name
string
File name.
path
string
File path.
last-modified
number
The date that the file was last modified.
permissions
string
The permissions for the file.
mime-type
string
The file mime type.
size
number
The size of the file.
public-url
string
The public-url to access the file.
thumbnail
string
The thumbnail URL.
extra
object
The object that contains the can-move
property to true or false.
can-move
boolean
A boolean key within the extra object that displays the move button on a file in the File manager when set to true
.
Show toolbar
Is the main option: if is not active, the elements listed bellow get hidden
Show Beefree SDK logo
Show our logo and links our site
Show preview
Trigger the preview window
Show send test
Trigger the function for sending a test
Show save as template
Is used to save only the editable version of the message
Show save button
If you don’t have a external one, better not to hide this 🙂
Show auto-save icon
This tiny icon alert the user every time the auto-save works
Show help link
This option is special, because you can also introduce your custom help URL
Show Multi-Language Templates
Custom url
The hostname – typically a CDN – that will be prefixed to resources URLs referenced in the JSONs created with BEE.
No
Bucket name
The name you assigned to the bucket when you created it.
Yes
Access key & Access secret key
Yes
Select Region
AWS region where you created the bucket. Uses EU as the default setting.
Yes
Images Path
The relative path (from the bucket root) to the images folder described above (use “/” symbol as path delimiter).
Yes
Thumbnails Path
The relative path (from the bucket root) to the thumbnails folder described above (use “/” symbol as path delimiter).
Yes
Shared images path
The relative path (from the bucket root) to the shared images folder described above. Cannot be the bucket root (use “/” symbol as path delimiter).
No
Shared thumbnails Path
The relative path (from the bucket root) to the shared thumbnails folder described above. Cannot be the bucket root (use “/” symbol as path delimiter).
No
HTML
Allows your users to include their own HTML code
Paid plans only
Menu
Allows users to create simple, text-based navigation elements
All plans, including free
Title
Allows users to add text with H1,H2,H3 tags, for email and web accessibility, and for SEO on web pages.
All plans, including free
List
Allows users to create easy numbered and bullet lists with Paragraph’s upgrades and list type, spacing, and identation support.
All plans, including free
Paragraph
Allows users to write text with support for multiple font weights, copy/paste support, easier reformatting, and more.
All plans, including free
Text
Legacy text block. Please refer to title, paragraph and list.
All plans, including free
Video
Helps users include a visual link to video content
Paid plans only
Icons
Enables users to create icon-based layouts, such as star ratings, bullet lists, properties
All plans, including free
Spacer
Allows users to add a space between content
All plans, including free
Table
Allows users to add a table to their design
All plans
The default configuration returned by the system can be extended by using additional configuration objects such as:
Special links are links that your system generates dynamically when the message is sent, typically because they include the message ID, the recipient’s email, or some other variable. The most common one is probably the unsubscribe link.
The type
parameter will be used to group related links in the UI and simplify the user selection.
Technically, special links are passed to the application in the configuration file as follows:
and here’s an example of what the user will see in the builder UI, starting from the above code:
As mentioned above, when you initialize the application, in the configuration file you can submit both “merge tags” and “merge content”.
Really, they are the same thing: some syntax that your system will replace with some meaningful content at the time the email is sent. They differ in the way they are presented to the user.
Merge tags help dynamically insert text into a paragraph, such as the very common scenarios of “Dear {first_name}”.
Merge content, instead, helps the user insert special syntax as content element in other sections of the message that are not text, such a list of recommended products.
Currently it is not possible to group merge tags and merge contents as it is for special links.
Here is an example of adding mergeTags
and mergeContents
in the configuration file:
Merge tags can be inserted into a text block by clicking on the “Merge tags” button in the expanded text block toolbar. The button is not shown if no merge tags were submitted in the configuration file.
Merge tags also become available to the user by pressing the @ key on the keyboard while editing a text block.
Here is an example: the user wants the date of the last order to be inserted after “[…] placing an order on …”, so he/she presses the @ key and selects “Last order date” from the list of merge tags found by the builder in the configuration file.
After inserting the merge tag, the text block now shows the placeholder for the last order date.
You can load Merge Tags in the builder when it is initialized by adding a mergeTags
node to the JSON configuration file. For example:
Merge content differs from merge tags in that it allows the user to drag and drop instances of it as a content element available in the Content panel.
For example, let’s say you have a section of an email where you want to display some recommended products: Merge Content allows you to insert some syntax into the message that your application will replace with the recommended products at the time the email is sent.
When Merge Content elements are submitted to the builder in the configuration file, a new tile is displayed in the Content panel.
The user can drag and drop it into the message just like any other content element.
Once dropped in position, the settings panel will display the instances of merge content available for selection.
To create another instance of merge content, the user can either drag and drop it again from the Content tab, or duplicate the existing content element…
… choose another instance of merge content from the available selections…
… and then drag it elsewhere in the message.
Just like with Merge Tags, you can load Merge Content in the builder at the time it is initialized by adding a mergeContents
node to the JSON configuration file. For example:
Merge tags are meant to be placeholders that will be replaced at the time an email is sent, or the web content is generated for visitors.
You cannot use HTML code in the text strings passed to the builder because – if you do – it will be encoded and will not function correctly in the source code of the message. Of course, you can replace the tag with HTML code at the time of saving or sending the message.
Standard merge tags do not support sample placeholder content, for now. The syntax will be displayed in the builder as your users design the message or page.
Additionally, there are some other limitations that are specific to the Merge Content feature. Among them:
Users cannot see & edit the content: what’s in it, the style used, the layout, etc..
Not seeing it, they could select the wrong content from the list of available Merge Content.
The HTML might be created outside of Beefree SDK, which could lead to rendering issues when it’s inserted into the message.
Since the HTML is created elsewhere, and it’s not part of the document created by Beefree SDK, it must be managed separately.
Learn more about injecting custom JS libraries into your Beefree SDK integration.
Custom JavaScript requires a complete technical evaluation by the Beefree SDK development team. The assessment will undergo security, technical and compatibility assessments.
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:
Our representative will forward your request to our development team
The development team will review the script and approve it
The script is enabled by our development team
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:
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).
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.
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.
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.
Take the following steps
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
.
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.
The following code sample displays an example of how to add advanced permissions for the color picker to your configuration.
The table below outlines the configurable parameters for the color picker.
canViewColorInput
boolean
Hides or shows the text input for the color picker in the sidebar.
Default value is true.
canViewSliders
boolean
Hides or shows the sliders inside the color picker popover.
Default value is true.
canViewSwatches
boolean
Hides or shows the swatches inside the color picker popover.
Default value is true.
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.
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.
It’s all good until things scale up. For example…
Since the Beefree builders are used in hundreds of applications, and since each of them is facing different user experience challenges like the examples mentioned above, we decided that this was really a case where one size does not fit all.
So we engineered a solution that puts you in control and provides a large amount of flexibility.
If your users want to insert a merge tag or a display condition, you control how that will happen. You can overlay a window on top of the editor, for example, and display a simple search box, a list of categories to browse, or a complex configurator to build an advanced conditional statement.
We call this feature Content Dialog.
Content Dialog allows you to build user interfaces for your users to locate & insert merge tags, links, conditional statements, and more. It lets you establish an interaction layer between the editor and your application (e.g. you show a pop-up window) that allows your users to locate/build/insert specific content (merge tags, links, conditional statements, etc.). And you’re in full control of the UI.
For example, imagine you want your customers to be able to quickly locate a link to a product page and assign that link to a button, image, or text. Content Dialog will let you build the right user experience.
Here is a visual example of what you could accomplish in that find a product link scenario.
The user experience in this interaction layer is entirely up to you. In the example above, the user clicked on “Find a product” (or alike) in the editor, and a modal window was shown, with a search box in it. Since you decide what the user experience will be like, you are fully in control of how users will select and insert:
For each type of content, you can define the action that will be triggered in your application (e.g. display a modal window), and the text that will be displayed in the Beefree SDK editor’s UI to trigger that action (e.g. “Locate a merge tag”), keeping a consistent UX with other areas of your application.
Content Dialog introduces new call-to-actions in the editor UI.
Depending on the type of content, the call-to-action will be rendered as a button, a link, or a drop-down choice (see below a detailed list of UI changes).
The text for the action is defined by the host application, so you can use your own wording to provide a better experience.
An example of a possible workflow when the user clicks on a content dialog action:
The editor will start waiting mode (same as when the save action is triggered)
This mode prevents users from further editing and keeps the focus on the user selection
The waiting mode is interrupted if the host application cancels the action
The host application will display to the user a UI element to select or define a content item
When the selection is done, the host application closes the UI and passes it to the editor
The editor receives from the host application the selected content and exits waiting mode
The content is applied to the selected item
The same example applied to special links (link to a product) in a text selection:
The editor starts waiting mode
The host application displays an overlay that hides the editor and lists the categories of products to link. The user browses them to find the desired product and selects it.
The editor receives the link and exits waiting mode
The link is applied to the selected text
To set up content dialogs you will need to add the contentDialog
object to beeConfig
:
For rowDisplayConditions
, there is a third parameter called currentCondition
. Use this parameter to return a row's current display condition. This parameter returns an object with the following format:
Note: You do not have to name the parameter currentCondition
. You can use any name that works best for your application and workflow.
You can add all the dialogs, some of them or only one. Is up to your application to create them for all the users or a segment, as there are no related server-side settings, you can customize them for each editor start.
All the dialogs use the same pattern, but the returned object must match the element pattern (described in the following section).
Defines the text displayed in the editor UI.
A resolve or reject call is mandatory. If you miss this step, the editor will remain in waiting mode. Error management on the host application must call the reject function to unblock the editor.
The following code snippet displays and example of applying a link action.
When the user clicks on Add an Example Link, the URL http://www.example.com is applied to the selection (a button, an image or a text).
The waiting mode will not be perceived, and there is no cancel action.
The following code snippet displays and example of applying a link with a delay.
The setTimeout
function in the above code sample is used to delay the execution of the enclosed code. It delays the call to the resolve
function by 2000 milliseconds, or 2 seconds. This means that after initiating the special link dialog process, the application will wait for 2 seconds before adding and displaying the specified special link with the label 'external special link' and the URL 'http://www.example.com'.
The following code snippet displays and example of opening a dialog UI element.
In this example the openMySpecialLinkDialog()
should be replaced with a function that opens a modal window (or other element) of the host application, where the user can select or build a link.
The selection is then returned as the value of specialLink
to the resolve()
function.
A cancel action will trigger the reject()
function instead.
Values must use the same pattern used in the beeConfig
object.
The returned object is validated against the expected format.
If the validation fails, an error will be returned in the browser console:
E.g., Error getting content rowDisplayConditions, the item is malformed.
These errors will not trigger any visible notification in the UI.
Merge tags allow you to dynamically insert values into your content, such as user information or other variables. This section will guide you on how to configure merge tags in your host application. See the following section for sample code on setting up merge tags in your content dialog configuration.
Open your content dialog configuration file:
Locate the file where you configure your application's content dialog.
Add the contentDialog
object:
If it doesn't already exist, add the contentDialog
object into your configuration file.
Configure the mergeTags
property:
Inside the contentDialog
object, insert the mergeTags
property as shown below:
Define the handler function:
Within the handler
function, write your logic to dynamically insert values into the content.
Add a corresponding action in the text toolbar:
Ensure that the text toolbar includes an action for the merge tag element, allowing users to apply dynamic syntax easily.
Test your implementation:
Validate that the merge tags are working correctly within the UI, ensuring that the dynamic values are properly inserted.
You can add a new action, available in the text toolbar, and associated with the merge tag element:
Your application has a high number of placeholders and needs to provide a categorization or search form
Placeholder availability depends on options that the user can select while building the message
You want to display the same UI your users already know and use in your application
You need to separate merge tags from other text placeholders
The following code snippet defines an object with name
and value
parameters meant for handling placeholders in an application. The name
parameter, although not immediately displayed, is useful for later reference if the user selection is saved and reloaded. The value
parameter contains a text string with specific syntax. This is for inserting dynamic content. This setup is important for applications to manage many placeholders or custom text fields efficiently.
Special links are dynamic URLs embedded within emails to execute predefined actions, such as:
Unsubscribing a recipient: Allowing users to easily opt-out from mailing lists.
Loading a Web version of an email: Enabling recipients to view the email content in a browser.
Sending the email to a friend: Facilitating users to share the email with others.
A few end user benefits of using special links are the following:
User Convenience: Simplifies adding recurring URLs and actions to designs, which increases efficiency throughout the design creation process.
Consistent Implementation: Ensures URLs and actions are consistent and accessible across various platforms.
By incorporating special links, end users benefit from the ease of managing various links efficiently across diverse platforms.
This section will explain how to configure special links with steps and provide a code sample to help get you started.
Take the following steps to configure special links in your application:
Define a contentDialog
object within your configuration or settings file.
Add a specialLinks
property to the contentDialog
object.
Set the label
property to the desired name for your link, for example, 'Search a post link'.
Create a handler
function within the specialLinks
object where you will define the custom logic for handling the link.
Ensure this handler
function takes resolve
and reject
parameters to manage its behavior.
The following code snippet provides an example of how you can configure special links.
The following image shows an example action that applies to image or button content types.
Apply links to products or news using a categories pattern, a search form, or a visual browser
Apply special parameters or configuration to certain links with a wizard or form
You want to display the same UI your users already know and use in your application
In the following code sample, the parameters serve the following purposes:
type: Represents the type of link but will not be shown to the user directly.
label: Provides default text for the link if no specific text is selected.
link: Contains the URL that will be applied when creating the link, with the possibility of using placeholders.
Merge contents is a feature that allows you to consolidate multiple content sources into a unified display. This section will cover how to configure this feature and its most common use cases.
Access the configuration file of your application.
Locate the contentDialog
object within the file.
Add a mergeContents
property to the contentDialog
object.
Inside the mergeContents
property, set a label
with the description you want to appear, such as 'Set up a new product recommendation'.
Implement a handler
function that will process your custom logic. This function should accept two parameters: resolve
and reject
.
Insert your specific code inside the handler
function where indicated.
Your configuration should look like the following:
The content dialog adds a button to the merge content list as shown in the following image.
A few of the most common use case for merge contents are the following:
Set up the content and/or layout for a product recommendation
Set up the content and/or layout for a dynamic advertising
Set up the content and/or layout for another type of targeted content
In the following code snippet, the properties perform the following tasks:
name: This property specifies the display name of the content. It appears in the editor UI and helps users identify the content item within the messaging interface.
value: This property represents the actual content that will be injected into the HTML output, shown in the preview. The {{ syntax }}
is typically used for dynamic content insertion.
Display conditions allow you to control when specific content is shown based on predefined criteria. This section will cover how to configure display conditions in your application and common use cases.
To configure display conditions in your host application, take the following steps:
Define the contentDialog
Object: Start by defining an object called contentDialog
in your code. This object will hold the configuration for the display conditions.
Add the rowDisplayConditions
Property: Within the contentDialog
object, add a property named rowDisplayConditions
. This property will specify the conditions under which a particular row is displayed.
Set the label
Property: Inside the rowDisplayConditions
object, define a label
property. This property sets the text label for the display condition. For example, to set the label as "Open builder":
Define the handler
Function: Add a handler
property inside the rowDisplayConditions
object. This property is a function that determines the logic for your display conditions. It accepts two parameters: resolve
and reject
, which are typically used for promise handling.
Implement the Display Logic: Within the handler
function, implement the logic to determine whether the row should be displayed. Use the resolve
function to indicate the conditions are met, and the reject
function to indicate they are not.
Complete the Configuration: Make sure your configuration object is properly closed and integrated into your application. Ensure that all necessary conditions and logic are correctly defined within the handler
function.
Customize the logic within the handler
function to meet your specific needs.
A new button will be available in the display condition widget. In this example, the button says “Open builder”, which is the label
shown in the JSON configuration file shown above.
A few of the most common use case for display conditions are the following:
Display a condition builder or form to target a segment of recipients
Display a form to create a loop with the row dynamic contents, as product recommendations
The following code snippet configures a display condition with a specific label, description, and delimiters that define the start and end of the condition block in the template. This will be shown in the editor UI and inserted around the selected row based on the specified conditions.
In this example, a window is shown to users when they click on the button to open the builder.
The UI is entirely up to the hosting application. Here, the developer decided to offer some fields at the top where the Display Condition can be named and described, an area below it where parameters, values, and operators can be selected, and a preview on the right.
When users click on “Confirm”, the information is passed back to the editor and shown in the properties panel.
Custom rows allow you to import products or news using various patterns, set up predefined content layouts, and create dynamic sections for recommendations, codes, and advertisements. This section will discuss how to configure custom rows in your host application.
The following code snippet displays an example of how to configure custom row.
The content dialog adds a new item, using your text label, in the Rows drop-down:
A few of the most common use case for custom rows are the following:
Import a set of products or news, as custom rows, using a categories pattern, a search form, or a visual browser
Set up the row layout for a set of predefined contents
Set up rows with dynamic content to build dynamic sections that provide product recommendations, QR or bar codes, advertising content, etc.
The following code snippet configures a custom row with a specific name and value. This will be shown in the editor UI in reference to a specific custom row based on the specified conditions.
This response will:
Create a new drop-down choice with the provided name
Display the rows provided by the URL in the rows panel
Notice that in the rows list, names returned by the content dialog display as highlighted elements to give them further visibility over starting choices.
The content dialog can be used as many times as the user needs and, depending on the response, the behavior may change:
This overwrites the existing results, keeping the same name in the drop-down. This behavior perfectly matches our example above, where the host application returns “Your search results” every time the content dialog is resolved.
This creates a new drop-down choice, keeping the previous results as selectable elements. Previous results are available directly in the drop-down. Usage example:
The label
, description
and notPermittedDescription
fields handle the wording related to the “Edit synced row” call-to-action/button. Here’s how and where they are used:
label
: Label related to the sidebar button that triggers the content dialog
description
: Description of the action on top of the button
Here’s an example of what label
and description
would look like:
And here’s an example of what notPermittedDescription
would look like:
Save rows refer to the functionality that allows users to save changes made to specific rows in a data table. This section will discuss how to configure the Save rows feature in your host application.
The following code snippet displays an example of how to configure save rows.
Unlike the rest of content dialog configurations, Save rows doesn’t use the label
parameter as the UI element is a save icon displayed on the selected row (and in the row’s properties panel):
The Save rows content dialog is a mandatory step in the Save rows workflow.
The args
object in the handler function returns to the host application metadata already applied to the selected row.
The following code snippet configures a save row with a specific name and category. This will be shown in the editor UI in reference to a specific saved row.
The row name is the only required metadata and it’s displayed as the row title in the Rows panel:
A string of plain text that identifies the row.
Displayed in the row card when the row is shown in the Rows panel.
Used for text searches within the Rows panel
Forms are interactive elements that allow users to input and submit data. This section will discuss how to configure forms to meet specific requirements in your host application.
If you want to have total control on the forms that a Beefree SDK application displays and renders, you can use this forms Content Dialog rather than passing a single form to the Beefree SDK application.
The args
object in the handler function returns to the host application the form object already applied. With this information, the application can decide what to display to the user (e.g., edit the current form, suggest a similar form, etc.).
Custom attributes are user-defined metadata that can be added to links and images within an editor. This section will discuss how to configure custom attributes in your host application.
If your end users need to apply custom attributes to the links and images in their content, you can completely customize the user experience and workflow for adding those attributes with a Content Dialog that will take over the editor’s UI. The dialog will need to return the attribute to apply.
Custom video allows you to integrate and configure videos from custom sources other than standard platforms like YouTube and Vimeo. This section will discuss how to configure custom video for your host application.
The following code snippet displays an example of how to configure custom video.
It is possible to leverage the Content Dialog method to add videos from custom sources – other than YouTube and Vimeo.
You can use the addVideo
Content Dialog modal, which will take over the builder’s UI. The video will be added as a thumbnail in the content area.
The user must fill out the video URL from a custom source, the image used as a thumbnail, and an alt text/title by implementing a custom modal window (optional). When the user clicks on the video thumbnail, it will open videoSrc
in a new tab/window.
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.
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:
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.
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.
Sample content strings are not limited to the preview, but can be displayed in the editor’s stage as mentioned above.
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.
Use this method to replicate the behavior described for the standard toolbar.
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.
The following image displays the Title and Description fields from within the page builder.
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:
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:
The following code snippet is an example of what the Meta Tags will look like inside the JSON.
The following image displays the Subject and Preheader fields from within the email builder.
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:
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:
The following code snippet is an example of what the Meta Tags will look like inside the JSON.
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:
With Custom Attributes, your end users can easily append additional information to HTML tags in emails and web pages, at the same moment they are creating their content in Beefree SDK. These attributes can be applied to links, both in text blocks and buttons, and images, and they serve a variety of scenarios: personalization, segmentation, styling, accessibility, etc.
Custom attributes enable a wide array of use cases, depending on your application’s capabilities and your users’ needs. Here are a few examples:
flagging specific links so that user activity for those won’t be tracked (e.g. clicktracking="off”
in SendGrid);
handling internal statistical segmentation or reporting (e.g. data-reportingname="October_promo" data-reportingtags="promo,iphone"
);
adding conditions to a single content element (using an attribute such as condition="customer_exists"
);
embedding a single image by adding an attribute like embedded="true"
, processed when the message is sent;
adding custom CSS classes for custom CSS;
adding WAI-ARIA attributes for accessibility requirements.
The host application can provide the editor with a list of attributes that will be available to the user through the UI. How the attribute value is formatted impacts how the builder UI displays it and how the user interacts with it.
Custom attributes can be applied to:
Links in text blocks
Links in buttons
Images (including thumbnails generated by the Video block)
For images and buttons, these attributes will be visible in the editor sidebar, under the new “ATTRIBUTES” section.
For links in text blocks, they will be part of the dialog window for creating a link.
You can provide the editor with a list of attributes that will be available to the user through the UI. How the attribute value is formatted impacts how the builder UI displays it and how the user interacts with it.
Depending on how custom attributes are implemented, users may:
add a custom attribute from a list of attributes already defined, and specify the value of the attribute, if appliable:
from a predefined list
in a text input
defining a boolean property (yes/no, true/false, etc.)
add a “custom” custom attribute by manually specifying both name and value
open an additional interface, through a content dialog, where users have complete freedom on how to build custom attributes.
Regardless of how a custom attribute is added, it will be included in the a
or img
tag when HTML is generated for an email/page, like the segment attribute in this hyperlink:
Custom attributes are a client-side configuration that needs to be passed when initializing the editor. There are different shades of implementation complexity, based on the outcome you want to obtain. These approaches can be combined as preferred.
The easiest implementation is to just pass a simple configuration at startup:
With this setup, users can indicate a “Custom” custom attribute by manually specifying Name and Value. Please note that users must know exactly what they are doing, as there will be no guidance in the editor.
You can pass the necessary custom attributes in the initial configuration. Those attributes will be available in the interface, and the user will be able to specify the value for these attributes, if possible.
Let’s look through the attributes defined in the example above, and how they will look like in the builder.
The Deeplink
attribute has a single, predefined value, so when added in the builder it will look like this:
The Segment
attribute has two possible values, which can be selected by the user:
The Class
attribute has no defined value, so the user can enter anything in a text input:
You can customize the list of fonts available in the editor’s text toolbar and the body settings panel.
This feature allows you (or users of your app) to:
Expand the list of available fonts, adding web fonts from popular services, such as Google fonts, font library.org or alike.
Reduce the list of fonts to a limited number of options, removing some or all our default fonts.
This flexible approach will help you use this feature in a variety of scenarios. A few example scenarios are the following:
You want your users to customize the list of fonts loaded in the builder when they edit designs. You can now create an interface in your app to do so, and instruct the editor accordingly (see below).
You have multiple levels of users, and you want “contributors” to only see a subset of approved fonts, while “editors” have access to a larger list.
You are a digital marketing agency, and you want to customize the list of fonts in the editor depending on the client/brand for which the email message is being designed.
In this example default fonts are loaded, and two new fonts are added: a web safe font (Comic Sans) and a Google hosted web font (Lobster).
Here is a more detailed description on how the editorFonts object is built:
showDefaultsFonts
This boolean parameter indicates if the entire list of default fonts is available or not. When the value is false, only the fonts added as custom fonts will be active in the editor.
customFonts
When the default font parameter is true, the custom fonts declared inside this object will be added to the list of default fonts: both are loaded into the editor. Otherwise, only custom fonts will be shown.
Each customFonts
element can have the following properties:
When we add a set of custom fonts, we can decide between system fonts and web fonts. Let’s see some details on what you need to know:
System fonts are installed on the operative systems and don’t need any external resource to work, so we can skip the url parameter.
Web fonts are hosted online and need to be loaded by the email client when the email is opened. Beefree SDK accepts only the CSS font embedding method, and the CSS file must be hosted in HTTPS protocol. You can use services like Google fonts, that provides host, font stacks and a well formatted CSS file.
We want the editor to work with only 2 fonts when creating a message, we want that only Lobster and Cabin fonts are available when editing this message:
In the following example, instead, we don’t want to add new fonts but restrict the default ones to our own selection:
Notice that if you want to change the default set of fonts, you need to disable them and use custom fonts to indicate the new set, including the URL parameter for web fonts.
This is the complete list of the default fonts in the application and its configuration, including the external URL for web fonts:
In this example, we want to add font weight options to our list:
We open a saved template that uses fonts that are not available:
System fonts will display normally in the editor and the text can be edited, but the font-family is not available in the font selector.
Web fonts will fallback to a system font. Text can be edited and the font-family is not available on the font selector.
We are able to save the message that already uses unavailable fonts.
With Commenting, teams using your application can collaborate asynchronously on the same email, page or popup, in order to get their work done more quickly and reach approval for going live more efficiently.
When Commenting is enabled, your end-users (or contributors, as we’ll call them in this context) can:
Add a new comment in any content block or row, so that the context of the discussion is always visible;
Reply to an existing comment and start a thread;
Mark existing threads as resolved, and reopen solved threads if necessary.
Copy the text of a comment, and paste it back to the content area
Preview comments by hovering over the comment icon
Automatically highlight the row where a thread is posted
Receive a notification straight in the builder when a new comment is added during a co-editing session (Superpowers users only).
With Commenting, you enable asynchronous, visual collaboration when multiple collaborators are creating, editing, and reviewing content in the Beefree builders. This collaborative feature can prove extremely beneficial in different contexts, regardless if contributors are in the same team, in separate teams, or even in different companies (e.g. digital marketing agencies collaborating with their clients):
have a single source of truth for feedback and requests on the content created with the builders;
cut time-to-publish, reducing back and forth conversations, both online and offline;
get sign-off for going live for email and web campaigns more efficiently.
Commenting – like most other features – is made available to Beefree SDK customers in an OFF state by default, and must be activated in the Beefree SDK Console.
To do so:
Click Details next to the application you want to configure
We recommend you first familiarize with Commenting in a Development or QA application
Click view more under Application configuration.
Toggle Enable commenting ON and click the Save button to activate Commenting for the application.
To activate Commenting when launching your Beefree application, you will need to pass a username
, userHandle
, and a userColor
in the configuration parameters. See this example:
When opening an email, a landing page or a popup, a contributor can add a new comment to a content block or a row by clicking the “Balloon” icon, available in two spots:
in the row or block outline, inside the editing stage
in the header of the Row properties or Content properties
Clicking one of these two icons will activate the commenting panel, which takes over the editor sidebar. From there, the user can insert a new comment. After the first comment, another contributor can start a thread by adding a second comment.
If you have implemented mentions, users can type @ to bring up a list of contributors and tag them in the comment. If the user starts typing, the list will be filtered If you’ve built a notification system around Commenting, you can use this piece of information to trigger a notification towards the mentioned person.
If you added a Content dialog for mentions, the action will be triggered by the button at the end of the list. You will define the CTA for this button as part of the Content dialog configuration (in this case, “Send an invite”).
If there has already been some activity, the editing stage shows whether a content block or row has any comments by displaying a small comment icon. The sidebar instead indicates the number of existing comments for the selected row or content block, three in this case.
Activating the Commenting panel will bring up the thread. In this case, it will show the three comments.
Existing comments can be edited or deleted by the contributor that added them. Contributors may also resolve comments when they have reached a consensus and completed any pending task.
Improved accessibility to in-line threads. Hover the mouse over the comment icon to see a preview of the last comment added.
Clicking on < All comments in the top section will bring up a list of all comment threads, indicating which ones have been resolved and which ones are still open. Contributors can search inside comments and filter out solved threads, or threads that were part of deleted content. Deleted and hidden comments will be filtered automatically.
To go back to the editor sidebar, contributors can close the Commenting panel by clicking the X icon in the upper right, or they can just click on another row or content block in the stage.
Quickly reopen resolved threads by adding a new comment, expand threads with a click, and show a comment thread preview straight from the content area.
Suggest edits in seconds, and save time with the copy/paste feature. Copy text from the comment body and paste it directly into the content area.
With the Reviewer role, you can now allow users to collaborate on your projects without changing the design. This role helps provide peace of mind by allowing inexperienced users to work with the team on their designs, without fear of accidentally changing it.
In short, this new role has the following characteristics:
Can’t apply changes to the message
Can add comments and start threads
Can edit their own comments
Can view other comments
This new role can be easily enabled by passing the following parameter in your configuration:
Once you turn on the feature in the Beefree SDK Console, you may want to disable Commenting for some customers. You can do so via the client-side configuration document that you feed to your Beefree application when initializing the editor.
Why? Because you may decide to make the feature available to customers of your application:
depending on the subscription plan that they are on (i.e. you could push users to a higher plan based on the ability to use Commenting);
depending on the purchase of an optional feature (same);
only if they are “beta” customers, so they see it while keeping it hidden from the rest of your users.
Here’s how to do so:
Enable Commenting in the Beefree SDK console, as mentioned above.
Add the configuration parameter commenting to the beeConfig document
Set it to false for all users that cannot comment.
Here is a simple example:
You can build a notification system around commenting by triggering a callback for events in the Commenting layer. When these events happen, the Beefree system triggers the onComment
callback.
You can react to that callback by taking the information provided in it (e.g. the user that created the comment, the text of the comment, any mentioned user, date & time of the comment, etc.) and send notifications.
You are free to define:
which events will trigger a notification
how it is sent (e.g. Email, In-app, Slack, etc.)
what exactly it says
Again, remember that the Beefree platform only triggers the callback, and it’s up to you to react, if you want. Below you can find the technical details on the comments schema and the onComment
callback.
Define an array to hold the list of mentioned users in the comment payload.
Loop through the comment payload and add any strings matching a regex to the array
Compare each value in the array with the ‘handle’ property of each user (as defined by the host application), to grab the active users
Loop through your array and pull the respective email address for the handle matches (for use in notifications)
Send the notification through email (via ajax), slack, etc… (you decide and implement how to send the notification)
The following JSON is saved as part of the template:
You may want to save multiple copies of a template, e.g. to create a history/revision or a draft feature.
In such cases, you may decide to store the comments in a database, and add the schema back to the template when it’s loaded. Alternatively, you can keep the comments inside the template, and it will become a static part of the history.
Comments can also be added dynamically, but it’s an advanced task, which requires matching the comment schema to the target content by its “elementId”.
When a thread or comment changes, the Beefree system triggers the onComment
callback. The callback returns the following details:
JSON contains all the details on the change
JSON array of the entire comments schema, as described in the previous section.
JSON contains the contributors
array with all users in a thread.
NEW_COMMENT
COMMENT_THREAD_RESOLVED
COMMENT_THREAD_REOPENED
COMMENT_EDITED
COMMENT_DELETED
JSON contains all the details of the change
You can activate a mention dialog for comments by adding a data source to the Beefree application configuration. You can use the “Hooks” data source method to fetch data from your application and pass it to the Beefree system in real-time.
To configure a hook data source, define the hooks
section in your bee config and implement the getMentions
method.
You can also extend the default mention dialog via Content Dialog. For example, you can enable end-users to to invite an external user not available in the data source.
To configure a hook content dialog, define the contentDialog
section in your Beefree application configuration and implement the getMention
method.
You can generate a link to a specific comment, which can be used to notify the user. Common use cases include sending a link via email, Slack, API, or via in-app messaging. To implement this action use the onComment
callback combined with a new instance method called showComment
.
The onComment
callback contains the comment’s id and a new section called “mentions” containing an array of mentioned users’ uid values.
With the uid
, your application can look-up the user’s contact details. The Beefree platform does not track any sensitive information, such as user emails!
Similarly, since mentions can trigger events and the uid
can generate notifications, you can match uid
to userHandle
.
Next, using the comment’s id, your app can generate a link back to the email containing the comment. The new showComment
instance method can be invoked from Beefree’s onLoad
callback to send the user directly to the comment as soon as the editor is fully loaded and ready.
Note: In the sample below, getParameterByName
is a function that takes the commentId
from the browser’s URL query string.
It may be also be used to protect application or customer-hosted content delivered to the editor, such as custom rows or other host app-specific content. The extra token helps the host application to apply an authentication layer to the contacted endpoints.
Please note that all custom headers will be prefixed with “X-BEE-“ identifier. For instance, in the example above, the header will be sent to the host app as X-BEE-Authorization
.
If data from Beefree SDK is available, it will be sent in the args
parameter (see below). Once the value is available, you must call the resolve(value)
function to pass it to the editor. In case you want to cancel the operation, call the reject()
function.
Please note that a resolve
or reject
call is mandatory. If you miss this step, the editor will remain in waiting mode – and the error management on the host application must call the reject()
function to unblock the editor.
The args
parameter is where the File Picker’s Content Dialog will receive additional data.
The following is the most basic example, which returns an image URL immediately after clicking the “Browse” button. This example does not open a file picker.
In a real-world scenario, the host application would display a file picker UI and let the user search for and locate the file before finally returning the file’s location (URL) to Beefree SDK:
The following is a list of all modules that are sent as part of the args parameter:
sidebar.link
buttonModule.link
imageModule.link
iconsModule.link
menuModule.link
iconsModule.src
socialModule.src
textModule.link
imageModule.src
titleModule.link
row.backgroundImage
backgroundVideo.src
toolbar.specialLink
sidebar.specialLink
In Beefree SDK we introduced the idea that some content may be editable by some users and not others. For example, you may want the header and footer section of an email newsletter to be locked, so that it cannot be inadvertently modified when creating the latest version of your weekly news digest.
Internally, we’ve been calling this feature “Restricted editing”. Others refer to it as “locked regions”, “blocked content”, and more.
To allow for this, we created ways for the application hosting the builder to define user roles and set their permissions. Let’s take a look at how the feature works first and then show you how to configure your application to take advantage of it.
The user roles that you create (e.g. Brand Manager, Senior Editor, Junior Editor, etc.) can have different permissions. You can create as many or few user roles as you wish. The permissions that you can assign to them refer to:
Locking content (entire rows or specific content blocks)
Editing locked content
Specifically, the permission settings that can be configured for each role are:
Can lock rows (if active, all other permissions are granted)
Can lock modules
Can edit locked rows
Can edit locked modules
Can select Display Conditions
Can edit Display Conditions
Can remove Display Conditions
For example, a Brand Manager all four permissions checked, whereas a Senior Editor might have editing access to rows and modules, but won’t be able to lock rows and modules. Let’s take a look at a few scenarios.
If the user has this permission, locking a row is very easy to do. That user will simply select the row they would like to lock and click on the lock/unlock radio button in the row properties panel.
If a user does not have the permissions needed to edit a locked row, they will see a friendly error when they attempt to select the row, notifying them that the row can’t be edited:
Likewise, they will not be able to drag & drop any content blocks on the locked row, as shown here:
You can restrict access to layout changes while granting access to content modifications by using user roles and permissions.
This allows you to give your users editing access to the content, while ensuring that the overall layout of the message is not altered, and that specific content blocks that should not be modified are left “as is”. This way, for example, a junior member of the marketing team could focus on updating text & images, without worrying about potentially modifying the structure of the message in an unwanted and/or unauthorized way.
Or, as shown in the example below, the same user could update social media icons and links in the footer of an email, without altering legal language and dynamic fields used in the same footer. That’s accomplished by setting us a social media module that’s editable (unlocked), but in a row that’s locked.
When users without the proper permissions try to edit, move or remove the row, they are told that they may not do so.
Similarly, if they try to edit any content is the row that has not been specifically unlocked, they are told that they are not able to do so. In this case, for instance, the user is not able to edit the merge tags used in the footer of the email.
However, when they click on the social media icons, they are able to edit it.
To accomplish the above, a user with higher permissions needs to:
Open the message in the builder
Lock a row
Unlock one or more specific pieces of content within the row.
In the Manage Roles section you’ll be able to create different user roles and set their permissions. For example, your user roles could be Brand Manager, Account Manager, Junior Editor, etc depending on your needs and nomenclature. For each user role you create, you can set and restrict editing permissions, such as the ability to lock or edit rows and content blocks, as you can see below:
Once you create your user roles you’ll be able to see them listed:
While Role Name is a friendly description of that user role, Role Hash is the parameter that identifies that particular role in Beefree SDK. It must be an alphanumeric string between 8 to 30 characters: it can contain letters and numbers, but cannot contain spaces or special characters (such as “-“, “_”, etc.). You will need to save these role hashes in your application, at the user level – or at the user role level, if you have the concept of “roles” in your application – so that you can retrieve them and pass them to the application when you initialize the builder for that specific user.
The property name is: roleHash
.
For user roles to become active in the builder , you will need to add this new property to your Beefree SDK configuration when you configure the builder for a specific user. You will pass:
roleHash: "roleSpecified"
for each of the user, depending on its role. For example, if the Role Hash for a “Junior Editor” is “juniorEditor”, the application configuration will include:
roleHash: "juniorEditor"
This section goes in more details about the various combinations of permissions. It might help you understand how to best put this feature to work in Beefree SDK with regard to locking & unlocking rows and content blocks.
First, we created some hypothetical roles by using all application combinations of the available user permissions at the row/content level.
Then, we created a table with a number of possible “actions” and see which user role would have access to which actions. This allows you to map a certain combination of permissions (from above) to a specific task carried out in the Beefree SDK builder.
With Advanced permissions, you can tailor permissions for users of your Beefree application by hiding or locking UI elements related to:
content tiles
content settings
layout settings
row & content actions (clone, delete, drag, save)
basically anything in the editor!
These advanced permissions grant total customization of the experience you want to present. Since you set them in the configuration parameters passed to your application after you’ve initialized it, they could be different each time the editor starts, and have different setups for different users.
You can create roles that can act only on a content type. For example, you may want a “copywriter” role for people in an organization that only need to touch copy for editing or translation purposes. To do so, you can:
hide any action that doesn’t involve working on the copy of an email or page.
limit style options for the text itself, by
locking/hiding the side tab;
hiding specific settings in the text toolbar.
You can limit how users upload and manage images and files inside Beefree SDK; for example, you want some users – e.g., external collaborators – to select pre-approved images and files uploaded by “admin” users. You can do so by:
disabling drag-and-drop of images onto the stage;
When customers of your applications are structured businesses, typically with a headquarter and a locally-deployed organization (e.g., Real Estate, Travel, Retail), their administrators can create custom, secondary roles to match any internal policy they might have. In this scenario, admins typically want to reduce disruptions of centrally-deployed templates for external communication, while allowing a specific degree of freedom.
Initialize different versions of the editor
By combining multiple permissions, you can load Beefree SDK with radically different experiences, based on the user that starts it. For example:
a “stripped-down” version of the content builder for lower-level subscribers;
a “simplified” version of the builder for new users of an account.
To set up the advanced permissions, you will need to add the advancedPermissions
object to beeConfig.
Take the following steps to set up advanced permissions in your beeConfig
for Beefree SDK:
Locate your beeConfig
object: This is where you configure the Beefree SDK with its basic settings, such as the user ID and container.
Add the advancedPermissions
object: You will need to insert the advancedPermissions
object within your beeConfig
to specify which content types and settings can be customized with specific permissions.
Define content
permissions: Inside advancedPermissions
, you can specify what content blocks (e.g., image
, button
, text
) are visible and what actions are allowed.
Configure settings
permissions: This controls settings like content area width, background color, or fonts for different blocks.
Control tabs
visibility: You can manage which tabs (such as rows or settings) are visible and editable in the editor interface.
Set rows
behaviors: You can control row-specific permissions, such as adding or hiding rows, background colors, and mobile visibility.
Test the configuration: After adding the advancedPermissions
object to your beeConfig
, test your configuration by launching the editor and checking if the permissions are applied correctly (e.g., specific settings are visible or locked as intended).
The following table provides the name, data type, description, and an example value for the first-level fields for advancedPermissions
.
You can add all the permissions, some of them, or just one. It is up to your application to create them for all users or a segment, as there are no related server-side settings. You may have a different setup each time the editor starts.
All the permissions use a similar pattern, but the object must match the content schema for the type of content (described in the following section).
Each content type below contains a parameter for “behaviors” and “properties”. The behaviors control what someone can, or can’t, do. The properties parameter is an array of sidebar property widgets (e.g., the width slider), and each widget has its default permissions.
All sidebar property widgets (e.g. width slider, alignment, color, etc.) accept the following basic permissions:
Let’s look at an example of these permissions applied to an image module. The following example will hide the image width property widget and lock the text alignment widget. We’ll cover more of the available settings below.
All contents and rows (e.g. image module, video module, stage row, etc.) accept the following basic behaviors:
The components
object lets you control the behavior and permissions for tools like file pickers and link types within the editor. You can define what actions users can take, such as uploading or deleting files, and specify which link types (e.g., web addresses, emails) are available. This section provides more information on the component object within advanced permissions.
The following code provides an example of the filePicker
object.
The following code provides an example of the linkTypes
object.
The following code provides an example of the colorPicker
object.
The rows
object in Beefree SDK allows you to manage the behavior and appearance of rows in the editor. You can control what users can do with rows, such as adding, deleting, or moving them. Additionally, you can set permissions for properties like background color, stacking behavior on mobile, and visibility settings. Configuring the rows
object ensures users can work with rows in a controlled way, customizing their content without altering crucial layout elements.
Hosted Saved Rows includes advanced permissions to control how rows and categories are accessed and managed. These permissions allow you to define user capabilities, such as editing or deleting rows.
canDeleteHostedRow
: Allows or prevents deleting hosted rows.
canEditHostedRow
: Enables or disables editing of hosted rows.
canManageHostedRowCategory
: Controls whether end users can manage row categories.
canAddHostedRowCategory
: Determines if end users can add new categories.
If both canDeleteHostedRow
and canEditHostedRow
are set to false
, the row menu will be hidden.
If both canManageHostedRowCategory
and canAddHostedRowCategory
are set to false
, the category management menu will be hidden.
You can set Advanced Permissions for the Edit Synced Row button in the toolbar.
Available Permissions
show
: Controls visibility of the Edit Synced Row button.
locked
: Controls whether the button is clickable (false) or read-only (true).
Permission Behavior
If show
is false, the Edit Synced Row button is hidden.
If locked
is true, the button is visible but not clickable.
Depending on your configuration, when this button is visible and clickable, end users can:
Example Configuration The following example shows how to configure permissions for the Edit Synced Row button:
The following configuration displays an example of the rows
object inside of advancedPermissions
:
The following code demonstrates how to specify behavior settings for individual Row AddOns. A custom Row AddOn can have its behaviors set independently from the global row settings.
The columns
object in the Beefree SDK lets you control the behavior and permissions for columns within the editor. You can define what users can do with columns, such as adding, selecting, moving, or deleting them. You can also set properties like column spacing and border radius. Configuring the columns
object ensures that users can manage column layouts effectively, while maintaining control over the design and structure of the content.
The tabs
object in the Beefree SDK allows you to manage the visibility and permissions of different tabs within the editor, such as the Rows, Content, and Settings tabs. You can control which tabs users can access and whether they can interact with them. By configuring the tabs
object, you streamline the editor’s interface, ensuring users have access to only the relevant tabs they need for editing while maintaining control over what they can modify.
The settings
object in the Beefree SDK allows you to control various design-related settings within the editor, such as content area width, background colors, and default font styles. You can define which settings users can view or modify, such as enabling or locking background images or link colors. By configuring the settings
object, you ensure that users can customize specific design elements while maintaining overall control over the layout and style of the content.
The content
object in the Beefree SDK controls the behavior and permissions for different types of content blocks, such as text, images, buttons, and more. You can specify what users can do with each content type, such as adding, editing, or selecting them, and set properties like alignment, padding, and visibility. By configuring the content
object, you allow users to interact with content blocks while maintaining control over how each element can be modified within the design.
You should use the Icon object to set advanced permissions when you need granular control over the display and behavior of icon elements. This allows you to lock certain properties, such as the visibility and font weight, ensuring consistency across different devices and user interactions. Additionally, setting these permissions helps in maintaining a cohesive design by managing how icons respond to mobile and AMP environments.
In the given icon code, the structure is defined using objects, properties, and parameters to represent a detailed configuration. The main object, icons
, encompasses two primary properties: behaviors
and properties
, each of which is an object itself. The behaviors
object contains a property canResetMobile
with a boolean parameter set to false
, indicating a specific behavior setting. The properties
object holds various properties such as icons
, fontWeight
, align
, and more, each representing different characteristics and settings for the icons. Each of these properties has parameters assigned to them; for instance, the icons
property has show
and locked
parameters set to true
, determining the visibility and lock status of the icons. This nested structure using objects and properties with defined parameters represent the configuration settings in the code.
The table below outlines the configuration elements, their data types, descriptions, and default values for the behaviors object used in the icon configuration.
The table below outlines the configuration elements, their data types, descriptions, and default values for the properties object used in the icon configuration.
To successfully use this feature, follow these steps:
Identify the AddOn ID: Obtain the unique ID of the addon you wish to assign permissions to.
Define Custom Permissions: Based on the type of addon, assign relevant permissions in your configuration file.
Override Default Permissions: Specify advanced permissions for the addon, ensuring they override the default ones if needed.
Set Specific Behaviors: For row addons, include permissions for individual modules like image blocks inside the row addon.
Apply Global Restrictions: Optionally, set global restrictions for all mixed and row content addons for consistent behavior.
By following these steps, you can effectively manage and customize addon permissions.
The following code provides an example of the different content modules and the addons-id
.
The following code shows an example AddOn with the canViewSidebar
behavior set to true
.
The following code defines specific permissions and behaviors for different modules within a Row AddOn.
The following code shows an example config for how you can display or hide these buttons using advanced permissions.
We’ve put together a few JSON templates of custom roles created with Advanced permissions, so you can get started experimenting with this powerful feature.
Display conditions allow you to change the content that is shown to a recipient of an email depending on who the recipient is.
Your users will have the ability to pick a condition (or write one from scratch if they are technically savvy), apply it to a row, and thus show different content based on who the recipient (or viewer) is.
The feature provides a number of benefits, including:
Display conditions allow anyone that is using the builder to easily create personalized messages without writing a line of code.
Use whatever syntax your application understands. The feature is language agnostic: it can be used with whatever syntax matches your tech stack. Does your sending engine understand the Liquid markup? Then you can use Liquid. Does it use a proprietary templating language? No problem.
Restrict access to some of the functionality based on user roles. For example, some users may be able to edit the syntax of the conditional statements, while others may not. Use this flexibility to simplify the UI or promote upselling.
As the application hosting the builder, you can now pass an array of conditions.
Those conditions become available for users of the editor to select, assuming the feature is turned on and the user has permissions to apply a condition to a row.
They will do so by browsing through categories or searching by keyword. For example…
The condition that they pick is applied to the row and displayed when the row is selected.
It can be changed (i.e. the user decides to apply another condition) or edited (if the user has the technical skills to do so, and its user role has been granted those permissions).
When the Preview feature is accessed, users can now simulate what recipients in a certain segment will see by toggling Display conditions on and off.
When active, the feature is available to all users by default. You can manage who can see and/or do what by leveraging user roles and permissions.
When the feature is ON, new permissions are available for you to configure when you create or edit a Role.
A basic set up allows you to have 3 user levels:
Can only view & preview
None of the above options are selected
No widget will be shown unless the loaded message has display conditions assigned to one or more rows
If conditions are applied:
They are shown as ready-only
They can be applied in the Preview
Can only select
Only Can select conditions option is selected in the role settings (remove will be automatically selected too)
The widget shows and the user can select and apply any of the conditions specified in the editor configuration
The user cannot add a new condition
The user cannot edit a selected condition
Full control
All permissions are selected
The user can select and edit conditions (if provided) or add a new condition
Note: if there are no Display conditions passed in the configuration, and the user has the rights to access the feature, the editor will only show the Add condition action, which allows users to apply a new condition to a row by manually adding the condition’s syntax.
It’s easy to identify a row to which a display condition has been applied. A bifurcation icon is added to the row’s “Structure” tag, which is shown as you mouse over the row. Here’s an example:
When a default Display condition is edited – by a user that has permissions to do so – it becomes a custom condition. Custom conditions are easy to recognize because:
A blue dot is added next to the condition’s name
The “Change condition” button is no longer available: a custom condition can only be removed
The cancel icon is replaced by a trash button because an edited condition, once remove, is lost: it cannot be re-added.
Why these different behaviors for custom conditions? Because Beefree SDK does not save them to the configuration (you passed that configuration to the application: we don’t have access to the repository where you save that information). So, custom conditions do not exist in the array of conditions that the user can search and/or browse.
Conditional syntax and row content are isolated from each other in the HTML generated by Beefree SDK, so your system can delete, repeat or change elements inside the row without impacting other parts of the message. For example, the HTML of a row might look like this:
Here is an example of a custom builder of Display Conditions.
In Beefree SDK, Custom Languages allow you to accomplish two things:
Translate the default text in the builder to your preferred language.
Override the default text in the builder to your preferred text, even if you keep the same language.
Translating the default text in the builder is useful when you have diverse end users and you'd like to provide them with a builder experience that resonates with them.
Overriding the default text in the builder with your preferred text is useful when you want to customize the builder experience and apply your application's unique tone.
This page discusses how you can accomplish both use cases with Custom Languages. Keep in mind that you can utilize Custom Languages for overriding default text in the builder, even if you are not translating any of it to another language.
This section includes two examples on how to use Custom Languages based on the above scenarios.
Example One: Overriding Default Text
This JSON includes the default text in the builder, which you can see in the image of the Top bar below.
By adding the translations
parameter to the beeConfig
with the following configuration, the top bar can easily be customized.
The following image shows how this configuration appears in the builder.
Example Two: Translating Default Text
Translating the content to another language follows the same approach. The following configuration overrides the default text with the Spanish translation.
The following image shows the result of the configuration with the Spanish configuration.
You can override the default Beefree SDK language file by providing a URL to your own translations. This is an advanced feature and will replace all languages used by the editor with the languages defined in the custom file.
Overriding the Help icon label in the default toolbar
Overriding the Rows tab label in the sidebar
Overriding the Preheader
Defining or adding a translation for "email"
The following code defines a translation object where the title for "bee-settings-details" is set to "New Email Details" specifically for the "email" field.
The following image shows the results for the overwritten default text for AI Paragraph Assistant based on the above configuration.
The following image shows the results for the overwritten default text for AI Title Assistant based on the above configuration.
The following image shows the results for the overwritten default text for AI List Assistant based on the above configuration.
The following image shows the results for the overwritten default text for AI Button Assistant based on the above configuration.
The following section lists translations that correspond with Confirmation Dialogs for Rows, Columns, Modules, and the File Manager.
This list details the translations corresponding with the Delete Row Confirmation Dialog.
Title: 🆕 Delete row
confirmation-dialogs.delete-row-confirmation-title
Secondary Button: 🆕 Keep
confirmation-dialogs.keep-button
Primary Button: 🆕 Delete
confirmation-dialogs.delete-button
This list details the translations corresponding with the Delete Column Confirmation Dialog.
Translations Variations
Title: 🆕 Delete column
confirmation-dialogs.delete-column-confirmation-title
Secondary Button: 🆕 Keep
confirmation-dialogs.keep-button
Primary Button: 🆕 Delete
confirmation-dialogs.delete-button
This list details the translations corresponding with the Delete Module Confirmation Dialog.
Translations Variations
Title: 🆕 Delete module
confirmation-dialogs.delete-module-confirmation-title
Secondary Button: 🆕 Keep
confirmation-dialogs.keep-button
Primary Button: 🆕 Delete
confirmation-dialogs.delete-button
This list details the translations corresponding with the Hide Row on Mobile Confirmation Dialog.
Translations Variations
Title: 🆕 Hide row
confirmation-dialogs.hide-row-confirmation-title
Heading: 🆕 Are you sure you want to hide this?
confirmation-dialogs.hide-row-confirmation-heading
This list details the translations corresponding with the Remove Custom Display Condition Confirmation Dialog.
Translations Variations
Title: 🆕 Delete display condition
confirmation-dialogs.delete-display-condition-confirmation-title
This list details the translations corresponding with the Confirm Delete Single File Confirmation Dialog.
Translations Variations
Title: 🆕 Delete {filename}
confirmation-dialogs.delete-file-confirmation-title
Secondary Button: 🆕 Keep
confirmation-dialogs.keep-button
Primary Button: 🆕 Delete
confirmation-dialogs.delete-button
This list details the translations corresponding with the Confirm Delete Multiple Files Confirmation Dialog.
Translations Variations
Title: 🆕 Delete {count} files
confirmation-dialogs.delete-files-confirmation-title
Secondary Button: 🆕 Keep
confirmation-dialogs.keep-button
Primary Button: 🆕 Delete
confirmation-dialogs.delete-button
This list details the translations corresponding with the Confirm Update Existing File Confirmation Dialog.
Text Updates:
Title: 🆕 Replace {filename}
confirmation-dialogs.replace-file-confirmation-title
Secondary Button: 🆕 Keep
confirmation-dialogs.keep-button
This list details the translations corresponding with the Update Existing File Confirmation Dialog.
Translations Variations
Title: 🆕 File {filename} already exists
confirmation-dialogs.file-already-exists-title
Heading: 🆕 Do you want to replace or keep both files?
confirmation-dialogs.replace-file-confirmation-heading
Reference the corresponding classnames: Not applicable.
This list details the translations corresponding with the Move File Replace Confirmation Dialog.
Title: 🆕 File {filename} already exists
confirmation-dialogs.file-already-exists-title
Heading: 🆕 Do you want to replace or keep both files?
confirmation-dialogs.replace-file-confirmation-heading
Reference the corresponding classnames: Not applicable.
Use this to enable a custom top bar that allows the end user to .
You can provide AWS Root Account Credentials or IAM User Credentials (we recommend the second option for security reasons). The provided account must have read and write access to the given bucket. .
You can now use the feature to allow users to search for additional Merge Tags and Merge Content, beyond those passed in the configuration file.
… or you can allow users to search and insert a merge tag by using the flexible feature. This is especially useful when the number of merge tags is large, and picking from a list would not provide an optimal user experience.
You can use a combination of both approaches, loading frequently used merge tags at the time the builder is initialized, and then allowing users to look for additional merge tags using .
In the example below, the user wants to insert some banner ads into the email, using a service such as . An array of Merge Content elements were submitted to the builder in the configuration file, so the user has several banner ads to choose from (i.e. some syntax that will be replaced with HTML when the email is sent).
… or you can allow users to search for additional instances of Merge Content by using the .
Here too, you can certainly use a combination of both approaches, loading frequently used Merge Content at the time the builder is initialized, and then allowing users to look for additional Merge Content using .
NOTE: if what you need for your users is a way to load a dynamic image into the message or page (e.g. a countdown clock), you don't need to use Merge Content. Beefree SDK can handle dynamic images with a feature that was created specifically for that task. See: .
If you want to provide a better experience when working with Merge tags, including using a friendly name instead of the syntax and generating sample content, we recommend to check out .
Due to these additional limitations, we now recommend an alternative approach to Merge Content in order to handle dynamic content in Beefree SDK: utilizing with Merge Content & Display Conditions.
You can use the feature to introduce an interactive layer between the builder and your application, and through it extend Merge Tags, Merge Content, Special Links, and Display Conditions.
This feature is available on the .
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 .
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
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 .
This feature is available on Beefree SDK only.
You can set for the Color Picker on any builder type (Email, Page, or Popup). Advanced Permissions are available for and plans.
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.
This feature is available on Beefree SDK only.
When designing a message or a landing page with Beefree’s editors, there might be cases in which users of your application insert a , add a link to an image, or apply a .
What if you have 400 merge tags? You can to the editor, but that’s not going to cut it.
What if it’s a 6,000 product database? How will they locate the right one? is not the right fit.
And what if a needs to be built on-the-fly?
a text placeholder ()
a dynamic link or a link to specific content ()
a markup placeholder ()
a conditional statement ().
Is a function with a -like signature.
This function lets you use your own logic to retrieve the desired value.
Once the value is available, you must call the resolve(value)
function to pass it to the editor.
In case you want to cancel the operation, call the reject()
function.
The above code snippet is an example of how to apply a .
Take the following steps to configure in your application:
A few of the most common use case for are the following:
Links can be applied to different . When you define a link dialog action, it will be displayed in the text-toolbar, which is the same behavior for merge tags, as shown in the following image.
A few of the most common use case for are the following:
Important: To display the Dynamic content tile in the contents panel, you must configure in with at least one predefined item.
Of course, it can be edited in the editor like any other Display condition, if the user has the .
Reference our to learn more about managing the visibility of the Add Condition and Edit Condition buttons.
are rows that are used across multiple designs, ensuring consistency when updates to a row are made. This section will cover how to configure synced rows in your application.
The following code snippet displays an example of how to configure .
notPermittedDescription
: Description of the action when the button is hidden from the dedicated
The resolve
function must return metadata for the selected row. The of the rows schema allows you to keep track of row-specific information.
This response will provide metadata that is added to the row in the asset (email, page, popup) before it’s provided through the .
Check the for further details on recommended metadata.
The following code snippet displays an example of how to configure .
The Content Dialog works the same way as the previous Content Dialog for – but in this case, the resolve
function should return the structure for the desired form.
To understand how this data is structured, refer to the on this website.
The following code snippet displays an example of how to configure .
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
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 .
After enabling Smart merge tags from your developer account, you need to apply a minor change to the merge tags’ .
The way to do this depends on how your integration manages the .
As with all the actions available in the toolbar, to control this option from your own UI:
Meta Tags are available for and .
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
You can totally customize the UX of adding attributes by invoking a that will take over the editor’s UI. The dialog will need to return the attribute that needs to be applied.
This feature is available on Beefree SDK only.
Unlike other premium features, fonts are part of the , so they can be defined each time the editor is started.
For instance, in our hosted (Beefree), we leveraged this Beefree SDK feature to create a “Brand styles > Brand fonts” area where an agency or marketing team can select which fonts have been approved by that brand. Only the selected fonts will be loaded in the builder when an application is initialized. Here is a screenshot.
This object, passed as part of the , tells the editor which fonts to load in any drop-down where a list of fonts is shown. It defines the availability of the default fonts and provides a list of additional, custom fonts.
The Commenting feature is available for .
Learn more about
If you subscribed to a Superpowers plan, and have enabled, your users will never lose a new comment again with the new notification system. Users will receive real-time notifications whenever a new comment is added to the document straight in the builder.
By clicking on the notification, they will be able to quickly open the comment, and highlight the element where the conversation is taking place. The toast notification can be styled with to match your application look-and-feel.
If you want to learn how to implement co-editing in your application, check the related documentation article .
We’ve put together a that illustrates how to send email notifications, triggered by a mention in a comment. This code shows how to:
This feature is available on Beefree SDK and above. If you're on the Core or Essentials plan, for free to try this and other Superpowers-level features.
This feature allows the host application to pass custom headers when it triggers a call to their services. The custom headers are added to and to calls.
For example, this could be useful for the security teams of , which would like to pass a JWT (JSON Web Token) when the user, through the file manager, triggers a call to their .
To activate this feature, the host application must add a specific element to the :
Please note that custom headers must be whitelisted by our team before using them. Please open a support ticket via the if you’re planning to use this feature.
This feature is available on Beefree SDK and above. If you're on the Core or Essentials plan, for free to try this and other Superpowers-level features.
This feature allows you to have your own file picker for choosing files (images) in Beefree SDK's Editor, to make its integration in your platform look even more seamless. It leverages Beefree SDK’s feature. To set it up you will need to add the corresponding entry to the :
The handler
function lets you use your own logic to retrieve the desired value, and it has a -like signature.
Images dragged onto an image block or edited via the “apply effects and more” button will be passed to the image storage per your app’s file storage settings. To prevent images from passing through Beefree SDK’s file storage, the file upload can be disabled via .
Values must use the same pattern used in the : the returned object is validated against the expected format. If the validation fails, an error will be returned to the browser console, eg: Error getting content filePicker value, the item is malformed
This feature is available on Beefree SDK only.
Using
Log into the and click on Manage roles under Application configuration for the selected application:
Please refer to for more details.
If you use in your builder application, then you can use additional user roles to control the access users have to creating and editing .
This feature is available on Beefree SDK and above. If you're on the Core or Essentials plan, for free to try this and other Superpowers-level features.
The absolute flexibility of these permissions makes it easy to address specific needs, not achievable with the feature that is available in the Beefree SDK Console.
Note: UID
is a when you configure Beefree SDK. This field connects end users to the permissions you set in the configuration.
limit actions in the file manager (either the built-in one or your ) by disabling actions like upload, import, and create a folder.
Another interesting case for using advanced permissions is the possibility to set a maximum size for uploads, per user. The maximum size set per user must not exceed the custom limitation size set on the . The default limit is 20 Mb unless otherwise stated. When this permission is configured, the system will check if a file exceeds the set size before uploading it; if so, Beefree SDK will return an error message, which you may customize using .
Note: UID
is a when you configure Beefree SDK. This field connects end users to the permissions you set in the configuration.
Open the row in (changes apply globally).
Convert the Synced Row to a Saved Row to .
Reference the to learn more about Advanced Permissions for the Edit Synced Row button.
In this section, we will explore how to assign advanced permissions and behaviors for various AddOn types, specifically focusing on how to customize permissions for and . These permissions can override default settings to provide granular control. For instance, an image addon can have specific permissions different from the default image block permissions.
You can choose to display or hide the "Add Condition" and "Edit Condition" buttons when using the with .
The following code snippet provides an example configuration for integrating the AddOn with advanced permission settings for managing access and permissions to Brand Tones:
You can find them in our
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
Please note that the Display conditions are disabled by default. You can turn this feature on by enabling it under the . You must be on a paid plan (Core subscription and above) to enable this feature.
Reference our to learn more about managing the visibility of the Add Condition and Edit Condition buttons.
You can extend this feature and allow users of the editor to build their own Display Conditions, on the fly, using a UI that you control. It’s part of the functionality. This is an advanced feature that requires some development on the side of the hosting application, but that provides fantastic flexibility.
You can choose one of for the visual builder's UI when initializing the builder. If you want to use custom language strings, however, you will need to use a Custom Language. This feature is available on Beefree SDK and above. If you're on the Essentials plan, upgrade a for free to try this and other Core-level features.
Before getting started, ensure you access and familiarize yourself with the GitHub repository. This repository includes important JSON files for you to utilize to accomplish the steps outlined on this page.
Important: Familiarize yourself with the prior to continuing into the steps.
In the , you'll find the following section at the beginning:
The easiest method to override specific text labels is to , which contains the segments of the language file you want to override.
You can override the default text for the . The following configuration sample includes the AI component and the various default text fields you can override.
Reference the for additional customization options and details.
Reference the corresponding .
Reference the corresponding .
Reference the corresponding .
Reference the corresponding classnames for .
Reference the corresponding classnames for .
Reference the corresponding classnames for .
Reference the corresponding .
Note: This section is relevant if both the and ConfirmOverwriteModalEnabled
are activate.
Reference the corresponding .
Check out our Github repository for in all supported languages.
name
This string will be shown in the font dropdown list. You can use the term you prefer and we suggest the usage of common font names, but you can go creative and use semantic names that fit on your application. Long strings may impact the interface, so we recommend to keep it short. The characters { } [ ] : ” / \ | ? * are invalid.
fontFamily
Describes the CSS font stack that will be applied to the final HTML. Is important that you provide at least one fallback font to ensure that the text is not displayed using an unwanted font family. Is important that you use single quote marks with the font names instead of double quotation marks to maintain a correct JSON syntax.
url
This parameter is used only when we work with web fonts. Is important that the URL points to a CSS file with the @font-face properties, and not directly to the font files. To work, the CSS must be hosted in HTTPS.
fontWeight
Adds a new option in the dropdown of the content block’s settings for title, button, paragraph, and list blocks (e.g. 100: Thin). If not defined, only Regular (400) and Bold (700) will be available.
uid
string
Unique identifier for the CMS user (mandatory).
'CmsUserName'
container
string
HTML container element ID for embedding Beefree SDK (mandatory).
'bee-plugin-container'
advanced permissions
object
Contains settings for content elements, rows, settings, and tabs configurations.
See configuration object for details.
components
object
Specifies available components like file picker and link types.
{ filePicker: {...}, linkTypes: {...} }
rowAddOn
object
Settings for custom row add-ons, such as custom behaviors.
{ customRowAddonHandle: {...} }
workspace
object
Defines workspace settings, such as stage toggle and history buttons visibility.
{ stageToggle: {...}, historyButtons: true }
locked
boolean
true or false
show
boolean
true or false
canSelect
boolean
true or false
Can select a row or module to edit its properties
canAdd
boolean
true or false
Can drag and drop the content tile or row onto the stage
canViewSidebar
boolean
true or false
Can view the content in the sidebar
canClone
boolean
true or false
Can clone a content or row on the stage
canMove
boolean
true or false
Can drag content to another location on the stage
canDelete
boolean
true or false
Can remove the content or row from the stage
canResetMobile
boolean
true or false
Can reset mobile style for content properties that make use of it
canResetMobile
boolean
Indicates whether icons can reset to default settings on mobile devices.
false
icons
object
show
boolean
Determines if the icons are visible.
true
locked
boolean
Indicates if the icons' visibility setting is locked.
true
fontWeight
object
show
boolean
Determines if the font weight option is visible for icons.
true
locked
boolean
Indicates if the font weight option is locked.
false
align
object
Aligns icons within their container.
NA
fontFamily
object
Sets the font family for icon labels.
NA
fontSize
object
Sets the font size for icon labels.
NA
textColor
object
Sets the text color for icon labels.
NA
iconSize
object
Sets the size of the icons.
NA
itemsSpacing
object
Sets the spacing between multiple icons.
NA
iconSpacing
object
Sets the spacing around individual icons.
NA
padding
object
Sets the padding around icons.
NA
hideOnMobile
object
Hides icons on mobile devices.
NA
hideOnAmp
object
Hides icons on AMP-format pages.
NA
id
object
Sets a unique identifier for icons.
NA
letterSpacing
object
Sets the space between letters in icon labels.
NA
admin
designer
designer2
copy
modules
rows
user
Lock/unlock a module
widget not provided
widget not provided
widget not provided
widget not provided
Lock/unlock a row
widget not provided
widget not provided
widget not provided
widget not provided
widget not provided
widget not provided
Add a module to locked row (the module is automatically locked)
can’t drop modules in locked rows
can’t drop modules in locked rows
can’t drop modules in locked rows
Move a locked module from an unlocked row to a locked one
can’t drop modules in locked rows
can’t drop modules in locked rows
module handler not provided
Move a locked module from a locked row to a locked one
module handler not provided
module handler not provided
module handler not provided
Move a locked module from a locked row to an unlocked one
module handler not provided
module handler not provided
module handler not provided
Move a locked module from an unlocked row to an unlocked one
module handler not provided
Move an unlocked module from an unlocked row to a locked one
can’t drop modules in locked rows
can’t drop modules in locked rows
can’t drop modules in locked rows
Move an unlocked module from a locked row to a locked one
module handler not provided
module handler not provided
module handler not provided
Move an unlocked module from a locked row to an unlocked one
module handler not provided
module handler not provided
module handler not provided
Move an unlocked module from an unlocked row to an unlocked one
Move a locked row
row handler not provided
row handler not provided
row handler not provided
Move an unlocked row
Delete/duplicate a locked module in locked row
show warning
show warning
show warning
Delete/duplicate an unlocked module in locked row
show warning
show warning
show warning
Delete/duplicate a locked module in unlocked row
show warning
Delete/duplicate an unlocked module in unlocked row
Delete/duplicate unlocked row containing locked modules
show error
show error
Delete/duplicate locked row
show warning
show warning
show warning
Change properties of a locked module
show warning
show warning
Change properties of an unlocked module
Change text of a text/button locked module
show warning
show warning
Change text of a text/button unlocked module
Add an image to a locked image module
show warning
show warning
Add an image to an unlocked image module
Change properties of a locked row
show warning
show warning
show warning
Change properties of an unlocked row
The Content Tile Sorting option allows the host application to change the order of the content tiles in the editor’s sidebar. This allows the host application to display the content blocks that are most important for their users first, and even provide additional visibility for a Custom Addon.
To use this feature, the host application must simply pass in the preferred order inside the configuration passed at initialization, like so:
The host application can pass as many or as few content blocks as they want. If only one content tile is specified, then only that content tile will be placed at the top, and the rest of the content tiles will follow the default order.
For Custom/Partner AddOns, the host application passes the “Content Title” value found in the Addon section of the Beefree SDK Console Application Configuration.
Beefree SDK enables you to customize the appearance of a variety of elements. Reference the following sections to learn more about how you can customize appearance:
The Content Tile Grouping option allows the host application to group content tiles in the editor’s sidebar. This allows the host application to display the content blocks into distinct groups.
Content Tile Grouping supports:
Text labels
Special Characters
Emojis
To display custom groups, the application must pass the groups settings in the configuration at initialization, like so:
Custom groups can be collapsed and opened by default by changing the collapsable
and collapsedOnLoad
values.
Ungrouped tiles will be gathered at the bottom of the list under a group with no label.
Duplicated tiles are not allowed, e.g., you can’t have a tile twice in the sidebar.
An onWarning
notification is triggered whenever an unknown tile is added to the configuration.
If you want to organize or include AddOns, and Custom AddOns under a custom group, mention the name used in the Beefree SDK Console.
Please note, the AddOn needs to be enabled to appear in the sidebar.
The default tab configuration option lets the host application decide which content should be visible first in the sidebar when the editor is loaded.
In Beefree SDK v2, the default tab is the Content tab and this behavior could not be changed. It’s still the behavior that we recommend for most scenarios.
However, apps that rely heavily on pre-built custom rows, or saved row libraries, may now choose to highlight the Rows tab, using the following configuration options.
Available Options:
content
rows
settings
Building upon the default tab configuration option, in Beefree SDK v3 you may also re-organize the way tabs are ordered.
The UID parameter:
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
.
It uniquely identifies a user of the application. When we say “uniquely”, we mean that:
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).
It’s entirely up to you – the application that has embedded BEE – 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.
This Beefree SDK configuration allows you to change the builder’s appearance when rendered within your application so that it will blend even more seamlessly with the rest of your user interface.
To change the builder’s appearance with just one click – and to familiarize with this feature – try one of the available, pre-built themes. All of them were created based on UI best practices, such as using the right amount of contrast between elements.
You can apply one of these themes as is, or use them as a starting point. And you can roll back to the default theme at any time, if things go wrong.
Note that themes will not be applied automatically, but rather will change the Look & feel values displayed in the lower part of the page.
Once you’re happy with your selection, press Save to apply the new theme to your Beefree SDK application.
The properties that make up a theme are divided into sections for clarity and easy of use.
The basic settings for your theme. They provide control over the font used and the general color scheme.
Font URL
You can use a Web font by adding the URL of a public CSS file (e.g., https://fonts.googleapis.com/css?family=Roboto)
Font-family stack
Will be used as font-family property. Remember that – when using web fonts – a fallback value will help to deal with downtime or network issues.
Brand color palette
Use this section to configure basic properties of your color scheme. These colors will be displayed in buttons, active widgets, hover & selection helpers, etc.
The Primary color will be the most important color in your scheme, as it will identify highlighted elements. Here are two examples of how a highlighted row is rendered using two different themes (the default theme is shown at the top).
The stage is the area where the message is displayed while you design it. The main elements will inherit colors from General | Brand Color Palette so only the text color is available as an editable property.
This section controls the appearance of the right panel’s top tabs. You can add custom colors and even hide the default icons (which may be useful for some translations in order to create more real estate for the text labels). Here is an example (left: default theme, right: aubergine).
These sections will help you customize the tiles that are used for content items and row structures. Here is an example (left: default theme, right: aubergine).
This is the title bar that is displayed in the right side panel when you select an item on the editing stage. It displays important information and actions that can be performed on that item.
All the properties displayed in the right side panel when you select an item in the editing stage are a mix of shared widgets.
The following is a visual guide of the available customizations (left: default theme, right: aubergine).
To define a custom look and feel through a CSS stylesheet, assign the URL of your CSS file to the customCss
property in your JavaScript code, as shown in the following example.
You can customize the builder's CSS for different users by dynamically setting the customCss
property with a unique CSS file URL for each user. Simply concatenate the user-specific identifier to the base URL as shown in the example code.
When used properly, it is a powerful tool that can be leveraged to accomplish anything from applying custom styles with fine granularity to changing icons.
When misused, however, it may harm the user experience and the rendering capability of the builder’s stage. For example, styles applied to the stage via CSS will not be reflected in the preview or exported HTML.
For the best results, follow these best practices:
Avoid global styles. Do not use generic global styles (e.g., *
, p
, input
) that could affect the editing stage.
Use specific CSS selectors. Target elements using precise selectors (e.g., body.bee--cs h3
).
Do not inject scripts via CSS. JavaScript and other scripts should not be included in CSS.
Ensure HTTPS hosting. The custom CSS URL must be hosted over HTTPS.
Avoid third-party hosting. Do not link to CSS files hosted on GitHub or other third-party sources.
Do not style elements directly on the stage. These styles will not appear in the final HTML, which may create a confusing experience.
Only class names with the --cs
suffix are reliable for custom CSS. Avoid the following selectors:
Nested tag structures (e.g., div > div > div
)
Sibling selectors (e.g., input + label
)
Class names without --cs
(e.g., .icons__item
)
Prefixed class name selectors (e.g., div[class^="StageModuleIcons_itemRow"]
)
Class names without the --cs
suffix may change without prior notice. However, any updates to the HTML structure and --cs
classes will be communicated in advance.
Reference the following Sample Custom CSS Theme to see an example of how you can use custom CSS in your web application.
With Content Defaults, you can define how content looks when dragged into an email or page.
When adding new content elements through the Content tab, you may want a default style that matches one of these options:
your application’s color scheme;
your user’s branding guidelines;
the look & feel of the template used to create the message or page.
For example, here is how a button dragged into the stage looks by default:
The background color is always light blue (HEX code #3AAEE0).
The font size is always 16px.
The font is Arial, unless a different Default font was set for the template loaded in the editor.
The border radius is set at 4.
The CTA is a formally correct, but laconic “Button”.
Instead, when applying Content defaults, the button dragged by your users could look out of the box like this:
We’ve used a dark grey color (HEX code #555555), an Ubuntu font at 22px in Bold, with a border radius of 10 and a nice “READ MORE” call-to-action.
Content Defaults are part of the Configuration parameters passed to your Beefree application during startup, so you can have different sets of them for different users.
By setting up your Content defaults, you’ll be able to address styling and branding needs for you and your customers.
If your application uses dark grey for the primary CTA, then you probably would want a default button in the Beefree builders to follow that style.
If your application has brand settings that are used for your app’s UI or for assets managed in your application, you may want those to apply also to default content in the Beefree editors.
Since the Social block is one of the available Content defaults, you can define what social platforms – either present in the Beefree editors or added by you – are included when a social block is added to a message or page. For example, you can have a default social block with three platforms defined in the Beefree system and a fourth, custom one (Messenger):
To set up the content styles you will need to add the contentDefaults
object to beeConfig
:
You can add all the content styles, some of them or just one. It is up to your application to create them for all the users or for a segment, as there are no related server-side settings; basically you can customize them each time the editor starts.
All the contents use the same pattern, but the object must match the content schema for the type of content (described in the following section).
The title
content default inside the beeConfig
sets default properties and styling for title elements in the editor. It includes heading levels, alignment, padding, and mobile-specific styles to ensure consistency and responsiveness across different devices.
The text
content default within the beeConfig
provides a default HTML string and sets the styles for text blocks, including color, font, and line height. It also includes options for padding and visibility on mobile devices to ensure a consistent appearance across different screen sizes.
The image content defaults in the BeeConfig define the properties for images, including attributes like alt
, src
, and href
, as well as styling details such as dimensions, border radius, and padding. It also specifies mobile-specific styles to ensure proper alignment and spacing on different devices.
Image Parameters
borderRadius
String
30px
Defines the roundness of the image corners.
The row
content default in the BeeConfig specifies various styling properties for rows, including background colors, vertical alignment, border radius, and spacing. It also includes options for mobile-specific styles, such as stacking and padding configurations.
Row Parameters
The following table lists the row content default parameters and their corresponding descriptions and data types.
backgroundColor
String
Red
Sets the background color of the row.
contentAreaBackgroundColor
String
Green
Sets the background color of the content area within the row.
verticalAlign
String
bottom
Specifies the vertical alignment of the row content.
columnsBorderRadius
String
10px
Defines the roundness of the column corners.
columnsSpacing
String
20px
Sets the spacing between columns.
columnsStackOnMobile
Boolean
false
Determines if columns should stack on mobile devices.
columnsReverseStackOnMobile
Boolean
true
Specifies if the order of stacked columns should be reversed on mobile devices.
columnsPadding
String
42px
Defines the padding inside each column (the value applies to all padding sides).
columnsBackgroundColor
String
Yellow
Sets the background color for each column.
columnsPaddingLeft
String
25px
Defines the left padding for each column.
columnsPaddingRight
String
20px
Defines the right padding for each column.
columnsPaddingTop
String
15px
Defines the top padding for each column.
columnsPaddingBottom
String
10px
Defines the bottom padding for each column.
padding
String
20px
Defines the padding for the entire row (the value applies to all padding sides).
paddingLeft
String
25px
Defines the left padding for the entire row.
paddingRight
String
20px
Defines the right padding for the entire row.
paddingTop
String
15px
Defines the top padding for the entire row.
paddingBottom
String
10px
Defines the bottom padding for the entire row.
The button content default in the BeeConfig specifies the appearance and behavior of buttons, including attributes such as label, hyperlink, width, and styles like font, color, and padding. It also defines block options for padding and alignment, as well as mobile-specific styles for responsiveness.
The divider content default in the BeeConfig specifies the appearance of dividers, including properties such as width, line style, and alignment. It also defines block options for padding and visibility on mobile, as well as mobile-specific styles for alignment and padding.
The social content default in the BeeConfig specifies the display of social media icons, including their type, name, image properties, and link. It also defines the block options for alignment and padding, with specific styles for mobile devices.
The dynamic content default in the BeeConfig specifies the block options, including padding and the ability to hide content on mobile. This ensures a consistent design by managing spacing and visibility across different devices.
The video content default in the BeeConfig specifies block options, including padding and the ability to hide content on mobile devices, ensuring a consistent appearance across different platforms. Additionally, it defines mobile-specific styles to enhance the user experience on smaller screens.
The form content default in the BeeConfig defines the structure and styling for form elements, including fonts, colors, alignments, and padding, ensuring a consistent layout across different devices. It also includes options for mobile-specific styles to improve usability on smaller screens.
The icons content default in the BeeConfig specifies the properties for displaying icon items, such as the image source, text, size, and link attributes. It also includes styles for the icon's appearance and mobile-specific configurations to ensure proper alignment and padding across devices.
The menu content default in the BeeConfig defines the properties for menu items, including text, links, and target attributes. It also sets the styles for the menu's appearance and behavior, such as font styles, colors, spacing, and mobile-specific configurations like hamburger icon settings.
The spacer content in the BeeConfig is used to add vertical spacing between elements in the layout. It allows for hiding the spacer on mobile devices through the hideContentOnMobile
option.
The paragraph content configuration in BeeConfig specifies the default styles such as color, font size, alignment, line height, and spacing for paragraphs. It also defines block options and mobile styles to ensure consistent rendering on different devices.
The list content default in BeeConfig sets the basic styling for list elements, including options like color, font size, alignment, and list type. It also ensures consistent spacing and padding across devices by defining both block options and mobile-specific styles.
Additionally, listStyleType
supports the following: revert, auto, disc, circle, square, decimal, lower-alpha, upper-alpha, lower-roman, upper-roman.
The carousel content default in BeeConfig sets the basic padding for carousel elements and provides an option to hide content on mobile devices. It also defines mobile-specific padding to ensure a consistent appearance across different screen sizes.
The table content default in BeeConfig specifies the initial styling and layout properties for table elements, including rows, cells, and headers. It sets text styles, colors, padding, alignment, and optional alternate row and header styles to ensure consistency across different table instances.
Note: If contentDefault
values for the Table module are incorrectly formatted, the following onWarning
will be triggered (this applies to incorrect values for rows and headers, not all contentDefaults
), and the default table will be used instead:
If the user tries to load a template that contains an improperly structured Table (for example, if a row does not contain all of its cells), the template will not load, and the onError
will be triggered.
The following code displays an example error for this scenario:
The general
content default in the BeeConfig specifies the overall styling for the email template, such as background color, content area width, and default font. These settings help maintain a consistent look and feel throughout the template.
Thanks to Mobile Design Mode, your customers can easily design responsive emails, pages, and popups for mobile without switching between the builder stage and preview mode. When enabled, your customers will be able to:
Easily switch between desktop and mobile view to access and edit content;
Edit padding, text alignment, and font size optimized for Mobile;
Extend Beefree SDK’s design flexibility and build mobile-first campaigns.
Mobile-first design: Start the builder in Mobile view, and let the user switch as needed.
Mobile-only editing: Start the builder in Mobile view, and hide the widget to switch views.
Control hidden elements visibility: Remove the “Visibility” toggle and decide if elements with a “hide on” property can be visible with the blur effect or are not visible during editing.
Custom UI controls: start the builder in a predefined mode and offer your UI controls to switch between views and hidden elements visualization. To do so, you can use the loadStageMode method to trigger a change from your application.
You can also use the loadStageMode method to disable Mobile editing mode.
Here is a video explaining why we built Mobile design mode and how it enhances the design UX of Beefree SDK.
If your application doesn’t have Mobile Design Mode enabled yet, you need to enable it. It takes just a few clicks:
Select the application you want to configure > Click Details
We recommend testing the feature first with a DEV or QA application
Go to Application Configuration > View More
Go to Services > Toggle Enable mobile design mode ON
Click Save on the top-right corner of the page.
Congrats! You’ve successfully enabled Mobile Design Mode!
The desktop view (screen icon on the left) will leverage your browser’s full width.
The mobile view (mobile icon on the right) will resize the work area width to 320px to simulate a mobile screen.
Beefree SDK provides settings both for rows and content blocks.
To change how content behaves on mobile and create a mobile version of an email, page, or popup:
Hide on mobile/Hide on desktop (available on developers.beefree.io)
A content property to hide a block when displaying the email/page on a specific device.
Do not stack on mobile (available on developers.beefree.io)
When this option is enabled for a row, adjacent columns will not be stacked on mobile devices. The columns will stay side-by-side, as in the desktop view.
Reverse stacking on mobile (available on developers.beefree.io)
When turned on for a row, columns for that row will stack in reverse order, i.e., from the rightmost to the leftmost.
These settings become more accessible with Mobile Design Mode, as users can immediately view the desktop vs. mobile design.
There is an additional setting to preview hidden elements included in a template. With the Hide-on enabled a “Visibility” icon will appear next to the Desktop vs. Mobile stage icons.
When the Visibility button is ON (default behavior):
The builder will display content blocks set as hidden for the current device;
Hidden elements will be blurred out;
A small icon in the outline of the block will appear whenever hovering with the mouse on the hidden element.
When Visibility is OFF:
Hidden elements won’t be visible in the content area;
The template will be available as it is;
Here is how the Visibility toggle changes the experience when editing a recent Beefree SDK newsletter.
The device preview matches the stage selected when accessing the design preview. This doesn’t apply if you have implemented a custom-built preview.
When a user is working in the Mobile stage, the features available are the same as in the desktop stage, with a few exceptions:
The content area width cannot be scaled – it can only be changed in the desktop view;
Users can add or delete columns within a row, but they won’t be able to resize them.
When designing content for Mobile, users may require more flexibility in the way they arrange or format elements to fit a smaller screen.
Thanks to the latest Mobile Design Mode updates, users can now control individual elements straight from the mobile stage without the need to duplicate them.
Users can optimize the design of the following content properties by switching to the Mobile Design Stage:
Padding
Alignment
Font size
It is now possible to style these elements for Mobile or Desktop.
These three mobile-optimized properties are available for the following content type modules:
Title
Paragraph
List
Form
Icons
Menu
Button
To edit a specific parameter for mobile, users must switch to the Mobile stage and select the content element they want to edit.
They will find the Mobile-optimized properties in the sidebar menu, under the “Content Properties” tab.
Mobile-optimized elements are flagged with a clickable “Mobile” pill, as shown in the image below:
Users can click on the x to revert the property back to the desktop.
We have also improved the user experience by moving the Font Size Controls, previously displayed in the formatting tiny menu available in the content area, to the Content Properties Tab in the sidebar menu.
All the edits performed in the Mobile Stage are tracked and flagged in the history as (Mobile) edits.
If you want to customize the user experience, Beefree SDK allows you to configure a few client-side options to control permissions and styles. Take a look at the code snippet below to see how to load these settings into the initial configuration as part of the workspace section.
Here is a brief description of the parameters and their options. They are all optional.
type
default, mixed, amp_only, html_only
default
stage
Define if the builder starts in desktop view, mobile view, or global (i.e. without desktop/mobile views.)
desktop, mobile, global
inherits Developer account configuration
displayHidden
if defined, hidden elements will behave based on the parameter value.
blur, hide
blur
hideStageToggle
if true, the mobile/desktop icons to switch view are not visible
true, false
false
With Co-editing, multiple users can work on the same asset (email, page or popup) simultaneously. Co-editors can see what each other is doing, as their changes are synced to the stage in real-time.
Each user is represented by a round icon with the initial of the user, and hovering the mouse on the icon will show the full name for that user.
When a user selects a row or a content block, other co-editors will see it highlighted with that user’s color. To avoid conflicting edits, only one user at a time can edit a row or block. A feedback message will guide users when this situation happens.
In many companies, it’s rare that someone works alone on everything related to an email and or a landing page. Your customers may have multiple people sharing duties – copywriting, designing, testing, reviewing, etc. That is why SaaS applications typically offer additional users or seats, so that more people can log into an account at the same time and collaborate.
When multiple people collaborate on creating content, co-editing is the logical solution for an authentic teamwork experience, Google-doc style.
Superpowers plans are limited to a maximum of 5 co-editors per session.
Enterprise plans are limited to a maximum of 20 co-editors per session.
This means that on the Superpowers plan, no more than five users can edit the same email or web page simultaneously. Your application will only receive an error code from the Beefree SDK platform when the limit is reached and the editor will not load – you’ll need to add a user notification to let them know they cannot join the editing session (e.g. “Sorry, you cannot edit this message because you’ve reached the limit of five co-editors, try again later”).
Even better, you can monitor sessions and disable editing for an email or landing page once the limit is reached.
Creating a co-edit session is nearly identical to starting a traditional, single-user session of your Beefree SDK application. You simply need to pass a shared flag, indicating the template is sharable, along with some simple user settings.
The following parameters are all required.
username
string
The user’s display name
userColor
string
Hex color code (e.g. #FFFFFF)
The following shared parameter is required to start a co-editing session.
shared
boolean
true or false
You pass this argument in the start instance method’s options parameter.
Once the session is started, a globally unique id will be created and returned to the host application via the onSessionStarted callback. The host application will save this session id, and use it when users want to join the same session.
sessionId
string
globally unique id saved from onSessionStarted callback
The host application can add a user to any active co-edit session by using the new join instance method. The join method replaces the bee.start method and accepts the session id as a parameter, and loads the current template directly from the active session.
Once the session is started, all changes to the session are reported to the onSessionChange
callback. The host application can monitor this callback to understand the session’s status.
Only display a “join” button when a session is active
Display an “edit” session only if there is at least one free co-editing spot
Know when someone logs on or logs off, and notify other users in the host application
Know when the session contains only a single user, so the user knows it’s safe to send a campaign
There are some limitations set for the Co-editing feature to preserve the integrity of the experience. These are:
Undo/redo: If only a single user is present in the co-editing session at any given time, undo/redo will function the same as in a normal session. When a second user is present, undo/redo will be limited to only allow changes while the content or row is locked, and users cannot undo the changes of other users or those that have been synchronized across all sessions.
Load/reload: The host application cannot trigger any action that overwrites the user’s changes.
Autosave: The autosave timer is set on the instance that started the session; it’s not recommended for co-editing sessions.
onChange: The onChange callback occurs only for the user that makes the change. For example, if user A makes a change, the onChange event fires only for their instance, and user B won’t receive the notification.
During the co-edit session, the host application may receive callbacks for saving JSON and HTML. However, with multiple users editing the content, potentially all over the world, the host application needs to confirm which changes are new vs. old. For this reason, a new version parameter has been added to all of the callbacks that return JSON or HTML.
The version is a simple integration counter: 1, 2, 3, …
Both the server and client regularly check the connection using the “ping-pong” heartbeat.
If the client misses 5 consecutive pings (ping is emitted every 10s), the server considers the connection to be lost and disconnects the client.
If the server misses 5 consecutive pings (also every 10s), the client considers the connection to be lost and will attempt to reconnect (see below).
If the server disconnects without reason (the disconnection is not clean), or it misses 5 consecutive pings, the client will attempt to reconnect to the session. It will keep trying for the 60s before emitting an error with code 5400.
Reconnect mechanism is also employed after certain recoverable errors, specifically 5001, 5100 and 5300. The error itself is only emitted if the reconnect fails.
The server will wait for 60s after the last user of the session disconnects (or the connection is lost) before erasing the session data.
During reconnecting, the builder is covered with an overlay to prevent the user from doing any changes (since they cannot be synchronized). This overlay also appears if the server has missed a ping.
In case of error, another overlay modal is displayed to prevent the user from interacting with the builders in an error state. The host application should handle the errors and restart the Beefree SDK.
You can monitor the onError callback to know when a problem occurs, and then alert users of the problem. For example, if a user loses internet connection, you can display an alert in the host application to let them know their changes have not been saved.
Here is the full list of error codes that can be returned for Co-editing.
5001
Unexpected error occurred during co-editing.
General error.
Yes
5100
Failed to open co-editing session.
Unexpected error when creating/joining a co-editing session.
Yes
5150
Session does not exist.
The client attempted to join a non-existing (or expired) session.
No
5200
Failed to synchronize changes.
Emitted if an unexpected error occurs on the server during the real-time synchronization of changes.
No
5300
Connection to the synchronization server was lost.
The server closed the connection. Reason is given in the detail field.
Yes
5400
Connection to the synchronization server was lost.
Caused by network connection error or the server unexpectedly dying.
No
5500
Co-editing is not supported for your current plan.
If the client attempts to initiate or join a co-editing session with a lower plan.
No
5600
Co-editing server is not available.
Please try again later.
No
When 2FA is set up, users will need to:
use their device and the app to generate a token and log in.
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.
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.
A classnames change log where you can reference current and past changes to CSS classes.
This section includes a reference for new classnames related to Mobile Badge.
Reference the classname changes related to Content for Mobile Badge in the following expandable section.
Reference the classname changes related to Rows for Mobile Badge in the following expandable section.
This section includes a reference for new classnames related to Confirmation Dialogs.
Reference the classname changes related to Rows for Confirmation Dialogs in the following expandable section.
Reference the classname changes related to Columns for Confirmation Dialogs in the following expandable section.
Reference the classname changes related to Modules for Confirmation Dialogs in the following expandable section.
Reference the classname changes related to Rows for Confirmation Dialogs in the following expandable section.
Reference the classname changes related to Rows for Confirmation Dialogs in the following expandable section.
Reference the classname changes related to File Manager for Confirmation Dialogs in the following expandable section.
Reference the classnames added in the following expandable section.
Reference the classnames added in the following expandable section.
The Hover Effect allows end users to design a standard view of buttons within their design, and a hover view of the button when a viewer of their email, page, or popup design hovers their cursor over the button. The Hover Effect for Buttons is available as a new content property available under the Content tab located within the builder's sidebar. Through applying this Hover Effect, your application's end users can design more attention-grabbing buttons within their design. Reference the Hover Effect for Buttons End User Guide to learn more about how this experience is for your application's end users. Continue reading this page to learn more about how to implement this feature.
The following GIF displays an example of a button within an email sent to an email client that does support the hover effect.
If an email client doesn't support the hover effect for buttons, the email recipient will see the standard button properties used to design the button when they hover their cursor over it.
The following image displays an example of a button within an email sent to an email client that does not support the hover effect.
Prior to implementing the Hover Effect button, ensure you have the following:
Take the following steps to toggle on and activate the Hover Effect for Buttons for your application:
Navigate to the application where you'd like to enable Hover Effect for Buttons.
Click Details to navigate to the application's details.
Click Application configuration.
Scroll to the Services section.
Toggle on the Enable button hover feature.
The Button Hover section is now available under Content Properties within your application's builder.
The following table outlines the properties available within the hoverStyles
object for buttons. These properties define the visual styles applied to a button when hovered over, including text color, background color, and border styles. Each property can be customized to create engaging and visually dynamic buttons that respond to the viewer's interaction.
The following table displays each hoverStyles
property and its corresponding data type, example, and description.
Consider the following when using this feature:
Multi-language Templates (MLT) empower your end users to design customized experiences for their international audiences. Through the use of this feature, your end users will be able to select one default language, and up to 20 translations reflected in the top bar of their builder. Keep in mind that Multi-language Templates provide you with a means to translate template content, but does not automatically translate the content for you.
MLT provides a translation infrastructure, but does not perform the translation for each language version of your template. You can integrate translations into your application for each language version using one of the following two methods:
End users can type the translations manually for each template language version.
Note: The style of your templates stays the same across the language version while MLT is in use. The only change that will occur is the language of the text for the relevant components.
The Multi-language Templates (MLT) feature is an enhancement for companies working with end users who build emails that engage with international audiences.
MLT adds the following extended functionality to your host application:
Add a new language for the content inside Beefree SDK
Customize a list of languages the user can choose from
Allow changes to the default language
Enable preview for templates in different language versions
Multi-language Templates (MLT) offers the following in-app features for an application end user:
Switching the editor and template languages
Translate contents
Multi-language Template preview
Export HTML for multiple languages as single files
Alternative text descriptions
Changing an image path
This lets users switch email images for different translations. For instance, they can replace an image containing English text with the corresponding image containing Spanish text for the Spanish translation.
For more detailed information on the MLT feature offering, visit our Multi-language Knowledge Base article.
Before proceeding with the configuration, ensure you have:
Superpower or Enterprise plans
The multi-language support toggle set to on in the Beefree SDK Console
Application Client ID
Application Client secret
To use Multi-language Templates, your host application only needs to store one JSON file with the different languages you’d like to offer. Take the following steps to configure Multi-language Templates (MLT) in your application.
Enable multi-language templates
Click “Details” on the application you’d like to enable multi-language template for.
Select “Application configuration”.
Navigate to the multi-language template toggle.
Toggle the feature to on.
Add the templateLanguage
property to the config object. This property defines the default language for the template.
Add the templateLanguages
property to the config object. This property defines the list of language options for the template translations.
Confirm you added both properties with the correct language options and save your changes.
The following example shows the properties within the config object. In this example, the languages are read and written from left to right.
Note: You can only choose languages that are written and read from left to right, or right to left. You cannot mix languages with different directions of reading and writing within the same JSON.
The following sample shows an example of a default language and three translation languages that are written and read from right to left.
Note: If you're on a Superpowers plan, you can have up to six additional language versions of the design using one template. If you're on an Enterprise plan, you can add up to 20 translation languages.
Once you have initialized multi-language templates, you can confirm that the configuration was successful by following these instructions:
Go to your builder.
Navigate to the top bar.
Confirm whether or not you see a language drop-down menu.
If you see a drop-down, the configuration was successful. If you do not see a drop-down, reference the following table for troubleshooting steps you can take.
Multi-language Templates (MLT) offer the option to save and export translation HTML. This section outlines the steps you need to take to save or export a translation’s HTML.
To save the HTML output for a specific language take the following steps:
Use the bee.save
method and provide the desired language as a parameter. In this example, we’ll save it for the Italian language (‘it-IT’).
Set up an onSave
event listener to handle the HTML saving process. This listener will be triggered when the HTML generation is complete. You can add it to the configuration object.
In the code above:
onSave
is an event handler function that takes several parameters related to the generated HTML.
pageHtml
contains the generated HTML.
language contains the requested language value, which was previously set in the bee.save
method.
If you want to use the default main language for generating HTML when the bee.save
method is called without parameters, you don’t need to specify a language in the bee.save method
. The default language will be used automatically.
Take the steps outlined in this section to export the translation HTML.
Define an array of languages that you want to export translations for. Each language should be represented as a string.
The following example shows an array of multiple export languages.
Create a function, let’s call it exportAllTranslations
as an example, which will iterate over the array of languages and call the bee.save method
for each language.
View the following example function.
Implement the onSave
callbacks for each language. These callbacks will be triggered when the bee.save method completes for each language. Make sure to handle the specific language-related data within each callback.
The following sample code displays this:
Follow the steps outlined in this section to create a specified functionality that allows the end user to change their template language when a custom top bar is enabled.
Create a function to handle the language change. You can use the instance method bee.switchTemplateLanguage
for this purpose.
Verify if the specified language exists in the available languages. If it does, the language switch will happen automatically.
Note: If the specified language does not exist among the available languages, an event will be fired to the onError
callback.
Once the language is successfully changed, a callback named onTemplateLanguageChange
will be triggered.
You need to define this callback function to respond to the language change.
The onTemplateLanguageChange
callback will receive an object (lang) containing information about the language the user switched to. This object will have three properties:
label
: The label or name of the language.
value
: The value representing the language (e.g., ‘es-ES’ for Spanish).
isMain
: A boolean property indicating whether the selected language is the default one, as defined with templateLanguage
in the configuration object.
Test the language switching functionality by calling bee.switchTemplateLanguage
with different language values, and make sure that the onTemplateLanguageChange
callback responds correctly.
If you have a custom Preview, you can handle switching languages on the Preview.
To open the Preview, you can call either of two methods:
bee.togglePreview
bee.switchPreview
The methods perform the following tasks:
togglePreview
: a toggle that opens and closes the Preview.
switchPreview
: accepts a parameter to specify the language and get the HTML preview. It also opens the Preview if it’s closed.
The following code shows an example of the methods applied for the default language.
The following code shows an example of the methods applied for a preview in French.
Note: The language parameter is optional in switchPreview
. Calling it without parameters will open the Preview with the default language selected. If the Preview is open, nothing will happen. The same behavior is applied when the language passed is not valid or doesn’t exist.
Learn more about how to activate cards style widgets and image rounded corners.
This guide explains how to enable the Image Rounded Corners and Cards Style features in your host application. It provides instructions for making these features available to your application's end users while they are designing emails, pages, and popups.
Cards Style is a Row Property that enables you to create space between columns and round the corners of columns within a row.
The Cards Style feature allows users to transform ordinary messages into visually appealing layouts that grab their audience’s attention effortlessly. By incorporating stylish cards, users can effectively highlight product features, display customer testimonials, promote special offers, and present news updates in a structured and eye-catching manner. This not only enhances the readability and engagement of emails, pages, and popups but also ensures that important information stands out and resonates with viewers, providing significant value to the end-users and enriching their design experience within your application.
The Image Round Corners feature allows your application's end users to easily add rounded corners to images from the side panel, enhancing the visuals of emails, pages, and popups. This built-in tool offers a sleek and professional design option, ensuring a modern look.
Together, these features empower your application’s end-users to create more compelling and attractive designs effortlessly. Users can employ these stylistic options to make their content more engaging and easier to scan.
Ensure you have the following prior to activating Cards Style and Image Round Corners:
Beefree SDK account (any plan type)
An application in the developer console
Client ID and Client Secret
Take the steps outlined in this section to enable Image Rounded Corners and Cards Style Widgets.
This section discusses how to enable Image Rounded Corners.
To activate Image Rounded Corners, follow these steps:
Log in to your developer console
Navigate to your application
Enter your application's configurations
Navigate to the Enable image rounded corners toggle
Toggle it to on
This section discusses how to enable Cards Style.
Follow these steps to enable the Cards Style Widget for your application:
Log in to your developer console.
Navigate to your application.
Enter your application's configurations.
Find the Enable cards style widgets toggle.
Toggle it on.
You can implement the image rounded corners and cards style features using content defaults in your application's configuration. The following code snippet demonstrates how to set the properties related to these features.
In this configuration:
Image Rounded Corners: The borderRadius
property under the image
key sets the border radius to "30px".
Cards Style Widgets: The row
key contains styling properties for widgets, such as columnsBorderRadius
, columnsPadding
, and columnsBackgroundColor
.
To control the permissions for the Cards Style and Image Round Corners features, use the following configuration sample.
This configuration allows you to manage whether these features are visible and editable to your application's end users.
The properties in the advanced permissions code snippet control the visibility and editability of specific interface elements related to Cards Style and Image Round Corners. By setting "show": true
, these elements will be displayed to end users. The "locked": false
property ensures that these settings can be modified by the end users. These configurations set the permissions for these features within your host application.
Consider the following when using Cards Style and Image Round Corners:
Round corners for Cards, Images, and Content Areas are not rendered in Outlook clients. The fallback is squared corners.
Visit Using Cards Style and Image Round Corners to learn more about how end users can use these features in your application's user interface.
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
This feature is available on Beefree SDK only.
The default Beefree SDK theme is grayscale and generally can be used with any color scheme. In v3, you can now choose between a dark and light theme for the loading animation, so it can better fit the host application’s UI. If you would like to change the loading icon and/or have more granular control of the loading theme, please view our article about .
This feature is available on Beefree SDK and above. If you're on the Core or Essentials plan, for free to try this and other Superpowers-level features.
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
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.
Is an alphanumeric string passed to Beefree SDK throughout the .
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 .
It will be counted as a unique user for .
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
Technically speaking, it allows you to change some parts of the CSS (Cascading Style Sheets) that controls the look & feel of the editor. If you want to use your own CSS, please refer to our feature.
This feature is available on Beefree SDK and above. If you're on the Core or Essentials plan, for free to try this and other Superpowers-level features.
Custom CSS is an advanced feature, which gives the host application great flexibility to customize the UI/UX of the builder. Please use this feature with caution. If you're looking to hide certain UI elements, we recommend you first check if that can be accomplished with , as it may be easier to implement.
This feature is available on Beefree SDK only.
If you’ve customized how the editor looks like, either through or , you may want default content to adhere to the same style.
Instantly display the results of – such as do not stack/reverse stack/hide on mobile;
When Mobile Design Mode is enabled for an application at , the builder will display two new icons in the upper-left corner of the content area, as highlighted below.
When the pill is highlighted in light blue, it means the property has been edited and applied in the mobile stage. The mobile pill can be styled using if covered by your .
Mobile Design Mode can be considered a “plug-and-play” feature because it just needs to be enabled on the and can be used by your users out of the box.
loads different workspace types (currently used to handle ).
This feature is available on the Beefree SDK and above. Additional limitations apply (). If you're on the Essentials or Core plan, for free to try this and other Superpowers-level features.
If you add to the mix, Beefree SDK becomes an all-around, real-time, collaborative content creation platform to design and review emails, landing pages, and popups, unifying your customers’ workflow under one roof.
Co-editing is available for Beefree SDK and plans:
You can for the main user and additional users in a collaborative editing session.
The onChange
callback allows you to track the activities and changes to the design JSON performed by session's main user (User A). Reference the onChange
to learn more about implementing and using this callback.
The onRemoteChange
callback allows you to track the activities and changes to the design's JSON performed by additional users (User B, User C, and so on). Reference the onRemoteChange
to learn more about implementing and using this callback.
You may override any of the default language strings using . The code block below contains the JSON required to replace all co-editing strings.
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.
download a two-factor authentication app to their mobile device (e.g. , , , and others);
This section includes a reference of the new classnames scheduled for release in March 2025. The new classnames will be related to and . For more details, click the > symbol to expand the expandable content sections containing additional information.
Reference the corresponding .
Reference the corresponding .
Reference the corresponding .
Reference the corresponding .
Reference the corresponding .
Reference the corresponding .
Reference the corresponding .
Reference the corresponding .
Hover Effect for Buttons is available on and is available for Email, Page, and Popup builders.
To learn more about the end user experience and what it looks like to utilize this feature on the frontend, visit the white label end user documentation. The markdown file is also available in our .
Important: Hover effects are supported by about 60% of email clients, with notable limitations in Outlook on Windows. View a .
Hover effects are supported by about 60% of email clients, with notable limitations in Outlook on Windows. Reference to view a list of email clients that are and aren't compatible with the Hover Effect for Buttons.
Log in to your .
Note: This feature is disabled by default for all existing applications. For new applications, it is enabled by default in the and Builder, but is disabled by default for the Builder.
The hoverStyles
object defines the visual changes that occur when a viewer hovers over a button with their cursor on a desktop. It allows you to set hover-specific styles such as font color, background color, and border appearance. These properties can be customized directly in the builder's Content Properties for the button. For example, changing the backgroundColor
in the Button Hover sub-section of Content Properties will update the button to reflect that color when hovered over. You can reference an example of a complete .
The mobileStyles
and hoverStyles
properties are not supported by the .
View a .
Multi-language Templates are only available for .
Enable the , which gives your end users access to a Translate button within the builder. When your end users click this button, all the translatable fields will automatically translate to the language corresponding with the template's language version. Note: MLT is a prerequisite for enabling the .
Enable the to allow your end users to translate their template language version's content with the .
This Configuration Guide will help you get started with configuring the MLT feature. We recommend you start with the section to ensure you have everything you need for a successful configuration.
If you are uncertain if your host application is a good candidate for this functionality, continue to the section to learn more about this feature.
Activate the language configuration in the
To use Multi-language Templates, your host application only needs to store one JSON file with the languages. For more information on this, visit the .
For more information on the end user experience for Multi-language Templates, visit our .
View a list of eligible content in the .
Log in to the .
The lang attribute on the content modules helps with .
To get HTML in a specific language by our , ensure you include a “language” key/value pair to the body of your request. Ensure you reference the instructions for using the of the to learn more about exporting template HTML.
Ensure you have a .
If you would like to provide your end users with the option to automatically translate all of the translatable content within their design, you can use the .
This feature is available for all . Available for Email Builder, Page Builder, and Popup Builder.
Reference the to learn more about how your application's end users can use this feature.
Reference the to learn more about how your application's end users can use this feature.
Visit the page to learn more about these configurations.
Visit the to learn more about these configurations.
Content Defaults: Define how content looks when dragged into an email or page.
Custom Sidebar Position: Choose whether to display the builder sidebar on the left or on the right side of the screen.
Content Title Sorting: Change the order of the content tiles in the editor’s sidebar.
Content Title Grouping: Group content tiles in the editor’s sidebar.
Loading Spinner Theme: Choose between a dark and light theme for the loading animation
Custom Tab Layout: Re-organize the way tabs are ordered.
Themes: Change the builder’s appearance when rendered within your application
Custom CSS: Define a custom look and feel through a CSS stylesheet
item_1-2
display-condition-card--cs
panel__actions
display-condition-card_custom--cs
display-condition-label--cs
display-condition-description--cs
display-condition-label_before--cs
display-condition-before--cs
display-condition-label_after--cs
display-condition-after--cs
display-condition-buttons--cs
row-display-condition-edit-button--cs
category-selected
selectable-modal-search--cs
back-action
selectable-modal-breadcrumb--cs
selectable-modal-items-list--cs
toggle-menu-button--cs
button-small--cs
button-large--cs
button-solid--cs
widget__textbox
button-primary--cs
widget__searchbox
button--cs
scrollable__panel--cs
add-form-field--cs
dropdown-menu--cs
dropdown-menu-button--cs
dropdown-menu-search--cs
input-search--cs
dropdown-menu-scrollable--cs
dropdown-menu-item--cs
icons-manager__pop--cs
button-small--cs
icons-manager__popcontent
button-solid--cs
popver__tab
button-primary--cs
social-add-icon--cs
button--cs
add-social-icon--cs
dropdown-menu--cs
dropdown-menu-button--cs
dropdown-menu-search--cs
input-search--cs
dropdown-menu-scrollable--cs
dropdown-menu-item--cs
toggle-menu-button--cs
button-small--cs
button-large--cs
button-solid--cs
scrollable__panel--cs
button-primary--cs
button--cs
add-attribute--cs
dropdown-menu--cs
dropdown-menu-button--cs
dropdown-menu-search--cs
input-search--cs
dropdown-menu-scrollable--cs
dropdown-menu-item--cs
widgets-section__heading
widgets-section__heading--cs
icon
sidebar-panel-title-icon--cs
icon-*
sidebar-panel-title-icon-comment--cs
sidebar-panel-title-icon-delete--cs
sidebar-panel-title-icon-duplicate--cs
sidebar-panel-title-icon-closepanel--cs
sidebar-panel-title-icon-save--cs
sidebar-panel-title-icon-editSyncedRow--cs
tgl-container
multi-toggle--cs
tgl-container--cs
multi-toggle-btns--cs
item_1-2
toggle-btn-pressed--cs
widget__label
btn-group
number-selector
number-selector--cs
tgl_bgd
multiToggle_option_descriptor_form_style_labels_font-weight_0
multiToggle_option_descriptor_form_style_labels_font-weight_1
button-default--cs
button-medium--cs
button--cs
active
item_1-2
social-collection-list--cs
widget__label
panel__title--cs
icons-manager__pop
title_icon
icon-organizer__panel
panel__icon-preview-wrapper
panel__title
comp-tree-placeholder
item_1-2
icons-collection-list--cs
widget__label
panel__title--cs
icon-organizer__panel
panel__icon-preview-wrapper
panel__title
comp-tree-placeholder
item_1-2
items-collection-list--cs
widget__label
item-organizer__panel--cs
icon-organizer__panel
panel__title--cs
icon-organizer__panel--cs
panel__icon-preview-wrapper
panel__title
title__icon
comp-tree-placeholder
item_1-2
form-items-list--cs
widget__label
form-item__panel--cs
icon-organizer__panel
form-field-item-id--cs
icon-organizer__panel--cs
panel__icon-preview-wrapper
panel__title
title__icon
comp-tree-placeholder
icon-manager__add-icon--cs
widget__label--cs
icon-organizer__panel--cs
carousel-slides-list--cs
comp-tree-placeholder
carousel-add-slide-btn--cs
slide-organizer__panel--cs
number-selector--cs
input-text--cs
item_1-2
input-text-boxed--cs
widget__textbox
widget__label
widget__label--textbox
btn
toggle-wrapper--cs
checkbox-wrapper--cs
toggle-input--cs
widget__label--cs
toggle-slider--cs
color
String
"#FFFFFF"
Sets the font color of the button when hovered.
backgroundColor
String
"#16688B"
Defines the background color of the button on hover.
borderTop
String
"0px solid transparent"
Specifies the top border's size, style, and color for the button when hovered.
borderLeft
String
"0px solid transparent"
Specifies the left border's size, style, and color for the button on hover.
borderBottom
String
"0px solid transparent"
Specifies the bottom border's size, style, and color for the button on hover.
borderRight
String
"0px solid transparent"
Specifies the right border's size, style, and color for the button on hover.
Improper JSON File Storage
Make sure the JSON file with the desired languages is correctly stored in your application.
Review the file location and ensure it’s accessible.
Disabled Multi-Language Templates
Double-check if the Multi-Language Templates feature is enabled in the Beefree SDK Console and set to “on.”
Enable the feature in the configuration settings.
Incorrect Configuration Properties
Verify the correctness of the `templateLanguage` and `templateLanguages` properties in the config object.
Correct any syntax errors or misconfigurations in the properties.
Language Direction Mismatch
Make certain that chosen languages follow the correct reading direction (left to right or right to left) and are defined with both value and label.
Ensure the languages are compatible with the chosen direction and follow the defined format.
Missing Language Drop-Down
If the language drop-down is not visible, review the setup steps in the Configuration section.
Revisit the configuration steps and check for any missing or incorrect settings.
HTML Saving Errors
If encountering issues with saving or exporting HTML, check the `bee.save` method for language parameters and the `onSave` event listener in the configuration.
Ensure proper usage of the `bee.save` method and validate the `onSave` event listener for any errors.
Incorrect `onSave` Handling
Ensure that the `onSave` callback correctly handles the HTML saving process for each language.
Review and update the `onSave` callback to address language-specific HTML saving properly.
Translation Export Issues
For exporting translations, validate that the defined languages are correctly represented in the array.
Double-check the array of languages for accuracy and completeness.
Missing `onSave` Callbacks
Implement `onSave` callbacks for each language to handle specific language-related data during export.
Create `onSave` callbacks for each language export to manage language-specific data appropriately.
Language Change Problems
When changing the template language, verify the existence of the specified language, and have an `onTemplateLanguageChange` callback to respond to language switches.
Confirm the language’s availability and define an `onTemplateLanguageChange` callback to handle language switches.
Learn more about what the Release Candidate Environment is, how to get started with it, and how to integrate it into your development life cycle.
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.
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.
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.
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.
Customers must be aware that while the RC version is production-ready, it is still subject to final testing and potential bug fixes.
This section discusses how to access the release candidate environment and use it.
To get the HTML version of a Beefree SDK message in the Release Candidate (RC) environment, you will need the following:
The Beefree SDK Support Team will provide you with a username and password (we will need a user’s email address to enable this).
A Beefree SDK JSON source file.
The ability to perform a call to a REST API. You can do that in different ways:
Applications like Postman or Insomnia
Use the “curl” command in a shell
With a custom script
The call should be addressed to one of the following endpoints, depending on the HTML output that you wish to receive back:
https://stg-bee-multiparser.getbee.io/api/v3/parser/email
- To receive HTML for Email
https://stg-bee-multiparser.getbee.io/api/v3/parser/pages
- To receive HTML for Webpages
https://stg-bee-multiparser.getbee.io/api/v3/parser/amp4email
- To receive AMP for Email
https://stg-bee-multiparser.getbee.io/api/v3/parser/popup
- To receive HTML for Popups
https://stg-bee-multiparser.getbee.io/api/v3/parser/text
- To receive the plain text version of the message
Reference the following additional requirements for using the Release Candidate Environment.
It has to be a POST call.
The Beefree SDK JSON has to be sent in the body of the REST call.
It must include a Basic Authentication header in which you specify your username and password.
Upon success, the body of the response will contain the desired output. In case of an error, the response's body will contain the error details.
Please do not use this method in production. This is an RC environment, and it may change its behavior in the future.
Example
Legenda
The following fields are required in the example above.
USERNAME and PASSWORD are your credentials provided by the Beefree SDK team.
JSON_FILE.json is the Beefree SDK source file.
OUTPUT.html is the desired output file.
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.
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.
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.
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.
Our Github account has some resources that might help you out when testing and integrating the Popup Builder.
Examples of different implementations and configurations that you can draw from to speed up your development.
A collection of ready-made templates that you can use right away and add to your application.
Contact the Beefree SDK team using this and request access to the Release Candidate Environment.
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 and request more information about customized release schedules with VPC plans.
When you log into the 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 , to ease new feature testing, development, and maintenance.
Out-of-the-box, the setup and configuration are the same as . This section will cover the settings specific to Popup Builder. Check out our if you’re new to Beefree SDK or unfamiliar with the configuration basics (as seen in the example below).
You can load forms in the builder with two methods:
If you successfully implement either method, you’ll see a new Form content tile in the builder Content tab.
Let’s see in detail how these methods work.
The default form will load when the user drags the form tile from the “Content” tab into the stage.
Here is an example of a typical login form:
The default form you pass to a Beefree SDK application may consist of a simple form (e.g., the most used one), or a longer form that the user can customize using the options in the form content properties, as pictured here:
The flexibility of these properties allows you to cover multiple form building capabilities, even when implementing just a default form. Let’s see how.
For higher flexibility and better user experience, the form can be customized with the optional canBeModified
, canBeRemovedFromLayout
, and removeFromLayout
attributes.
canBeModified
all fields except file
, hidden
, label
, and submit
,
since they cannot be edited
boolean
true
This attribute can be used to turn off the “Edit field” dialog for a field. If set to false, the configuration for that field will be locked to the one defined in the form JSON you passed to the application, except for the label.
If unspecified, it will be applied as true, allowing the user to edit the field using the builder UI.
canBeRemovedFromLayout
all fields
boolean
true
This attribute indicates that a field can be toggled off by the user. If unspecified, it will be applied as true, allowing the user to switch it on or off in the builder UI.
It’s a best practice to add canBeRemovedFromLayout: false
to mandatory fields (e.g., the email address field in a sign-up form) so that they can’t be excluded in the HTML form.
removeFromLayout
all fields
boolean
false
This attribute indicates that a field is toggled off by default when the form is loaded. This behavior is quite useful to simplify the first experience when working with forms:
you can use a single form with all the possible fields, so there is no form selection step;
you can hide less common fields to load the most used combination at first, and keep the starting point simple, or even empty;
the user than can explore available fields with the form properites and build their custom form
When added, the form shows the minimum fields for submtting an email, e.g. for subscribing to a newsletter:
but then, the user can toggle on the available fields to transform it:
The content dialog allows you to build a user interface for selecting a form, on top of the builder. It can be a simple list with prebuilt forms, a search through categorized forms, a small form configurator or wizard, or even a complete form builder tailored for your application’s data.
For detailed information about this feature, please check the content dialog section.
The object that defines the form content dialog is the following:
As with most content dialog objects, the label is used within the interface to trigger the function:
The args object in the handler function returns to the host application the form object already applied. With this information, the application can decide what to display to the user (e.g., edit the current form, suggest a similar form, etc.).
An example of the content dialog object in beeConfig that handles special links and forms:
by passing in the a single, default JSON form, potentially including all the fields your application supports;
by implementing a and building a user interface on top of the builder, so that your users can browse and select forms.
Use this method to provide a default form in the when the builder starts.
The Content Dialog feature is available on Beefree SDK only.
The resolve object in the handler function must return a form using the structure and parameters described in .
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.
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
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.
To access server-side configurations, log into your and select the application that you wish to configure.
Special Links and Merge Tags
Content Dialog
Custom Color Palette
Font management
Roles and Permissions
Smart Merge Tags
Commenting
Custom Attributes
Meta Tags
Custom Languages
Display Conditions
Advanced Permissions
Custom File Picker
Custom Headers
You can choose whether to display the builder sidebar on the left or on the right side of the screen.
Available positions:
left
right
Here is the same sample application, with the same template and same content element selected, and the sidebar displayed on the left…
… and on the right.
The configuration document needs the following, new parameter:
This feature is available on Beefree SDK only.
AMP for Email features interactive elements that email readers can use to take action directly in the inbox. It can also be used to fetch up-to-date information and present it each time an email is opened.
Traditionally, a marketing or a transactional email is a multipart message, with two different parts delivered as different MIME types.
HTML: this is what the vast majority of email clients support. It is also the usual output of our email builder.
Text: Originally, this was the only way to send emails. When the HTML MIME type was rolled out, not all email clients supported HTML, or readers could set their client to stick to the Text version. The text part still acts as a fallback for the HTML part. Beefree builders do not produce this MIME type.
The AMPHTML version will be delivered only to the inboxes of service providers that support AMP – currently Gmail, Yahoo Mail (webmail only), and mail.ru. All other clients will fall back to the HTML version.
Please note that adding AMP content in Beefree’s email builder is only possible through our AMP-powered widgets. We currently do not support adding AMPHTML markup directly into the message. Our first AMP content block is the AMP Carousel.
The AMP Carousel is OFF by default and you must first activate it in the Beefree SDK Console.
To do so:
Click Details next to the application you want to configure
We recommend you first try the AMP carousel under a DEV or QA application
Click view more under Application configuration.
In the AMP Content section, toggle Enable AMP Carousel ON and click the Save button to activate Commenting for the application.
Next, to activate the AMP Carousel when launching the builder, you will need to initialize your Beefree application with an AMP-compatible workspace.
We recommend starting by initializing a Beefree application with a “mixed” workspace, which is the most straightforward way of testing out the AMP Carousel. This parameter will:
activate the AMP Carousel block in the Content tab;
add a Hide on AMP/HTML property in the “block options” section of content blocks. This property will be essential when creating AMP emails to manage content visibility and fallbacks.
Also, when the message contains AMP content, you will:
see a switch between the HTML and the AMP version in the message preview;
receive an additional AMPHTML document when the OnSave
method is fired.
Here is how to load a Beefree application with a “mixed” workspace:
If the workspace is loaded successfully, a onLoadWorkspace(workspace)
callback is triggered.
The Carousel content tile will appear in the Content tab after enabling it in the Beefree SDK Console and loading the editor with an AMP-compatible workspace, as described above.
To start creating a carousel, users need to drag and drop the carousel block to the stage. By clicking on “browse” or dropping an image file in the block, they can start adding images, or as we call them in this context, “slides”.
The carousel looks best using images of the same size. However, it is possible to mix sizes in the slides: in that case, the logic that drives how the carousel is rendered is that the first slide will determine the carousel ratio. The slides that follow will be adapted to that ratio.
Beyond this, remember that images will be adapted to fill the carousel width, so if users choose an image less wide than the carousel, it will be stretched to fill it.
For each slide, users can:
set an alternate text in case the slide doesn’t load, the email client blocks images or the email is opened with a screen reader;
set a link so that clicking or tapping on the slide takes recipients to a specific destination;
rearrange the slides in the carousel by dragging the slide card inside the content properties panel;
Change image or delete the slide by using the controls in the slide card.
There are two additional properties for a carousel:
Autoplay, to enable automatic scrolling between slides, setting the interval in seconds between each slide (the autoplay stops if the recipient interacts with the carousel).
Dot navigation, to add a dot for each slide, so that the reader can jump to different images without scrolling with the arrows. The user can define the color of the dots.
The carousel can be previewed right inside the editing stage, using the left and right arrows in the AMP carousel block:
For a full preview, using real AMPHTML, users need to hit Preview, and they can switch between the AMP and the HTML version, both on mobile and desktop.
When using AMP content, it’s essential to create fallback for email clients that don’t support AMP. The fallback can be easily obtained with the “Hide on AMP/HTML” widget, available on all blocks as a content property.
It is very similar to the “Hide on Desktop/Mobile” control. Users can add the content for the HTML fallback and mark it as “Hide on AMP”. Inside the stage, a visual cue in the block’s outline will identify the block as hidden on AMP.
Besides the carousel, users can mark any part of the email as AMP-only by applying the “Hide on HTML” property.
No, it’s not possible to use the image editor. You might work around this limitation by editing the image in a standard Image block and then adding it to the carousel.
The best way to build a carousel is to use images with the same size, or that respect the same image ratio. Plus, the first slide should be wide at least as the carousel block, to avoid image stretching.
AMP is a versatile but pretty strict framework, and it will not render messages that don’t respect its validation protocol. The most common validation error is related to invalid HREF value in links (e.g., no URL, invalid or missing protocol, or incorrect URL composition).
To validate an AMP message before sending it out, all post-processing steps must beperformed (e.g., substitution of text variables that may impact link validation). Since Beefree builders use a replacement syntax and do not handle substitutions, we can’t currently provide a built-in validation without triggering false positives. However, nothing prevents you from adding a validation service in your application before sending out AMP emails.
The limit for the AMP version of an email, before being trimmed by Gmail clients, is 200Kb, up from 100Kb for HTML emails.
Once you turn on the feature in the Beefree SDK Console, you may want to disable AMP Carousel for some customers. You can do so via the client-side configuration document that you feed to your Beefree application when initializing the editor.
Why? Because you may decide to make the feature available to your customers:
depending on the subscription plan that they are on (i.e. you could push users to a higher plan based on the ability to use AMP);
depending on the purchase of an optional feature (same);
only if they are “beta” customers, so they see it while keeping it hidden from the rest of your users.
Here’s how to do so:
Enable AMP Carousel in the Beefree SDK Console, as mentioned above.
Your app must save the additional AMPHTML version of the email, when returned by the Beefree system, the same way it already saves the HTML version.
You should advise end-users on creating fallback for AMP content due to limited client support for AMP – optional, but highly recommended.
For example, if they create an image carousel with AMP, they should also add some images for the HTML version. They can hide content for the AMP version with the “Hide on AMP” content property.
The email senders – i.e., the end-users of your application – need to:
Have domain authentication in place (SPF, DKIM, DMARC) for the domain they use to send emails with your app.
Each email client has a separate registration process.
Each email address that will be used to send AMP emails address needs to be authorized individually.
These registration processes usually involve
Meeting the client’s bulk sender guidelines.
Sending a real, production-quality AMP email, from their production servers to a registration address.
is an open-source, web component framework, maintained by the OpenJS Foundation with significant support from Google. Its goal is to create great experiences across the web, focusing on interactivity and speed.
works by creating AMP markup that looks like HTML but is a new specification. That code is written in a separate email file, delivered using a third, additional MIME type (on top of existing HTML and text types). We’ll provide an additional AMPHTML document when there’s AMP content in the email saved by Beefree’s email builder.
Visit to learn more about what workspaces are and the additional workspaces you can use for AMP content.
If you don’t set a workspace when loading the builder, AMP widgets are not visible in the Content tab. However, if a message or template containing AMP is loaded, the builder will send an to your application. At that point, you may decide to switch to an AMP-compatible workspace, using the .
There are no particular limitations. You can use any image type that already works with the standard Image block (GIFs included). Please note that if you have a custom that limits the image types that can be loaded in the builder, it will reflect also on the AMP carousel.
Configure the ‘default’ workspace in the beeConfig document, so that AMP cannot be used (). As an alternative, if you don’t configure a workspace, the Beefree application will be loaded with the default workspace.
Your sending infrastructure must handle delivering an additional MIME type for AMP – this typically involves becoming an for dynamic emails.
In alternative, you can leverage one of the existing ESPs that already support sending AMP emails via SMTP or API, such as Amazon SES, Mailgun, and Sparkpost. See the full list list .
Register with , (Yahoo) and as an authorized sender for dynamic emails, so that AMP emails will be rendered in the inbox of recipients who use these clients.
As a final step, fill out the . This is the only form they need to fill out to be allowlisted to send AMP emails for all supporting email clients.
Integrate custom fonts and resized images into your designs. It saves custom fonts within the template's JSON, ensuring the correct font is displayed. It also handles image resizing, particularly when the image's initial template width is narrower than the saved row's destination template.
The collection ID or name
A string field for rowIdentifierLabel