Files
summercms/docs/services/mail.md
Jakub Zych 2bf9081c1b feat(postcard): mail branding and the logo URL
- Brand, DefaultBrand and CompileBrandCSS: thirteen colours, each checked
  as a six-digit hex colour, compiled into CSS for plain elements and the
  built-in layouts and partials
- once the branding row exists its compiled CSS replaces mail.brandCss;
  mail.css still follows, and the file version sent after a failing
  override keeps the Branding
- layouts get logoUrl, built per send from storage.uploads.public_url or
  app.url through attach.AbsolutePublicURL; a logo that cannot be shown is
  left out with a rate-limited warning
- Editor previews and validates a Branding draft (rule colour)

Plan 35-01, task 5.
2026-11-13 11:06:43 +01:00

12 KiB

title, description, section, order
title description section order
Mail Ship WinterCMS-style mail templates in a plugin, send them through postcard, and deliver them with the memory, log or SMTP driver. services 70

Mail

WinterCMS plugins ship mail templates in views/mail and send them with Mail::send. SummerCMS keeps the file format and the dotted template names; postcard loads them at boot and sends them through a configured driver.

Templates and layouts

A plugin implements pact.HasMailTemplates: it returns its embedded views/mail files, the template names it ships and short aliases for its layouts. A template named acme.blog::mail.welcome lives in views/mail/welcome.htm (dots in the name become directories), and a plugin may only register names in its own namespace. A missing file, a duplicate name or an unknown layout alias fails the start-up.

The file format is WinterCMS's: an INI header with the subject, the layout alias and a description, a == line, then a Markdown body with Go template variables such as {{ .name }}. A layout has a header, a text wrapper and an HTML wrapper, separated by == lines, each with {{ .Content }} where the message goes. A template without a layout uses the built-in default layout; see Built-in layouts.

Each message gets an HTML part, rendered from the Markdown, and a plain-text part. mail.css and the brand CSS go into the layout's style block; see Branding.

Partials

A partial is a block that several templates and layouts share, such as a button or a footer note. A plugin implements pact.HasMailPartials: it returns its embedded views/mail files and the partial names it ships. A partial named acme.blog::mail.partials.note lives in views/mail/partials/note.htm, and its file has the layout format, with a text section and an HTML section:

name = "Note"
==
NOTE: {{ .text }}
==
<div class="note">{{ .text }}</div>

The name must be in the plugin's namespace and under mail.partials.; otherwise, or when the file is missing or the name is declared twice, the start-up fails. A plugin can ship partials without shipping templates.

A body or a layout calls a partial with its name and pairs of a key and a value:

{{ partial "button" "url" .link "body" "Track the order" "type" "positive" }}

{{ partial "acme.blog::mail.partials.note" "text" .note }}

A bare name is one of the built-in partials; a plugin's partial is called by its full name, from any plugin's mail. The pairs become the partial's variables. The HTML section is used in the HTML part and the text section in the plain-text part.

Built-in partial Arguments Renders
button url, body, type (primary, positive or negative) A link styled as a button.
panel body A highlighted block; the body is Markdown.
table body A Markdown table.
subcopy body Small print under a rule; the body is Markdown.

In a body, write the call on a line of its own with blank lines around it. Bodies are Markdown and raw HTML in them is still dropped; postcard inserts a partial's HTML after the Markdown conversion, through a random token that a variable's value cannot contain. Inside a partial's HTML section, {{ markdown .body }} renders a value as Markdown.

Built-in layouts

Three layouts are available to every plugin's templates without declaring an alias:

layout Renders
default The message in a plain page. Used when the template names no layout.
system WinterCMS's system layout: the message in a centred table, then a note that it was sent automatically.
minimal The message directly in the page body, with the style block only.

A plugin's own alias wins over system and minimal; default cannot be redefined.

Branding

A layout's style block has a brand slot, {{ .brandCss }}, before {{ .css }}. Until the branding settings are saved for the first time, the brand slot holds mail.brandCss from the configuration. From the first save on, it holds CSS that postcard compiles from the saved colours, and mail.brandCss is no longer used. mail.css is applied either way.

The settings are thirteen colours: the page and content backgrounds, the header, footer, heading, text and link colours, the button text and the primary, positive and negative button backgrounds, the panel background and the table border. Each is a six-digit hexadecimal colour such as #2da7c7, and one left empty takes WinterCMS's default. The compiled CSS styles plain elements (the page, links, headings, paragraphs, tables) as well as the built-in layouts and partials, so it shows in any layout that has the style block.

The settings also hold a logo. A layout shows it where it uses {{ .logoUrl }}:

{{ if .logoUrl }}<img src="{{ .logoUrl }}" alt="">{{ end }}

A mail client needs an absolute address, so the logo's URL is built at send time from the configuration: storage.uploads.public_url when it is set, otherwise app.url with storage.uploads.public_path_prefix; see Absolute URLs for mail. Set one of them, or the logo is left out and a warning is logged.

Sample values for previews

A preview of a template has no caller to pass its variables. A template can therefore give sample values in its header, one key per variable: sample. followed by the variable's path, in the variable's own case.

subject = "Your order {{ .order.code }}"
sample.name = "Ada"
sample.order.code = "ZAM-1"
==
Hi {{ .name }}, we received the payment for **{{ .order.code }}** from {{ .company }}.

