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.
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 Beefree SDK File Manager.
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
The API uses JSON as the input and output data format: Responses are JSEND standard compliant.
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:
In the event a request fails, the API returns the error codes described in the Error codes section.
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.
User information is segmented by UID parameter.
Ensure you save the username, password, and base URL in the Configuration section of the Beefree SDK Console.
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:
Add a can-move field in the extra object in the listing directory content response. 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 Listing for Move Dialog section for steps on how to complete this.
Implement a PATCH method for file URLs with conflict_strategy management. Reference the Implement PATCH Method section for steps on how to complete this.
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.
Note: When you replace an image, the thumbnail updates immediately to show the new version. However, the main image URL, which is used in the stage and in any previously sent emails, may still display the old version until the cache clears. This cache expiration typically happens within 2 hours but can vary.
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.
The final step in activating the move feature 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.
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.
The following response is the same as the upload method. This is the response you will see in the event that a file was successfully moved to a new location.
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
The trailing slash (/) on the request matters!
The FSP API uses the trailing slash (/) on the resource path to understand if the required resource is a file (no trailing slash) or a directory (with trailing slash).
For example, if the FSP API receives a GET request for /sample.jpg it will return sample.jpg file metadata, whereas if it receives a GET request for /sample.jpg/ it will return a list of the content located in the sample.jpg directory.
In case of errors, the API returns a JSON object structured like this:
To read the full list of possible errors, please refer to this page.
Thumbnail generation is up to the developer of the file system provider.
In case you don’t want to develop your own thumbnail generation procedure, you can use a service like rethumb by Rapid to create a thumbnail URL.
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).
When you configure a builder application, you have four options for image & file storage:
Beefree SDK storage: unless you select another option, images will be hosted in Beefree SDK’s own AWS S3 bucket. See below for details about potential fees associated with this option.
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.
Your own AWS S3 bucket: instead of using Beefree SDK’s AWS S3 bucket to store & deliver files, you can use your own. See Configuring your own S3 bucket.
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 your file system.
When working with your own custom file system provider, there are many considerations to keep in mind. Follow the steps outlined in the Move Files in the File Manager documentation to ensure you configure this feature successfully for this storage option.
End users can upload images, PDFs, and other documents to the builder. For instance, they can link a button to download a PDF report.
Reference the white label end-user documentation 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 file manager limitations in the Privacy & Security section of your app’s configuration. In alternative, you may consider connecting the builder to your file system.
By default, images used in emails and pages created with the builder are stored in Beefree SDK’s file storage system. Beefree SDK uses Amazon Web Service’s S3 service for storage, and leverages Amazon’s Content Delivery Network (CloudFront) for fast content delivery.
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.
Beefree SDK customers that exceed 50 GB of image data traffic on the Free plan in a given month will be moved to our Essentials plan.
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.
Navigate to the Beefree SDK Developer Console.
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.
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 Beefree SDK Console, and going into the application details, in the Statistics widget.
You can switch to using your S3 storage or connect your file storage.
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.
Please contact your account manager for this. If you are not sure how to do this, please log into the Beefree SDK Console and submit a support ticket asking for your usage history.
This feature is only available on Beefree SDK paid plans.
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.
Their name is restricted by .
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.
Note: Images path and Thumbs path must be valid directories in the bucket.
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:
Note: If you change the custom URL, the new URL is immediately used for all images.
Example using single folders in the bucket root:
Example using single nested folders:
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.
Remember to save your changes with the SAVE button at the top.
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.
| Field | Description |
|---|---|
| Field | Description | Type | Example |
|---|---|---|---|
| Field | Description | Notes | Type |
|---|---|---|---|
| Field | Description | Notes | Type |
|---|---|---|---|
| Metadata | Type | Description |
|---|---|---|
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).
| Parameter | Description | Required |
|---|
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.
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.
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 |
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. .
