Email Templates

What It Is

An email template is Jetstack's reusable email body definition. It stores:

  • a template name
  • a layout file
  • a header block
  • a content block
  • an active flag

At runtime, Jetstack turns the template into a tenant-side Latte file and uses that file when an email is rendered by automations or internal email APIs.

Why It Matters

Email templates separate message presentation from message delivery logic.

That matters because the same outbound email usually has two different concerns:

  • workflow logic: who receives the email, when it is sent, what the subject is, and which variables are passed in
  • presentation: what the email looks like and how the message body is structured

Email templates own the second part.

Use them when:

  • one business process sends emails repeatedly
  • branding and structure should remain consistent
  • several automations should reuse the same message layout
  • rollout should allow preparing a template before it is activated

How To Read This Chapter

The Email Template resource has a small configuration surface, but each field matters because it affects how the final email file is assembled.

This chapter explains:

  • what each template field means
  • how it can be configured
  • how the template is rendered at runtime
  • what belongs in the template versus what belongs in the calling automation

Use this chapter together with:

Mental Model

Keep these distinctions clear:

  • the email template defines the reusable body structure
  • the calling automation or API call usually defines:
    • subject
    • recipients
    • sender
    • reply-to
    • variables passed into rendering
    • whether sending happens immediately or through cron-capable delivery

This is one of the most important implementation boundaries:

  • email templates are not full outbound-message definitions
  • they are renderable body templates used by a broader sending flow

Configuration Options

template_name

What it is:

  • the main administrative name of the email template

How to configure it:

  • enter a stable, recognizable name such as:
    • Invitation
    • Password Reset
    • Approval Request
    • Invoice Reminder
    • Daily Digest

Why it matters:

  • this is the title-role field for the Email Template resource
  • it is the label shown when automations or other builder surfaces ask you to choose a template
  • it should help implementers understand the template's purpose immediately

Use it when:

  • the template needs a clear reusable identity in builder lists and automation selectors

Good naming guidance:

  • name templates after the process they support, not only after tone or styling
  • prefer User Account Activation over Welcome Mail

layout_file

What it is:

  • the Latte layout file used as the outer shell for the email

How to configure it:

  • choose a valid layout file from the layout-file picker
  • in most implementations, keep the default unless the tenant needs a distinct email shell

Default behavior:

  • the default value points to the platform's @email layout resolved for the current locale

Why it matters:

  • this file provides the outer email structure
  • the template's header and content fields are injected into blocks inside that layout

In practice, the runtime assembles the final renderable file like this:

  • {layout ROOT_DIR . '/<layout_file>'}
  • {block header}...{/block}
  • {block content}...

This means layout_file controls:

  • the overall HTML wrapper
  • branding shell behavior
  • email-wide structure such as logo area, container, footer, and background styling

Use it when:

  • the tenant has one standard email shell
  • several templates should share consistent visual branding
  • a special class of emails needs a different shell than the standard one

Be careful:

  • layout_file should point to a stable, valid Latte layout
  • changing the layout file affects every header and content block rendered through this template

What it is:

  • the value rendered into the layout's header block

How to configure it:

  • enter the short primary heading of the email
  • keep it concise and immediately informative

Typical examples:

  • Welcome to the platform
  • Reset your password
  • Approval requested
  • Your verification code

Why it matters:

  • the default email layout renders header prominently near the top of the message body
  • it acts as the visual headline of the email

Use it when:

  • the recipient should understand the email purpose before reading the main content

Writing guidance:

  • prefer a clear action or state headline
  • avoid putting the full message into the header
  • think of it as the email's in-body title, not the SMTP subject line

Important distinction:

  • header is not the email subject
  • the subject is set by the automation or API call that sends the email

content

What it is:

  • the main body content of the template

How to configure it:

  • enter the email body in the rich-text field
  • use it for the primary message, instructions, links, and body-level formatting

Why it matters:

  • this is the main reusable content block inserted into the layout's content block
  • it carries the actual message users read after the heading

Use it when:

  • the email needs explanatory text
  • links, next steps, or call-to-action copy should appear in the message body
  • the template should be reused by one or more sending automations

Practical guidance:

  • keep content focused on the recipient action or information goal
  • if variables are passed from an automation, use them carefully and consistently
  • prefer reusable copy over one-off overly specialized text when the template is meant to serve a process family

