--- 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 }} ==
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. 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](jobs.md) and [Transactions](../database/transactions.md).
## 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`):
```yaml
driver: smtp
from: blog@example.com
smtp:
host: smtp.example.com
port: 587
username: blog
password: