.png)
If you’ve ever inherited a pile of legacy HTML email templates and thought, “There has to be an easier way to bring these into the builder,” we heard you, and we built the HTML Importer API just for you.
The new HTML Importer API converts HTML emails into editable, drag-and-drop templates powered by Beefree’s proprietary JSON structure. Whether you’re a developer handling integrations or a product manager thinking through onboarding workflows, this feature gives you a fast, flexible way to bring legacy email content into the modern builder experience.
In our recent Spotlight Session, Senior Developer Advocate Lawrence Lockhart and Full Stack Developer Luca Filice walked through exactly how this new feature works, what makes it unique, and how to get started.
As an added bonus, they’ve created sample code you can use to easily add a simple Import button into your configuration.
What is the HTML Importer API?
The HTML Importer API is a conversion tool that transforms standard HTML emails into Beefree JSON. This means that HTML emails, whether built years ago or generated last week, can now be imported into the SDK builder and edited visually without needing to be completely rebuilt from scratch.
Why it matters:
- Drag-and-drop freedom: Once imported, content is fully editable with Beefree’s visual tools.
- Save time onboarding new users: Skip rebuilding their HTML email designs from scratch and import in just seconds, not hours.
- Repurpose legacy content: Bring in your older templates without burning dev hours recreating in the SDK.
Whether you’re onboarding new users with existing HTML libraries or revisiting old favorites, this API bridges the gap between past work and future innovation.
How it works
- Enable the API in your Beefree SDK Developer Console
Head to your app's detail page, find the HTML Importer API section, and click “Enable and get API key". - Call the Endpoint
Make a POST request to the https://api.getbee.io/v1/conversion/html-to-json endpoint with your HTML as the payload. - Authenticate
Enter your API key as a Bearer Token in the Auth Type field, and ensure your request body's Content-Type is set to text/html. - Enter HTML and Send
Insert the HTML you'd like to convert into the request body field and ensure it meets the requirements outlined in our documentation. Then, click Send. - Get JSON Back
The API returns Beefree’s JSON schema, ready to load into the SDK editor.
A few technical notes:
- The API accepts well-formed HTML that includes doctype, <html>, <body>, and<meta charset="UTF-8"> tag in the head section of your HTML.
- Assets like images must be hosted publicly.
- Merge tags and dynamic content aren’t supported during import, but can be added afterward.
- The output is deterministic; identical HTML will always return the same result.
In the Spotlight Session, Luca showed how you can create a simple Import button to make this call easy and intuitive for your users. You can find this sample code here in our GitHub repository.
Bonus: Pair it with Brand Style Management for bulk style changes
You can go one step further and instantly apply brand styling to imported content using the Brand Style Management endpoint.
Once the HTML is converted and loaded into the builder, use the Brand Style Management endpoint to apply custom fonts, colors, and other styles defined in your JSON schema. This ensures that even legacy templates reflect your users’ current branding.
Here’s how:
- Enable the Content Services API in the SDK console.
- Send a POST request to the https://api.getbee.io/v1/template/brand endpoint with:
- The imported template
- Their brand’s style definition in JSON
- The imported template
One detail to keep in mind: if your style definition doesn’t match any elements in the template, the system will return a 422 status code, basically saying “nothing to update”.
Luca also created sample code for a button that allows your end users to easily apply their styling, which you can access here.
How this helps you drive more revenue
This combo of APIs unlocks powerful workflows:
- Client onboarding: Import customer-provided HTML into your platform without starting from scratch.
- Template upgrades: Convert old designs into editable layouts with on brand designs in just a few clicks.
- Content reusability: Empower teams to work from existing materials while preserving design flexibility.
- Custom pricing models: Limit or charge for usage per user, per import, or as part of a plan tier.
Frequently Asked Questions
Does the importer support external CSS?
We recommend using inline styles. External CSS isn’t officially supported and may result in inconsistent rendering.
Can I test it for free?
Currently, each successful import is billed at $2. If testing access is something you need, let us know at sdksupport@beefree.io.
What happens to unsupported HTML tags?
They’ll be ignored or stripped. They won’t break the import process, but may not render as expected.
Can I limit usage for end users?
Absolutely. Track usage on your side by user ID, and create thresholds, limits, or pricing as needed.
What about images?
Imported templates will reference the image URLs from the original HTML. Nothing is uploaded to the file manager unless added manually.
For additional FAQs, please refer to our HTML Importer API documentation.
Resources to Explore
Get started today
The HTML Importer API is a simple but powerful way to bring your existing HTML templates into the Beefree SDK. It’s developer-friendly, marketer-approved, and designed to accelerate how your teams build and manage content.
Need help, have ideas, or want to see what others are building? Reach out to sdksupport@beefree.io. We’d love to hear from you.
.png)
