Email Template Architecture

Understanding how the email template system processes MJML, handles variable substitution, and supports per-brokerage customization.

The Email HTML Problem

Email clients are notoriously inconsistent in rendering HTML. What works in Gmail breaks in Outlook. What looks perfect on mobile fails on desktop webmail.

Common email HTML challenges:

Outlook ignores CSS margins and requires MSO conditionals
Gmail strips <style> blocks and requires inline styles
Yahoo Mail has unpredictable rendering quirks
Mobile clients need responsive width handling

Writing email HTML that works everywhere requires:

Table-based layouts (not CSS Grid or Flexbox)
Inline CSS styles on every element
Microsoft Office conditionals for Outlook
Careful responsive breakpoints

MJML: The Solution

MJML (Mailjet Markup Language) is a framework that compiles to email-safe HTML. You write semantic components; MJML generates the complex underlying code.

MJML Components

<mjml>
  <mj-body>
    <mj-section background-color="#f8fafc">
      <mj-column>
        <mj-text font-size="16px">
          Hello {client_name}!
        </mj-text>
        <mj-button href="{action_url}">
          View Details
        </mj-button>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

This compiles to ~200 lines of email-safe HTML with:

Nested tables for layout
Inline styles on every element
MSO conditionals for Outlook
Responsive width calculations

Why MJML Over Raw HTML?

Developer Experience

Semantic tags like mj-button instead of nested tables

Consistency

Same output renders identically across email clients

Responsive

Built-in mobile breakpoints and stacking

Maintainable

Changes to source are easy to understand and review

Template Categories

Templates are categorized by who can edit them:

Platform Templates (Admin-Only)

System-critical emails that should be consistent across all brokerages:

Template	Purpose
`verification`	Email address verification for new brokers
`magic_link`	Passwordless login for favorites sync
`lead_assignment`	Internal lead routing notifications

These templates use HomeStar branding and cannot be overridden.

Customizable Templates (Broker-Editable)

Client-facing emails that brokerages may want to brand:

Template	Purpose
`lead_notification`	New lead alerts to agents
`tour_confirmation`	Property tour confirmations to clients
`market_report`	Market report delivery

Brokerages can override these with custom subject lines, content, and styling while maintaining the variable contracts.

Variable System

Templates use {variable_name} placeholders that are replaced at send time.

Variable Substitution

When an email is sent:

Template content is loaded (brokerage override or system default)
Pre-compiled HTML is retrieved (or MJML is compiled on-the-fly)
All {variable} placeholders are replaced with actual values
Final HTML is sent via email provider

html = render_template(
    "tour_confirmation",
    brokerage_id=5,
    client_name="Sarah Johnson",
    property_address="123 Oak Street",
    tour_date="Saturday, January 25",
    tour_time="2:00 PM",
    agent_name="Mike Chen"
)

Auto-Injected Brokerage Variables

When brokerage_id is provided, two variables are automatically injected:

Variable	Source	Fallback
`brokerage_name`	Brokerage record	(required in call)
`brokerage_logo_url`	Brokerage record	HomeStar logo SVG

This ensures consistent branding without requiring every caller to look up brokerage details.

Variable Schema

Each template defines a schema documenting its variables:

{
  "client_name": {
    "type": "string",
    "required": true,
    "description": "Recipient's display name"
  },
  "tour_date": {
    "type": "string",
    "required": true,
    "description": "Formatted tour date"
  },
  "agent_phone_display": {
    "type": "string",
    "required": false,
    "description": "Agent phone with HTML formatting"
  }
}

The editor uses this schema to:

Show variable chips with descriptions
Highlight required variables in amber
Provide autocomplete in the subject field

Brokerage Override System

Customizable templates support per-brokerage overrides with cascading resolution.

Lookup Order

When rendering a template:

Brokerage Override — Check for active override for this brokerage
System Default — Use the platform-wide template from database
File Fallback — Load from filesystem (legacy support during migration)

def get_template_content(slug, brokerage_id=None, db=None):
    # 1. Try brokerage override first
    if brokerage_id:
        override = db.query(BrokerageEmailTemplate)...
        if override and override.is_active:
            return override.get_effective_content()

    # 2. Try system default from database
    template = db.query(EmailTemplate)...
    if template:
        return template

    # 3. File-based fallback
    return load_from_file(slug)

Partial Overrides

Brokerage overrides can customize only specific fields:

Override Field	Null Behavior
`subject_template`	Use system default subject
`mjml_content`	Use system default body
`text_content`	Use system default plain text

A brokerage might override just the subject line while keeping the standard body, or customize the entire email.

When to Use Overrides

Good candidates for override:

Adding brokerage taglines to subject lines
Customizing color schemes to match brand
Including brokerage-specific contact information
Modifying call-to-action button text

Not recommended:

Removing required information (unsubscribe links, etc.)
Changing the fundamental purpose of the email
Breaking variable contracts

Compilation Pipeline

MJML compilation happens at save time for performance.

Save-Time Compilation

Admin edits MJML in visual or code editor
Admin clicks Save
Server compiles MJML → HTML using mjml_to_html()
Compiled HTML stored in compiled_html column
compiled_at timestamp updated

Render-Time Efficiency

At send time:

Pre-compiled HTML is loaded directly (no compilation)
Variable substitution is simple string replacement
No MJML parsing overhead

If compiled_html is missing (legacy or error), compilation happens on-the-fly with a warning logged.

Compilation Errors

MJML is forgiving but can produce warnings:

result = mjml_to_html(mjml_content)
if result.errors:
    # Log warnings but proceed
    logger.warning(f"MJML warnings: {result.errors}")
html = result.html

Common warnings:

Deprecated attributes
Missing recommended attributes
Non-standard tag usage

Performance Characteristics

Storage Requirements

Content Type	Typical Size
MJML source	2-5 KB
Compiled HTML	8-15 KB
Text fallback	0.5-1 KB
Variable schema	0.5-1 KB

Render Performance

Operation	Typical Time
Load from database	1-5 ms
Variable substitution	< 1 ms
MJML compilation (fallback)	50-200 ms

Pre-compilation eliminates the 50-200ms MJML overhead at send time.

Visual Editor Architecture

The frontend uses GrapesJS with the MJML plugin:

Lazy Loading

GrapesJS and its MJML plugin are loaded dynamically when a user first opens the visual editor:

if (!grapesjs) {
  const [gjsModule, mjmlModule] = await Promise.all([
    import('grapesjs'),
    import('grapesjs-mjml'),
  ]);
  grapesjs = gjsModule.default;
  grapesjsMjml = mjmlModule.default;
}

This reduces initial bundle size by ~500KB.

MJML ↔ Editor Sync

Loading: MJML is parsed into GrapesJS components
Editing: Changes update the internal component model
Saving: Components are exported back to MJML via mjml-export command

Why GrapesJS?

MJML Native

First-class MJML support via official plugin

Drag & Drop

Visual block-based editing for non-developers

Extensible

Custom blocks, panels, and commands possible

Code Access

Switch to raw MJML for power users

Security Considerations

Variable Injection

Variables are substituted with simple string replacement. To prevent XSS:

Email HTML is rendered in iframes (preview)
Email clients sanitize HTML on their end
Don’t allow arbitrary HTML in variable values

Template Access Control

Platform templates: Admin-only editing
Customizable templates: Future broker editing via role check
All templates: Read-only for non-admin users

Audit Trail

Every template save records:

updated_by — Email of the editor
updated_at — Timestamp of change
compiled_at — When HTML was regenerated

Manage Email Templates — Step-by-step editing guide
Email Template Variables — Complete variable reference