The keys are optional and sending ignores them. Where a preview finds no sample, it shows the variable's path in square brackets, so the body above previews as "Hi Ada, we received the payment for ZAM-1 from [company]." Nested fields and lists work without samples too: {{ range .order.items }}{{ .description }}{{ end }} previews one item, [order.items.description]. Saving an edited template runs the same render, so an edit that uses a variable the plugin never passes still shows up as a placeholder, not as an error.

Previews, the checks on save and test sends are postcard.Editor; see the postcard README for its API.

Sending

At boot, postcard.Activate publishes one postcard.Mailer on the application, and postcard.BootPlugin registers each plugin's templates as it boots. Look the mailer up with app.Lookup[postcard.Mailer]() and send a postcard.Message with the template name, the recipients and the variables. Tests build the catalog and a memory driver directly, and read back what was sent:

// At boot, postcard.BootPlugin registers what pact.HasMailTemplates
// declares; a test registers the same thing directly.
cat := postcard.NewCatalog()
err := cat.Register("acme.blog", mailFS,
	[]string{"acme.blog::mail.welcome"},
	map[string]string{"blog": "acme.blog::mail.layouts.blog"})
if err != nil {
	fmt.Println(err)
	return
}
driver := postcard.NewMemoryDriver() // mail.driver: memory
mailer := postcard.NewMailer(cat, driver, postcard.Options{From: "blog@example.com"})

err = mailer.Send(context.Background(), postcard.Message{
	Template: "acme.blog::mail.welcome",
	To:       []string{"ada@example.com"},
	Vars:     map[string]any{"name": "Ada"},
})
if err != nil {
	fmt.Println(err)
	return
}
sent := driver.Messages()[0]
fmt.Println(sent.From, sent.To, sent.Subject)
fmt.Println(sent.Text)
fmt.Println(strings.Contains(sent.HTML, `<div class="blog-mail"><p>Hi <strong>Ada</strong>`))

// Header injection is refused before any driver sees the message.
err = mailer.Send(context.Background(), postcard.Message{
	Template: "acme.blog::mail.welcome",
	To:       []string{"ada@example.com\r\nBcc: all@example.com"},
	Vars:     map[string]any{"name": "Ada"},
})
fmt.Println(err != nil, len(driver.Messages()))
// Output:
// blog@example.com [ada@example.com] Welcome, Ada
// Hi **Ada**, thanks for joining the blog.
//
// -- The Acme blog
// true
// true 1

postcard does not pick a locale. For a per-language template, register one name per language (acme.blog::mail.welcome_pl) and pass the full name.

Before a driver sees a message, postcard refuses a subject or address with a line break, parses every address with net/mail, and rejects rendered HTML that contains script, iframe, object or embed tags, inline event handlers, or javascript:, vbscript: or data: URLs. Variables are escaped by Go's html/template.

postcard.Mailer.Send delivers before it returns. To keep a request fast, send from a queued job, and send after the write that triggered the mail has committed; see Queued jobs and Transactions.

Overrides from the admin

A plugin's mail files are the default text. postcard also owns a set of mail tables, created by migrate with the framework's other tables, where an administrator's edit of a template is stored. A row of system_mail_templates with is_custom set overrides the template named in its code: its subject, body and layout replace the file's. The body keeps the file's format, Markdown with Go template variables.

postcard.Mailer.Send reads that row on every send and caches nothing, so an edit applies to the next message in every process that shares the database, a queue:work worker included. The subject is the first of these that is set:

  1. postcard.Message.Subject, when the caller passes one;
  2. the override's subject;
  3. the file's subject.

Layouts and partials have rows too, in system_mail_layouts and system_mail_partials. A customized row replaces the file's wrappers or sections, and a layout row whose code is not a file layout's name is a layout that exists only in the database, which a template override can select. A layout row's CSS goes before mail.css in the layout's style block.

An override cannot stop mail from going out:

  • With no database, or before migrate has created the tables, the file version is sent. A failed lookup is logged as a warning, at most once a minute.
  • An override of the template, its layout or a partial that does not parse, fails while rendering (it uses a field of a variable the caller does not pass, for example) or fails the safety checks is logged as an error with the template name, and the message is sent from the files alone.
  • An override whose layout no longer exists is rendered in the default layout, with a warning.

The log lines carry the component postcard. In a test, pass any postcard.OverrideSource in postcard.Options.Overrides to supply overrides without a database; postcard.NewDBSource is the one postcard.Activate installs.

Drivers

mail.driver selects the driver:

Driver Delivers
memory (default) Nowhere: messages are kept in the process, for tests.
log To the log: headers and the text part, never the HTML part or credentials. For development.
smtp Through an SMTP server with the configured TLS policy.

The SMTP settings go in config/mail.yaml, with the password in the environment (SUMMER_MAIL__SMTP__PASSWORD):

driver: smtp
from: blog@example.com
smtp:
  host: smtp.example.com
  port: 587
  username: blog
  password: <secret>
  tls: mandatory

mail.smtp.tls defaults to mandatory: the connection must upgrade with STARTTLS, and sending fails if the server does not offer it. postcard never infers a plain connection. The other two values exist for local mail catchers only:

  • starttls (or opportunistic) uses TLS when the server offers it and sends in plain text when it does not, so an attacker on the network can strip the upgrade.
  • none sends in plain text.

Warning

Use starttls or none only against a local development mail catcher. In production, keep the default mandatory.