--- title: Mail description: Ship WinterCMS-style mail templates in a plugin, send them through postcard, and deliver them with the memory, log or SMTP driver. section: services order: 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](../../modules/postcard/README.md) 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](#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](#branding). ### CSS inlining Many mail clients drop a style block, so postcard also copies the CSS onto the elements it styles, as WinterCMS does: after the layout has rendered, every rule of the HTML's style elements is written into the `style` attribute of the elements it matches (with go-premailer), and CSS widths and heights also become `width` and `height` attributes. Classes stay on the elements. Rules that cannot be inlined, such as media queries and `:hover`, stay in a style element in the head; the style block holds only those afterwards. The preview, the test send and real mail are inlined the same way, and the plain-text part is never touched. A layout keeps its CSS in the style block only when it opts out: a layout file with `disable_auto_inline_css = true` in its header (`1` and `yes` also work), or a layout edited in the admin with **Do not inline CSS** switched on (its CSS tab). The built-in layouts all inline. The safety checks run on the message before inlining, whether or not the layout opts out. If the inliner fails on a message, or its result fails the safety checks, that message is sent with its style block only and a warning is logged; mail is never stopped by it. ## 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: ```text name = "Note" == NOTE: {{ .text }} ==
{{ .text }}
``` 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: ```text {{ 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. | | `header` | `logo` (an image URL), `body` (a name), `url` (optional link) | A table row for a layout's header: the logo, with the name as its alternative text, or the name when there is no logo. | | `footer` | `text` or `body` | A table row for a layout's footer; `text` is printed as it is (escaped), `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` | WinterCMS's default layout: a header with the Branding logo (or the site name when no logo is set), the message on a white card, and a footer with the copyright year and the site name. Used when the template names no layout. | | `system` | WinterCMS's system layout: the same header and footer as `default`, the message on a padded white card, then a note that it was sent automatically. | | `minimal` | The message directly in the page body, with the Branding logo above it when one is set. | A plugin's own alias wins over `system` and `minimal`; `default` cannot be redefined. Every layout gets these values besides `{{ .Content }}`: `{{ .Subject }}`, the CSS slots `{{ .brandCss }}` and `{{ .css }}`, `{{ .logoUrl }}` (see [Branding](#branding)), `{{ .siteName }}`, the site name, and `{{ .year }}`, the current year. The default and system layouts use the `header` and `footer` partials with them; the footer reads `© `, or `© ` when there is no name, passed as the footer's `text`, so the site name is printed as typed, never as Markdown, and the header row is left out when there is neither a logo nor a name. ## 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 }}`: ```text {{ if .logoUrl }}{{ end }} ``` The settings also hold a site name, given to layouts as `{{ .siteName }}`. The built-in layouts show it in the header (as the logo's alternative text when there is a logo) and in the footer. Left empty, the display name of `mail.from` is used (`Acme` for `Acme `), so mail from an application that never saved Branding still carries a name. A site name mail could not show safely is refused when the settings are saved: one holding a `javascript:`, `vbscript:` or `data:` address. Ordinary text with a colon, such as `Big Data: Summit`, and text such as `Online=Shop` or `onclick=` are accepted: the layouts print the name as escaped text. A name stored before this check, or a `mail.from` display name of that kind, is left out of mail at send time (the next name in line is used, or none), with a warning in the log; the message is still sent. 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](storage.md#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. ```text 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](../../modules/postcard/README.md) 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: ```go src=modules/postcard/example_test.go#ExampleMailer_Send // 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, `

Hi Ada`)) // 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: the caller passes the full name. A per-language version of a template is a file named after the template, a dash and the locale (`welcome-en.htm`, sent as `acme.blog::mail.welcome-en`). A name with its own file always renders that file. A name the catalog does not hold, of the form `