Templates Introduction

Templates are reusable email designs that separate your content from your code. Instead of building HTML in your application, design your emails in Lettr and send them by referencing a template slug.

Why Use Templates?

Benefit	Description
Separation of concerns	Designers update emails without code changes
Consistency	Maintain brand standards across all emails
Version control	Track changes and rollback when needed
Visual editing	Design emails with drag-and-drop tools
Reusability	Use the same template for multiple sends

Quick Start

Create a Template

Go to Emails in your dashboard and click New Email.

Design Your Email

Use the visual editor to design your email, or paste custom HTML.

Add Variables

Insert dynamic content using {{variable_name}} syntax.

Save and Send

Save your template and send emails using its slug.

Try it in the app

Follow an interactive walkthrough of this guide inside Lettr.

Sending with Templates

Reference templates by their slug when sending:

curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@example.com",
    "to": ["recipient@example.com"],
    "subject": "Welcome to Acme",
    "template_slug": "welcome-email",
    "substitution_data": {
      "name": "John",
      "company": "Acme Inc"
    }
  }'

Specifying a Template Version

By default, Lettr uses the active version of the template. To use a specific version:

curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@example.com",
    "to": ["recipient@example.com"],
    "subject": "Newsletter",
    "template_slug": "monthly-newsletter",
    "template_version": 3
  }'

Project-Scoped Templates

If your template is in a specific project, include the project_id:

curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@example.com",
    "to": ["recipient@example.com"],
    "subject": "Welcome",
    "template_slug": "welcome",
    "project_id": 123
  }'

If no project_id is specified, Lettr uses your team’s default project. Make sure a default project is configured in your team settings, or the API will return a 404 error.

Template vs Inline Content

Choose the approach that fits your use case:

Feature	Template	Inline HTML
Reusability	High—use across multiple sends	Low—embedded in each request
Maintenance	Update once, affects all sends	Update in each integration point
Version control	Built-in versioning	Manual management required
Design tools	Visual editor support	Code only
Best for	Recurring emails, campaigns	One-off or highly dynamic content

Content Priority

When both a template and inline content are provided in the same request:

Template content takes precedence—the template version’s HTML replaces any html parameter
The subject in your request is always used—templates do not provide a fallback subject
Inline html or text is only used when no template_slug is provided

curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@example.com",
    "to": ["recipient@example.com"],
    "subject": "Custom Subject",
    "template_slug": "welcome-email",
    "html": "<p>This HTML is ignored when template_slug is provided</p>"
  }'

If you provide both template_slug and html, the template HTML will be used. The inline HTML is not a fallback—it is ignored entirely.

Template Organization

Lettr provides a hierarchical system to organize templates:

Team
└── Project
    └── Folder
        └── Template
            └── Versions

Projects: Separate templates by brand, product, or team
Folders: Group related templates within projects
Versions: Track changes and control which version is active

Key Features

Visual Editor

Design emails with Topol’s drag-and-drop editor

Projects & Folders

Organize templates with projects and folders

Template Versions

Manage versions and schedule publishing

Saved Blocks

Create reusable sections and synced content

Loop Blocks

Display repeating content like product lists and order items

Template Language

Personalize emails with merge tags and dynamic content

Template Slugs

Each template has a unique slug used to reference it in API calls:

Slug	Use Case
`welcome-email`	New user onboarding
`password-reset`	Security notifications
`order-confirmation`	E-commerce receipts
`weekly-digest`	Recurring newsletters

Slugs are auto-generated from template names but can be customized. They must be unique within a project.

Visual vs Code Editing

Lettr supports two editing modes:

Visual Editor (Topol)

Drag-and-drop interface
Pre-built content blocks
Responsive design tools
No HTML knowledge required

Custom HTML

Full control over markup
Import existing templates
Advanced customization
Direct code editing

Each template has an editor_type field (topol or custom_html) that reflects which editing mode is active. You can switch between modes or use both—design visually and fine-tune with code.