Important runtime note:

  • the template content is written into a generated tenant Latte file
  • some unsafe Latte execution tags such as {do and {php are neutralized during generation

This means:

  • the template is meant to be a safe renderable message body, not an unrestricted code execution surface

is_active

What it is:

  • the activation flag for the template

How to configure it:

  • enable it when the template is ready for use in live sending flows
  • disable it when the template is still being prepared, reviewed, or retired

Why it matters:

  • the send-email automation explicitly checks this flag before sending
  • if the selected template is inactive, the automation throws an error and does not send the email

This makes is_active a real rollout control, not just a label.

Use it when:

  • preparing a new email flow before launch
  • temporarily suspending a message template without deleting it
  • keeping an old template for reference while preventing further use

Practical caution:

  • the field does not rename or replace old templates automatically
  • if a process should move to a new template, you still need to update the automations or integrations that point to it

What The Template Does Not Configure

Several important outbound-email settings do not live in the Email Template resource itself.

These are usually configured by the calling automation or email API path:

  • subject
  • from
  • reply-to
  • recipients
  • attachments
  • template variables
  • send timing

This boundary is important in practice.

Example:

  • the template defines the body for Approval Request
  • the automation decides:
    • who receives it
    • what subject is used
    • which approval link variables are injected
    • whether the mail is sent immediately

Rendering Model

When Jetstack needs to use an email template, it performs a renderable-file workflow.

In simplified terms:

  1. resolve the template
  2. resolve the selected layout_file
  3. generate a tenant file under TENANT_DIR/emailTemplates/<templateId>.latte
  4. inject the template's header and content into that generated file
  5. render the final email HTML through Latte sandbox mode

Why this matters:

  • the email template is not sent directly from database fields
  • it becomes a real tenant-side Latte file used by the mail renderer

This also explains why:

  • the layout file matters so much
  • updates to the template are reflected through the generated renderable file

Layout File Versus Template Body

This distinction is worth being very explicit about.

The Layout File Owns

  • outer HTML shell
  • page container
  • logo/header shell
  • footer shell
  • global email styling decisions

The Template Owns

  • body heading through header
  • body content through content

Use this separation when:

  • branding should stay consistent across many emails
  • message content should vary without duplicating the full email HTML shell

Working With Variables

Email templates are usually rendered with variables passed in from the caller.

In the send-email automation path, the selected template is rendered with the vars payload supplied by the automation step.

This means:

  • the template should assume a contract with the sending flow
  • the automation and template should agree on variable names and meaning

Use variables when:

  • recipient-specific data must appear in the email
  • links, tokens, names, or business-specific values need to be injected

Best practice:

  • keep the variable contract stable
  • if several automations share one template, document or standardize the expected variables

Common Email Template Patterns

Transactional Message Template

Use for:

  • password reset
  • verification code
  • magic link
  • account activation

Recommended shape:

  • short clear header
  • concise content
  • standard shared layout_file
  • is_active = true only after end-to-end testing

Workflow Notification Template

Use for:

  • approval requests
  • assignment notices
  • escalation notifications
  • status-change alerts

Recommended shape:

  • business-action-oriented header
  • content that clearly states what happened and what should happen next

Digest Or Summary Template

Use for:

  • daily digest
  • manager summary
  • scheduled report email

Recommended shape:

  • strong heading
  • predictable body sections
  • variable contract aligned with the automation producing the digest data

Design Questions To Ask Before Finalizing A Template

  • Should this email share the standard tenant email layout, or does it need a special shell?
  • Is the body truly reusable, or is it too specialized for a shared template?
  • Is the header acting as a clear message headline?
  • Is activation part of rollout control for this process?
  • Which values are expected to be injected by the calling automation?

Best Practices

  • Keep email templates focused on presentation, not workflow control.
  • Use one stable layout_file for consistent branding unless there is a real need for a separate shell.
  • Treat header as the in-body title, not the SMTP subject.
  • Activate templates only after testing the full automation-variable contract.
  • Keep template names process-oriented and easy to identify from automation selectors.
  • Prefer reusable message structures over one-off narrowly tailored templates when the business process is shared.
Previous← CanvasesNextModules →