--- 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). ## 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` | `body` | A table row for a layout's footer; 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` | 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 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. 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 layout uses the `header` and `footer` partials with them; the footer reads `© `, or `© ` when there is no name, 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 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 `