Files
summercms/modules/postcard
Jakub Zych 7e5d2c74af feat(postcard): database overrides for mail templates with file fallback
- postcard owns the system_mail_* tables (postcard.Migrations), run by lagoon
  as the framework set summercms.postcard after system_files
- Send asks an OverrideSource once per message; NewDBSource reads the
  customized template row through the *gorm.DB published on the app
- a failed lookup, missing tables or an override that does not render or
  fails the safety checks sends the file version and is logged
- the caller's Message.Subject still wins; Mailer, Message, NewMailer,
  Catalog.Register and BootPlugin keep their signatures

Plan 35-01, task 2 (tracer).
2026-11-13 10:26:10 +01:00
..

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 <plugin>::mail.<name> and loaded from views/mail/<name>.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:

subject = "Welcome, {{ .name }}"
description = "Sent after registration"
==
Hi **{{ .name }}**, thanks for joining the blog.

and sends it through the mailer the runtime published:

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:

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:

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 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.
mail:
  driver: smtp
  from: blog@example.com
  smtp:
    host: smtp.example.com
    port: 587
    username: blog
    password: <secret>
    tls: mandatory

Dependencies

  • SummerCMS modules: backpack, compass, diary (component logger postcard when the app publishes no logger), pact.
  • 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

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.