Skip to main content
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?

BenefitDescription
Separation of concernsDesigners update emails without code changes
ConsistencyMaintain brand standards across all emails
Version controlTrack changes and rollback when needed
Visual editingDesign emails with drag-and-drop tools
ReusabilityUse the same template for multiple sends

​
Quick Start

1

Create a Template

Go to Emails in your dashboard and click New Email.
2

Design Your Email

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

Add Variables

Insert dynamic content using {{variable_name}} syntax.
4

Save and Send

Save your template and send emails using its slug.

​
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:
FeatureTemplateInline HTML
ReusabilityHigh—use across multiple sendsLow—embedded in each request
MaintenanceUpdate once, affects all sendsUpdate in each integration point
Version controlBuilt-in versioningManual management required
Design toolsVisual editor supportCode only
Best forRecurring emails, campaignsOne-off or highly dynamic content

​
Content Priority

When both a template and inline content are provided in the same request:
  1. Template content takes precedence—the template version’s HTML replaces any html parameter
  2. The subject in your request is always used—templates do not provide a fallback subject
  3. 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:
SlugUse Case
welcome-emailNew user onboarding
password-resetSecurity notifications
order-confirmationE-commerce receipts
weekly-digestRecurring 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:
ParameterTypeRequiredDescription
template_slugstringNo*Template identifier (slug name)
template_versionintegerNoSpecific version number (uses active version if omitted)
project_idintegerNoProject containing the template (uses default project if omitted)
substitution_dataobjectNoKey-value pairs for template variable substitution. All values must be strings.
metadataobjectNoKey-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

  1. Use meaningful slugs: order-confirmation is better than template-1
  2. Organize early: Set up projects and folders before creating many templates
  3. Version before changes: Create a version before major redesigns
  4. Use synced blocks: Share headers and footers across templates
  5. 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