Custom AddOns

Introduction

Custom AddOns are useful when there is a feature you'd like to offer within your application that is not available in our AddOn Marketplace within the Developer Console. In these instances, you can develop your own Custom AddOns for your application's end users.

Custom AddOns extend the functionality of the Beefree email builder by allowing you to create custom content tiles that integrate with your own services, data sources, and workflows. Whether you're building an image generator, product catalog integration, or custom HTML component, Custom AddOns give you the flexibility to tailor the editor to your specific needs.

Common Use Cases

The following list outlines a few of the most common use cases for building Custom AddOns.

• E-commerce Integration: Build AddOns that pull product data from your catalog and insert product images, descriptions, and pricing.

• Image Libraries: Connect to stock photo services, user-uploaded assets, or AI image generators.

• Dynamic Content: Create AddOns for countdown timers, live social media feeds, weather widgets, or personalized recommendations.

• Third-Party Services: Integrate with CRMs, marketing platforms, analytics services, or any external API.

Example of a Custom AddOn

Let's say you embedded our email editor in your event engagement platform, which has a feature that allows event marketers to insert an event ticket's QR code in marketing campaigns sent to create more engagement around an event.

• You want those marketers, users of your platform, to be able to easily include a QR code in the emails they send to remind people about the event. That way ticket holders can use the QR code to quickly get into the event venue.

• So you decide to create a "QR Code" addon: "QR Code" becomes a new tile in the Content tab in the editor.

• Marketers drag and drop the tile, click on Select event to indicate which event the QR is for, and use the editor to style that section of the message (e.g. size, padding, etc.).

• The QR code is created dynamically by your platform, at the time the email is sent to a ticket buyer.

• The feature is specific to your application.

Getting started

Log into the Beefree SDK Console and locate any application that is on the Superpowers or Enterprise plans. Click on Details to navigate to the application details page. In the lower part of the page, locate the Application configuration section and click on AddOns.

You will be taken to a page that lists the AddOns that have been installed for this application. Since you are just getting started, the list is likely empty. Click on Create a custom addon to start the process of creating a Custom AddOn.

Refer to the How to Build AddOns with Content Dialog and Build AddOns with External Iframe for more details on how to build your AddOn.

Prerequisites

Before you start building Custom AddOns, ensure you have:

1. A Beefree SDK account at developers.beefree.io

2. Superpowers plan or above — Custom AddOns are only available on the Superpowers and Enterprise plans. If you're not on one of these plans:

   • Create a development application

   • Request an upgrade from your account dashboard

3. A development application — Always test your AddOns in a development environment before deploying to production. Development applications inherit the plan of the production application they're connected to.

Development Methods

There are two methods for building Custom AddOns. They are:

• Content Dialog Method

• External Iframe Method

Available AddOn Types

Custom AddOns can return different types of content. Each type displays different properties in the editor's sidebar:

Quick Start Guide

Here's a high-level overview of the process to create a Custom AddOn:

Step 1: Create AddOn in Beefree SDK Console

1. Log into developers.beefree.io

2. Navigate to your application's AddOns section

3. Click Create a custom addon

4. Fill in the form:

   • Name: Display name shown to users

   • Type: The content type your AddOn will insert (Image, HTML, Button, etc.)

   • Handle: Unique identifier for your code (e.g., my-custom-addon)

   • Method: Content Dialog or External Iframe

   • Icon: Optional custom icon for your AddOn tile

   • Description: User-facing explanation

5. Click Create

6. Copy your AddOn Handle — you'll need it in your code

Step 2: Register AddOn in Your Code

Add the AddOn to your beeConfig:

const beeConfig = {
  // ... other config options
  addOns: [
    {
      id: 'my-custom-addon',  // Must match the handle from Console
      openOnDrop: true        // Optional: Auto-open when dropped
    }
  ],
  contentDialog: {
    addOn: {
      handle: 'my-custom-addon',  // Must match the handle from Console
      handler: (resolve, reject, args) => {
        // Your AddOn logic goes here
      }
    }
  }
};

Step 3: Implement Handler Logic

Your handler must resolve with a properly formatted content object matching your AddOn's type.

Content Object Structure:

// Image AddOn Example
resolve({
  type: 'image',
  value: {
    src: 'https://example.com/image.jpg',
    alt: 'Description'
  }
});

// Button AddOn Example
resolve({
  type: 'button',
  value: {
    label: 'Click Me',
    href: 'https://example.com',
    'background-color': '#7747FF',
    color: '#FFFFFF',
    'border-radius': 4,
    'padding-top': 12,
    'padding-right': 24,
    'padding-bottom': 12,
    'padding-left': 24
  }
});

// Heading AddOn Example
resolve({
  type: 'heading',
  value: {
    title: 'h2',
    text: 'Welcome!',
    align: 'center',
    size: 28,
    color: '#333333',
    bold: true
  }
});

// HTML AddOn Example
resolve({
  type: 'html',
  value: {
    html: '<div>Custom HTML</div>'
  }
});

Step 4: Test Your AddOn

1. Initialize Beefree SDK with your config

2. Look for your AddOn tile in the Content tab

3. Drag and drop the tile onto the stage

4. Verify that:

   • Your handler is called

   • The module appears on the stage

   • Sidebar properties display correctly

   • Clicking the module works as expected

Content Object Schema

All AddOns must resolve with a content object that follows this structure:

{
  type: string,        // Must match your AddOn type
  value: object,       // Type-specific properties
  mergeTags: array     // Optional: For dynamic content
}

The value object varies by type. See the AddOn Types documentation for complete schemas for each type.

Direct Open Feature (openOnDrop)

The openOnDrop property controls whether your AddOn handler is triggered immediately when a user drops the tile onto the stage:

addOns: [
  {
    id: 'my-custom-addon',
    openOnDrop: true  // Handler opens automatically on drop
  }
]

When to use openOnDrop: true:

• User needs to configure the module before insertion (e.g., select an image, enter button text)

• Your AddOn requires user input

When to use openOnDrop: false or omit:

• Your AddOn inserts pre-defined content

• No user interaction is needed

• Users can configure the module after insertion via the sidebar

You can detect if your handler was triggered by a drop action:

handler: (resolve, reject, args) => {
  if (args.hasOpenOnDrop) {
    // Handler was triggered by a drop action
  }
  // Your logic
}

Troubleshooting

Module Not Appearing on Stage

• Check that your resolve() content object matches your AddOn's type

• Verify the type property in your content object matches the Console type

• Open the browser console for validation errors

• For Title AddOns specifically: Ensure you're using type: 'heading' (not type: 'title'), and that you've included the required title property (e.g., 'h1', 'h2', 'h3', 'h4')

Handler Not Firing

• Confirm the handle in contentDialog.addOn.handle matches the handle from Console

• Check that the AddOn is registered in the addOns array with the correct id

• Verify your AddOn is enabled in the Console

Sidebar Not Showing Expected Properties

• Ensure the type in your content object is correct

• Check that you're using the correct property names (e.g., label for buttons, not text)

• Review the Simple Schema documentation for your type

Content Not Editable

• HTML and Mixed types are only editable by reopening your AddOn

• Other types should be editable via sidebar — check your content object structure