Beyond the prompt: The architectural fix for broken email code

Let's get straight to it. You’re using a Large Language Model (LLM) to generate email content, and the HTML it spits out is, to put it mildly, a mess. It looks great in the playground, but test it in a real email client, and the design falls apart. The branding is wrong, it’s not responsive, and it completely fails accessibility standards.

You end up spending hours fixing what the AI was supposed to do in seconds. This isn't a failure of the AI’s creativity. It's a failure in our approach. We’re asking a brilliant copywriter to also be a master email developer, and that’s a role it was never trained for.

The problem isn't your prompt, it's your architecture

Many developers fall into the trap of trying to solve this with increasingly complex prompts. They’ll add detailed instructions about div structures, inline CSS, and VML for Outlook. This is a losing battle. You’re essentially trying to teach a machine the dark arts of email coding through a chat window.

The real solution isn't better prompting; it's better architecture.

My angle is this: we need to apply a fundamental software design principle here, separation of concerns. Let the AI do what it’s good at, which is generating the substance of your message (the words and ideas). Then, let a specialized system handle what it’s good at, which is applying the structure (your brand guidelines, responsive code, and accessibility rules).

When you build a system that separates content from presentation, you get the speed of AI without sacrificing the quality of a professional design system.

So what does this ideal architecture look like in practice? Imagine a workflow where a user generates content with an AI, then brings that content into a platform that handles the heavy lifting. This platform would automatically enforce brand guidelines, ensure accessibility compliance, and manage the complexities of email client rendering.

From there, the user could iterate on the design inside the platform, making tweaks and refinements until they have the perfect final version.

The last step would be exporting clean, campaign-ready HTML that just works.

The Beefree SDK provides the foundational tools to create this exact platform.

Teaching AI and humans a common language: JSON

To make this architecture work, you need a way for the AI and your design system to communicate. Beefree SDK achieves this with two distinct JSON schemas and two API endpoints that act as translators.‍

1. Full JSON Schema: This is the complete blueprint Beefree uses to render every pixel of your design. It's powerful and precise for the editor but far too complex for an AI to manipulate safely. One wrong bracket, and the whole design can break.
2. Simple Schema: This is a lightweight, simplified version that focuses only on the core layout and content. It’s clean, easy to parse, and perfect for an AI to read and edit without touching the underlying design complexity.

The bridge between these two schemas is our Content Services API, specifically two endpoints: full-to-simple-json and simple-to-full-json.

The round-trip workflow: A practical guide

Here’s how you can build a workflow that allows an AI to safely edit a human-made design.

Step 1: Start with a human-made design (Full JSON)

Your process begins in the Beefree builder. A user creates or opens a template, and the onSave callback gives you the pageJson. This is the Full JSON representation of the email design.

Step 2: Convert from Full to Simple Schema

Take that Full JSON and send it to our full-to-simple-json endpoint. This API call simplifies the JSON so that it is AI-ready, easy for AI to understand and interpret.

Step 3: Iterate with an AI Agent

Now you can hand the Simple Schema to your LLM with a clear, content-focused prompt on the backend. The LLM will generate an email in Simple Schema JSON that considers the prompt and additional context.

For example: “You are an expert marketing copywriter. Based on the following JSON, make the text in the title module more exciting and urgent. Create 5 iterations of this modification. Return only the complete, updated JSON objects.”

AI will then use this backend prompt to generate an email in Simple Schema JSON.

Step 4: Convert from Simple back to Full JSON

Once the AI returns the modified Simple Schema objects, send them to the simple-to-full-json endpoint. This call applies the AI's new content in Full Beefree SDK JSON, which is compatible for loading within the no-code drag-and-drop email builder.

Step 5: Load and finalize in the Editor

Finally, use beeInstance.load() to load the new Full JSON back into the Beefree builder. Your user now sees their original design, but enhanced with the AI’s suggestions. They can review the changes and make any final tweaks before sending.

Unlocking real capabilities

The Beefree SDK is more than a drag-and-drop editor; it's a content platform built on a flexible JSON core. This round-trip workflow opens the door to powerful features:

• AI-assisted editing: Let users start with a professionally designed template and use AI to brainstorm and refine the copy.
• Automated A/B testing: Programmatically generate dozens of content variations for testing without anyone needing to manually copy and paste.
• Headless content refinement: Build automated systems that suggest content improvements to your library of templates based on performance data.

By providing an API-powered bridge between human design and artificial intelligence, we give you the tools to build smarter, more efficient content applications.

Ready to build a better AI content workflow? Check out the Beefree SDK Content Services API documentation to get started.

And if you're looking for more use cases of our SImple Schema, including how you can create templates with AI, watch our Spotlight Session or access our Cookbook.