Template Parameters Reference

When sending with templates, these parameters control template behavior:

Parameter	Type	Required	Description
`template_slug`	string	No*	Template identifier (slug name)
`template_version`	integer	No	Specific version number (uses active version if omitted)
`project_id`	integer	No	Project containing the template (uses default project if omitted)
`substitution_data`	object	No	Key-value pairs for template variable substitution. All values must be strings.
`metadata`	object	No	Key-value data passed to webhooks (not used in templates). All values must be strings.

*Required if not providing html or text content directly.

substitution_data is used to populate merge tags in your template (like {{name}}). metadata is passed through to webhooks for tracking but is not rendered in the email content.

Template API

List and retrieve templates programmatically. The list endpoint supports pagination with per_page (default 25, max 100) and page query parameters:

# List all templates (with optional pagination)
curl "https://app.lettr.com/api/templates?per_page=10&page=1" \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"

Response:

{
  "message": "Templates retrieved successfully.",
  "data": {
    "templates": [
      {
        "id": 1,
        "name": "Welcome Email",
        "slug": "welcome-email",
        "project_id": 5,
        "folder_id": 10,
        "created_at": "2026-01-15T10:00:00+00:00",
        "updated_at": "2026-01-20T14:30:00+00:00"
      }
    ],
    "pagination": {
      "total": 42,
      "per_page": 10,
      "current_page": 1,
      "last_page": 5
    }
  }
}

Get a specific template by slug:

curl https://app.lettr.com/api/templates/welcome-email \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"

Response:

{
  "message": "Template retrieved successfully.",
  "data": {
    "id": 1,
    "name": "Welcome Email",
    "slug": "welcome-email",
    "project_id": 5,
    "folder_id": 10,
    "active_version": 1,
    "versions_count": 3,
    "html": "<html>...</html>",
    "json": "{...}",
    "created_at": "2026-01-15T10:00:00+00:00",
    "updated_at": "2026-01-20T14:30:00+00:00"
  }
}

You can scope both endpoints to a specific project by adding ?project_id=123. If omitted, your team’s default project is used.

Best Practices

Use meaningful slugs: order-confirmation is better than template-1
Organize early: Set up projects and folders before creating many templates
Version before changes: Create a version before major redesigns
Use synced blocks: Share headers and footers across templates
Test thoroughly: Send test emails before activating new versions

Template Language

Merge tags, conditionals, and loops

Storage Domains

Host template images on your domain

Integrations

Use templates with Stripe, Supabase, WordPress

Documentation

Quickstart

Learn

Integrations

Resources

Templates Introduction

Why Use Templates?

Quick Start

Try it in the app

Sending with Templates

Specifying a Template Version

Project-Scoped Templates

Template vs Inline Content

Content Priority

Template Organization

Key Features

Visual Editor

Projects & Folders

Template Versions

Saved Blocks

Loop Blocks

Template Language

Template Slugs

Visual vs Code Editing

Visual Editor (Topol)

Custom HTML

Template Parameters Reference

Template API

Best Practices

Template Language

Storage Domains

Integrations

​Why Use Templates?

​Quick Start

Try it in the app

​Sending with Templates

​Specifying a Template Version

​Project-Scoped Templates

​Template vs Inline Content

​Content Priority

​Template Organization

​Key Features

Visual Editor

Projects & Folders

Template Versions

Saved Blocks

Loop Blocks

Template Language

​Template Slugs

​Visual vs Code Editing

​Visual Editor (Topol)

​Custom HTML

​Template Parameters Reference

​Template API

​Best Practices

​Related Topics

Template Language

Storage Domains

Integrations

Why Use Templates?

Quick Start

Sending with Templates

Specifying a Template Version

Project-Scoped Templates

Template vs Inline Content

Content Priority

Template Organization

Key Features

Template Slugs

Visual vs Code Editing

Visual Editor (Topol)

Custom HTML

Template Parameters Reference

Template API

Best Practices

Related Topics