The shared HTML layout every email built from a file or a default is wrapped in.

PhoenixKit.Email.Content.resolve/5 calls render/3 on the file/default path, so an email reaches the reader as HTML even when all it has is text: core's auth emails and the defaults a module passes to PhoenixKit.Mailer.send_from_template/4 ship no html part of their own. Content from a database template is never wrapped — it carries its own chrome.

Three parts: layout, header, footer

The layout is the document around the body; the header and footer are rendered on their own and handed to it, so a host can replace just the header without copying the rest:

<host>/priv/phoenix_kit_templates/
├── _layout/html.html      <- the document; must place {{{content}}}
├── _header/html.html      <- placed as {{{header}}}
└── _footer/html.html      <- placed as {{{footer}}}

Each is resolved like any other template (PhoenixKit.Templates): the message's own locale and override roots, html.de.html before html.html. Only the html part is read, and only the variables below are bound — not the message's own, since every email shares these parts.

An empty or whitespace-only _header/_footer file counts as missing. Neither needs a placeholder. A _layout with no content placeholder (an empty file, a typo such as {{{contnet}}}) would drop the body of every email, so it is refused and the next layout in line is used; a warning is logged once per layout name, override roots and locale for the life of the VM.

Groups

A group of emails can have chrome of its own: _layout-<group>, _header-<group>, _footer-<group>. Each falls back on its own — to the shared _layout/_header/_footer, then to core's — so a billing group may replace only its footer. The group is the :group option here; Content.resolve/5 takes it from layout: "<group>" or from the email's own layout.txt. A group name is [a-z0-9-]+; any other is ignored, with a warning.

Core's defaults

default_html/1, default_header_html/1 and default_footer_html/1 are core's own parts, kept in code for the same reason the message defaults are Gettext calls rather than files: core ships no files of its own. They are deliberately neutral — table markup with inline styles, no external resources but the site's own logo — and carry no words of their own, so they need no translation.

• The header shows the logo ({{logo_url}}, from Settings) when there is one, else the site's name.
• The footer shows the site's name and a link to the site.
• The layout is a card with the header, the body and the footer, and a thin bar in the accent colour on top once the email_accent_color setting holds a colour.

Variables

Every part sees:

and the layout also:

site_url is whatever the site is configured with. Core's footer links it only when it is an http(s):// address and prints it as text otherwise.

content, header and footer must be written with three braces. The html part escapes every {{variable}}, which is right for subject and the site's name but would print the body's markup as visible text. Triple braces are the escaping opt-out, and these values are safe to insert raw because they were escaped when they were built.

Opting out

layout: false to Content.resolve/5 or Mailer.send_from_template/4 leaves the message exactly as resolved. An html part that is already a whole document is never wrapped either — an export of an old database template is one. It is a document when, after any byte-order mark, whitespace, <!-- comments --> and <?xml … ?> prolog, it starts with <!doctype or an <html tag (<html>, <html lang="…">), in any case.