Manage Email Templates

This guide walks through editing email templates, using the visual editor, previewing changes, and sending test emails.

---

Before You Start

1. Log in as an admin at your site’s /admin path
2. Navigate to Email Templates in the sidebar
3. Ensure you have access to an email inbox for testing

Note

Only administrators can edit Platform templates. Customizable templates can be overridden by brokerages in future releases.

---

Selecting a Template

The template list is organized into two categories:

• Platform — System emails that only admins can modify (verification, magic link, lead assignment)
• Customizable — Templates brokerages can override with their own branding (lead notification, tour confirmation, market report)

1. Click a template name in the left sidebar
2. Wait for the template to load (shows header with name and category badge)
3. The URL updates to #template-slug for bookmarking

Caution

If you have unsaved changes, switching templates will prompt you to confirm discarding them.

---

Editing the Subject Line

The subject line supports variable substitution with autocomplete:

1. Click in the Subject Line field
2. Type { to trigger the variable popover
3. Select a variable from the categorized list
4. The variable is inserted as {variable_name}

Alternatively, click the Insert variable button (icon next to the field) to open the picker directly.

Tip

Required variables are highlighted in amber. Include all required variables to ensure emails render correctly.

---

Using the Visual Editor

The visual editor uses GrapesJS with MJML support for drag-and-drop email design:

Adding Components

1. Open the Blocks panel (typically left side of editor)
2. Drag MJML blocks onto the canvas:
   • mj-section — Container rows
   • mj-column — Column layouts
   • mj-text — Text content
   • mj-image — Images with src attribute
   • mj-button — Call-to-action buttons
3. Click any component to select it
4. Use the Style Manager panel to adjust colors, spacing, fonts

Editing Text Content

1. Double-click any text component to enter edit mode
2. Type or paste your content
3. Use {variable_name} syntax to insert dynamic values
4. Click outside to exit edit mode

Note

MJML automatically converts your design to email-safe HTML with inline styles, table layouts, and Outlook compatibility.

---

Using the Code Editor

For direct MJML editing:

1. Click the MJML Code tab
2. Edit the MJML source directly
3. Use proper MJML tags (<mj-section>, <mj-text>, etc.)
4. Switch back to Visual Editor to see rendered preview

When to use code mode:

• Fine-tuning responsive breakpoints
• Adding custom CSS via <mj-style>
• Debugging layout issues
• Copying templates between environments

---

Using Variables

Variables enable dynamic content in templates. The Variables panel (right sidebar) shows all available variables for the current template:

Variable Categories

Category	Example Variables
Recipient	client_name, user_email
Property	property_address, listing_price
Agent	agent_name, agent_phone_display
Brokerage	brokerage_name, brokerage_logo_url
Tour	tour_date, tour_time

Inserting Variables

1. Click a variable chip in the Variables panel
2. The variable is copied to clipboard as {variable_name}
3. Paste into the subject line, visual editor, or code editor

Tip

Amber badges indicate required variables. Gray badges are optional and may not always have values.

---

Previewing Changes

The Preview panel shows how the email will render:

1. Make changes in the editor
2. The preview updates with sample data
3. Click the Refresh button to force-update if needed
4. Scroll to see the full email layout

The preview uses sample data configured for each template (stored in preview_data).

---

Sending Test Emails

Before deploying changes, send a test email:

1. Click Send Test button in the header
2. Enter a recipient email address
3. Click Send Test
4. Check your inbox for the rendered email

Caution

Test emails use sample data, not real user information. Verify all variables render correctly before saving.

---

Saving Changes

1. Click Save (enabled only when changes exist)
2. Wait for MJML compilation to complete
3. Success toast confirms the save
4. The “Unsaved” badge disappears

Saving triggers:

• MJML → HTML compilation
• Storage of compiled HTML for fast rendering
• Preview regeneration with new content

---

Template Reference Quick Links

Template	Category	Purpose
verification	Platform	Broker email verification
magic_link	Platform	Passwordless login for favorites sync
lead_assignment	Platform	Agent lead assignment notifications
lead_notification	Customizable	New lead alerts to agents
tour_confirmation	Customizable	Client tour confirmations
market_report	Customizable	Market report delivery

---

Troubleshooting

Visual Editor Won’t Load

Symptoms: Blank canvas or “Failed to load visual editor” error

Solutions:

• Refresh the page and try again
• Switch to MJML Code tab as fallback
• Check browser console for JavaScript errors
• Ensure ad blockers aren’t blocking GrapesJS CDN

Preview Shows Broken Layout

Symptoms: Misaligned content or missing styles in preview

Solutions:

• Verify MJML syntax is valid (no unclosed tags)
• Check that all mj-section tags have mj-column children
• Avoid using raw HTML outside MJML components
• Save and refresh to trigger recompilation

Variables Not Substituting

Symptoms: Email shows literal {variable_name} text

Solutions:

• Verify variable name matches exactly (case-sensitive)
• Check that variable is defined in the template’s schema
• Ensure the sending code passes all required variables
• Review server logs for missing variable warnings

Test Email Not Received

Symptoms: No email in inbox after clicking Send Test

Solutions:

• Check spam/junk folder
• Verify recipient email address is correct
• Review server logs for SMTP errors
• Confirm email service (Resend, SendGrid) is configured

---

Related Documentation

• Email Template Architecture — How the MJML system works
• Email Template Variables — Complete variable reference