Menu
Login

The Idea Loft

The Idea Loft Blog

Ant
Ant
Blog owner

Email Templates – Authoring Guide 02 Dec 2025 • 3 min read

This page explains how to create and use email templates in ChatApp.
Back to Folder

1. Introduction

ChatApp includes a flexible, developer-friendly email templating system built on Fluid, a lightweight and secure Liquid-style templating engine for .NET.
The goal is to let product and support teams customize email content—while keeping rendering logic safe, consistent, and fully controlled.

Templates can:

  • Use variables and structured data

  • Include reusable layouts (headers, footers, branding)

  • Be previewed live in the browser

  • Send test emails

  • Be triggered automatically by system events (coming soon)

This guide explains how the system works and how to create, maintain, and troubleshoot templates.

2. Template Types

There are two kinds of templates in the system:

2.1 Regular Email Templates

These define the actual message body, such as:

  • Welcome emails

  • Invoice confirmations

  • Password reset notifications

  • Marketing campaigns

Regular templates can have a layout assigned to them.

2.2 Layout Templates

Layouts act as reusable wrappers that provide consistent:

  • Branding

  • Container styles

  • Header and footer elements

  • Typography

  • Unsubscribe/footer blocks

A layout contains a special placeholder:

[BODY] 

When an email is rendered, this placeholder is replaced with the processed content of the regular template.

Example layout:

<html> <body style="font-family: sans-serif"> <div class="header">ChatApp</div> [BODY] <div class="footer">© 2025 ChatApp</div> </body> </html> 

Templates marked IsLayout = true appear only in the layout dropdown.

3. Template Structure

Each template supports three key building blocks.

3.1 Parameters (Variables)

Variables allow inserting small dynamic values:

Hello {{ userName }}, Your account has been created. 

These values are supplied when the email is rendered.

3.2 Data Blocks

For more complex content, templates can loop over structured data:

{% for item in order.items %} <div> {{ item.name }} — {{ item.price | currency }} </div> {% endfor %} 

Data blocks map directly to your C# backend’s object model.

3.3 Conditional Logic

Liquid-style conditionals allow variation in content:

{% if user.isPremium %} Thanks for being a premium customer! {% endif %} 

No code execution is allowed—Fluid ensures templates stay safe.

4. Layout Assignment Workflow

4.1 Choosing a Layout

When editing a template, the UI provides a dropdown list of available layouts.

Choosing a layout:

  • Updates preview instantly

  • Stores the reference via LayoutTemplateId

  • Ensures the template is rendered inside the layout wrapper during sending

4.2 Rendering Pipeline

Rendering works in three steps:

  1. Process the template body with Fluid (inject variables + data)

  2. Load the layout template (if one is assigned)

  3. Replace [BODY] inside the layout with the rendered content

This produces the final HTML email.

5. Editing, Previewing & Testing

5.1 Inline Editor

Templates are edited inside a code-friendly text editor with syntax highlighting.

5.2 Live Preview

Below the editor is a dynamic preview panel that:

  • Renders the template with sample data

  • Automatically updates when fields change

  • Shows the final email as recipients will see it

5.3 Send Test Email

A “Send Test” button lets you send the rendered email to any address.

This helps verify:

  • Layout rendering

  • Dynamic data correctness

  • Styling consistency

  • Mail client rendering issues

6. Event-Based Email Sending (Upcoming Feature)

A major extension planned for the system is event-driven email dispatch.

Each email template will be tied to an EventKey, such as:

  • User.SignedUp

  • Billing.InvoicePaid

  • Security.PasswordChanged

  • Chat.NewMessage

Flow:

  1. Backend raises an event

  2. System finds the corresponding template

  3. Data is assembled

  4. Rendering occurs (template + layout)

  5. Message is pushed to Hangfire

  6. Hangfire handles actual delivery & retries

This enables:

  • Fully customizable system emails

  • Tenant-specific overrides

  • Template versioning

  • Consistent branding across all modules

7. Why We Use Fluid

Fluid was chosen because it:

  • Is fast and suitable for runtime rendering

  • Supports Liquid syntax, which is understandable by non-developers

  • Prevents unsafe operations (sandboxed environment)

  • Has strong, well-maintained .NET integration

  • Allows custom filters and extensions when needed

It offers enough flexibility while keeping rendering predictable and secure.

8. Best Practices

Keep logic minimal

Let backend code prepare data; keep templates focused on presentation.

Use layouts for branding

Avoid duplicating headers/footers in multiple templates.

Keep variables predictable

Document expected parameters for each template so editors know what to use.

Test frequently

Use the preview and test-send tools to avoid surprises in production.

9. Troubleshooting

Problem: Variable “does not exist”

Cause: Backend didn’t supply it.
Fix: Check the data model passed to FluidTemplateRenderer.

Problem: Layout wraps twice

Cause: Template accidentally includes its own wrapper.
Fix: Remove outer HTML from the template; layouts handle that.

Problem: Missing [BODY] in layout

Cause: Layout invalid.
Fix: Ensure the placeholder exists exactly once.

10. Summary

The ChatApp Email Template System is designed to be:

  • Powerful

  • Safe

  • Easy for non-developers

  • Flexible enough for all communication workflows

Using Fluid templates, layout wrappers, live preview, test sends, and event-based dispatching, the system supports a full pipeline for dynamic, branded email communication.