# postcard Transactional mail from plugin-owned Markdown templates and layouts, delivered through a memory, log or SMTP driver. `import "git.golem15.com/golem15/summercms/modules/postcard"` **Name:** What you send home in summer; it delivers the application's mail. ## Overview postcard is the mail layer of SummerCMS. Plugins that implement `pact.HasMailTemplates` ship WinterCMS-shaped mail files under `views/mail/`; at boot, `postcard.Activate` publishes one app-scoped `postcard.Mailer` built from the compass `mail.*` config, and `postcard.BootPlugin` registers each plugin's templates and layouts as the plugin boots. Callers then send a template by its dotted name with a map of variables. postcard also owns the mail tables that hold administrators' edits: when a template has a customized row, the mailer sends that override, and the plugin's file otherwise. It is the counterpart of WinterCMS's `Mail::send` with `views/mail/*.htm` templates and mail layouts. ## Role in the framework A service module on `backpack`, `compass` and `pact`; `party` registers the templates plugins contribute, and `lagoon` runs `postcard.Migrations` with the framework's other migrations. postcard does not import `lagoon`: it finds the database through `backpack`. It is separate so mail rendering and delivery can be tested and swapped (memory, log, SMTP) without touching the code that sends. Use cases: - Send account mail (welcome, password reset) from Markdown templates owned by the plugin. - Share one branded layout across all of an application's mail. - Capture sent mail in memory in tests, or log it in development instead of delivering it. ## Features - Templates named `::mail.` and loaded from `views/mail/.htm` (dots become directories). A plugin may only register names in its own namespace; missing files, duplicates and unknown layout aliases fail at boot. - WinterCMS file format: an INI header (`subject`, `layout`, `description`), a `==` separator, then a Markdown body rendered with Go `html/template` variables such as `{{ .name }}`. - Layouts with a header, a text wrapper and an HTML wrapper, referenced from templates by a short alias (`pact.HasMailTemplates` maps aliases to full names). A neutral default layout is built in. - Every message gets an HTML part (Markdown converted with goldmark) and a plain-text part. `mail.css` and `mail.brandCss` are inlined into the layout's style block. - Safety checks: rendered HTML with script, iframe, object or embed tags, inline event handlers or `javascript:`/`vbscript:`/`data:` URLs is rejected; CR/LF in the subject or address headers is rejected; addresses are parsed with `net/mail`. - Drivers behind the `postcard.Driver` interface: `postcard.MemoryDriver` (keeps messages for tests), `postcard.LogDriver` (logs headers and the text part through `log/slog`, never the HTML or credentials), `postcard.SMTPDriver` (go-mail with an explicit TLS policy) and `postcard.FailDriver` (a deterministic failure for tests). - Database overrides: a customized row of `system_mail_templates` replaces a template's subject, body and layout. The mailer reads it on every send, with no cache, in every process that publishes a `*gorm.DB`. A missing database, tables that are not migrated yet, or an override that does not render or fails the safety checks sends the file version. - No locale selection: callers pass the full template name, including any locale suffix. ## Usage A plugin ships `views/mail/welcome.htm`: ```text subject = "Welcome, {{ .name }}" description = "Sent after registration" == Hi **{{ .name }}**, thanks for joining the blog. ``` and sends it through the mailer the runtime published: ```go package blog import ( "context" "errors" "git.golem15.com/golem15/summercms/modules/backpack" "git.golem15.com/golem15/summercms/modules/postcard" ) func SendWelcome(ctx context.Context, app *backpack.App, email, name string) error { mailer, ok := app.Lookup[postcard.Mailer]() if !ok { return errors.New("mailer not published") } return mailer.Send(ctx, postcard.Message{ Template: "acme.blog::mail.welcome", To: []string{email}, Vars: map[string]any{"name": name}, }) } ``` In tests, build the catalog and mailer directly and inspect what was sent: ```go package blog import ( "context" "testing" "testing/fstest" "git.golem15.com/golem15/summercms/modules/postcard" ) func TestWelcomeMail(t *testing.T) { mailFS := fstest.MapFS{"views/mail/welcome.htm": {Data: []byte("subject = \"Welcome, {{ .name }}\"\n==\nHi **{{ .name }}**.\n")}} cat := postcard.NewCatalog() if err := cat.Register("acme.blog", mailFS, []string{"acme.blog::mail.welcome"}, nil); err != nil { t.Fatal(err) } driver := postcard.NewMemoryDriver() mailer := postcard.NewMailer(cat, driver, postcard.Options{From: "blog@example.com"}) msg := postcard.Message{Template: "acme.blog::mail.welcome", To: []string{"ada@example.com"}, Vars: map[string]any{"name": "Ada"}} if err := mailer.Send(context.Background(), msg); err != nil { t.Fatal(err) } if got := driver.Messages()[0].Subject; got != "Welcome, Ada" { t.Fatalf("subject = %q", got) } } ``` ### Overrides from the admin postcard owns the tables `system_mail_templates`, `system_mail_layouts`, `system_mail_partials`, `system_mail_brand_settings` and `system_mail_image_library` (`postcard.Migrations`). A row of `system_mail_templates` with `is_custom` set is an override of the template named in its `code`: its `subject` and `body` replace the file's, and the row its `layout_id` points at names the layout. The body has the same format as in the file, Markdown with Go template variables. `postcard.Activate` gives the mailer the source `postcard.NewDBSource` returns. On every `Send` the mailer asks it once for the template being sent; nothing is cached, so an edit applies to the next message in every process that shares the database, including a worker that never loads the admin. The subject is taken from the first of these that is set: 1. `postcard.Message.Subject`, the caller's subject; 2. the override's subject; 3. the file's subject. An override never stops mail: - With no `*gorm.DB` published, the file version is sent. - When the lookup fails (no connection, or the tables are not migrated yet), the file version is sent and a warning is logged, at most once a minute per distinct error. - When the override does not parse, fails while rendering (for example it uses a field of a variable the caller does not pass) or fails the safety checks, the error is logged as `postcard: override failed, sending the file version` with the template name, and the file version is sent. - When the override's layout no longer exists, the message is rendered in the default layout and a warning is logged. `postcard.NewMailer` takes a source through `postcard.Options.Overrides`; any `postcard.OverrideSource` works, which is how a test supplies overrides without a database: ```go package blog import ( "context" "git.golem15.com/golem15/summercms/modules/postcard" ) // fixedOverrides overrides one template with a fixed subject and body. type fixedOverrides struct{} func (fixedOverrides) MailOverrides(_ context.Context, template string) (postcard.Overrides, error) { if template != "acme.blog::mail.welcome" { return postcard.Overrides{}, nil } return postcard.Overrides{Template: &postcard.TemplateOverride{ Subject: "Hello, {{ .name }}", Body: "Good to see you, **{{ .name }}**.", }}, nil } func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Mailer { return postcard.NewMailer(cat, driver, postcard.Options{Overrides: fixedOverrides{}}) } ``` ## API reference | Identifier | Description | |------------|-------------| | `postcard.Activate` | Builds the driver from config and publishes the app-scoped `postcard.Mailer` before plugins boot. The mailer reads overrides through `postcard.NewDBSource`. | | `postcard.BootPlugin` | Registers a booting plugin's declared templates and layouts with the published mailer. | | `postcard.Mailer` | Sends a registered template through the configured driver. | | `postcard.NewMailer` | Builds a mailer from a catalog, a driver and `postcard.Options`. | | `postcard.Message` | What callers send: template name, recipients, reply-to, variables and an optional subject override. | | `postcard.Options` | Mailer settings: sender address, CSS, brand CSS and, in `postcard.Options.Overrides`, the source of database overrides (nil sends the file versions). | | `postcard.Catalog` | Registered templates and layouts, including the built-in default layout. | | `postcard.NewCatalog` | Returns a catalog holding only the default layout. | | `postcard.Catalog.Register` | Loads a plugin's templates and layout aliases from an `fs.FS`. | | `postcard.Driver` | Delivers a `postcard.RenderedMessage`. | | `postcard.RenderedMessage` | The validated payload a driver transmits: headers, HTML part and text part. | | `postcard.NewMemoryDriver` | In-memory driver; `postcard.MemoryDriver.Messages` returns what was sent. | | `postcard.NewLogDriver` | Driver that logs through a `*slog.Logger` (the postcard component logger when nil). | | `postcard.NewSMTPDriver` | SMTP driver built from a `postcard.SMTPConfig`. | | `postcard.SMTPConfig` | Host, port, credentials, TLS policy and timeout for the SMTP driver. | | `postcard.FailDriver` | Driver whose `postcard.FailDriver.Send` always returns `postcard.FailDriver.Err`. | | `postcard.OverrideSource` | Supplies the database overrides of one render. `postcard.OverrideSource.MailOverrides` takes the template name; an empty name asks for everything except a template override. | | `postcard.Overrides` | What a source returns: the template override in `postcard.Overrides.Template` (nil when there is none), layout content by code in `postcard.Overrides.Layouts` and partial content by name in `postcard.Overrides.Partials`. | | `postcard.TemplateOverride` | A template's customized subject, body and layout code. An empty `postcard.TemplateOverride.Layout` keeps the file's layout. | | `postcard.LayoutOverride` | A layout's name, HTML wrapper, text wrapper and CSS as stored in the database. | | `postcard.PartialOverride` | A partial's HTML and text sections as stored in the database. | | `postcard.NewDBSource` | The source over postcard's tables. It looks the `*gorm.DB` up on the app at every call and returns no overrides when none is published. | | `postcard.Migrations` | The gormigrate set that creates the mail tables; lagoon runs it under the `summercms.postcard` history. | | `postcard.TemplatesTable`, `postcard.LayoutsTable`, `postcard.PartialsTable`, `postcard.BrandTable`, `postcard.ImageLibraryTable` | The names of the mail tables, for code that defines models over them. | ## Configuration `postcard.Activate` reads these keys from the app's [compass](../compass/README.md) config: | Key | Default | Controls | |-----|---------|----------| | `mail.driver` | `memory` | Delivery driver: `memory`, `log` or `smtp`. Any other value fails at boot. | | `mail.from` | empty | Sender address. Required by the SMTP driver. | | `mail.css` | empty | CSS inlined into the layout. | | `mail.brandCss` | empty | Brand CSS inlined before `mail.css`. | | `mail.smtp.host` | none | SMTP host. Required when `mail.driver` is `smtp`. | | `mail.smtp.port` | `587` | SMTP port. | | `mail.smtp.username` | empty | SMTP user. When set, PLAIN authentication is used. | | `mail.smtp.password` | empty | SMTP password. | | `mail.smtp.tls` | `mandatory` | TLS policy: `mandatory` (or `tls`), `starttls` (or `opportunistic`), `none` (or `notls`, `off`). Plain connections are never inferred. | | `mail.smtp.timeout` | `10s` | Connection timeout, as a Go duration or a number of seconds. | ```yaml mail: driver: smtp from: blog@example.com smtp: host: smtp.example.com port: 587 username: blog password: tls: mandatory ``` ## Dependencies - SummerCMS modules: [backpack](../backpack/README.md), [compass](../compass/README.md), [diary](../diary/README.md) (component logger `postcard` when the app publishes no logger), [pact](../pact/README.md). - Third-party: `github.com/wneessen/go-mail` (SMTP), `github.com/yuin/goldmark` (Markdown), `gorm.io/gorm` (reading overrides), `github.com/go-gormigrate/gormigrate/v2` (the mail tables' migrations). - Standard library: `bytes`, `context`, `embed`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `strings`, `sync`, `text/template`, `time`. - Tests additionally use `github.com/testcontainers/testcontainers-go` (Mailpit and Postgres containers), `gorm.io/driver/postgres` and `github.com/jackc/pgx/v5`. ## Testing ```sh go test ./modules/postcard/... ``` The SMTP integration test starts a Mailpit container and the override smoke test a Postgres container, both through testcontainers-go, so they need Docker. Run `go test -short ./modules/postcard/...` to skip them; the remaining tests use the memory and fail drivers and need no external services.