Templates

What Is a Template?

A template is a reusable email design. It contains:

• Structure - Sections, layouts, components
• Content - Text, images, buttons
• Variables - Dynamic placeholders for personalization
• Styling - Colors, fonts, spacing

Templates are rendered with variables to produce final HTML.

Template Document Model

Internally, templates are stored as a document structure:

type EmailDocument = {
  id: string
  name: string
  subject?: string
  sections: Section[]
  styles: DocumentStyles
}

Each section contains content blocks, and blocks can contain text with variables.

Template Components

Sections

Top-level containers that stack vertically:

• Header section
• Content sections
• Footer section

Sections have their own background colors and padding.

Blocks

Content within sections:

• Text - Paragraphs, headings, lists
• Image - With alt text and links
• Button - Call-to-action with URL
• Divider - Horizontal separator
• Spacer - Vertical spacing

Layouts

Multi-column arrangements within sections:

• Single column (default)
• Two columns
• Three columns

Columns automatically stack on mobile.

Template Lifecycle

Create → Edit → Save → Render → Send

1. Create - New template in a project
2. Edit - Build in visual editor
3. Save - Stored in database
4. Render - Hydrate with variables
5. Send - Deliver via provider

Template vs Rendered Email

Subject Lines

Templates can have a subject:

• Set in the template editor
• Can include variables: Your order {{orderNumber}} shipped
• Can be overridden via _subject in API

Subject priority:

1. _subject from API request
2. Template subject
3. Template name (fallback)

Template Storage

Templates are stored per-user:

• Each template belongs to a project
• Projects belong to users
• Templates are identified by unique IDs

Template IDs

Template IDs look like: tmpl_abc123xyz

Use these IDs when:

• Calling the render API
• Calling the execute flow API
• Referencing templates in code

Find template IDs in:

• The URL when editing: /editor/template/tmpl_abc123xyz
• The template settings panel

Template Limits

Template Best Practices

Naming

Use descriptive, consistent names:

• welcome-email
• order-confirmation
• password-reset

Organization

Group related templates in projects:

• Auth - Welcome, verify, reset
• Orders - Confirmation, shipped, delivered
• Notifications - Comment, mention, digest

Versioning

mailshit doesn’t have built-in versioning, but you can:

• Duplicate templates before major changes
• Name versions: welcome-email-v2
• Keep old templates for rollback

Reusability

Design templates to be reusable:

• Use variables for all dynamic content
• Set sensible defaults
• Avoid hardcoded values