diff --git a/docs/services/mail.md b/docs/services/mail.md
index 5ac65288..83156f06 100644
--- a/docs/services/mail.md
+++ b/docs/services/mail.md
@@ -46,6 +46,8 @@ A bare name is one of the built-in partials; a plugin's partial is called by its
| `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.
@@ -55,12 +57,14 @@ Three layouts are available to every plugin's templates without declaring an ali
| `layout` | Renders |
|----------|---------|
-| `default` | The message in a plain page. Used when the template names no layout. |
+| `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.
@@ -73,6 +77,8 @@ The settings also hold a logo. A layout shows it where it uses `{{ .logoUrl }}`:
{{ 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
diff --git a/modules/cabana/README.md b/modules/cabana/README.md
index 63ea8fd6..d0bedeea 100644
--- a/modules/cabana/README.md
+++ b/modules/cabana/README.md
@@ -59,7 +59,7 @@ Use cases:
- Form fields on another plugin's controller: a `pact.AdminActionExtension` with `Form` set to a `pact.AdminFormExtension` places fields and tabs in any admin controller's form by its ID. Its fields document is the `fields.yaml` format plus `before:`/`after:` anchors, `zone:` (only the tab zone for now) and a `tabs:` list, compiled at boot with every `fields.yaml` check; extensions apply in plugin activation order and the form is sent in the compiled order, so the SPA adds no ordering. `Hide` removes owner fields, `Permissions` and `Visible` decide per request who sees the fields (schema, show and save alike), widget fields run the extension's `Actions` and partial fields render from its `Dir` through `PartialData`. Extension values leave the save body before any owner path reads them; `Save` runs in the record's save transaction after the owner row is written (`pact.AdminFormErrors` answers 422, its notices join `meta.notices`) and `Load` serves the values on show. A form no extension lays out compiles unchanged. Unknown anchors, duplicate names, anchor cycles, anchors outside `Requires()`, other zones, `fileupload` fields and clashing widget action or partial names stop the boot naming the plugin, the controller and the name.
- Plugins screen: Settings → System → Plugins opens the admin SPA route `/system/plugins` (the settings entry carries `path` instead of a controller) for administrators holding `cabana.PermissionViewPlugins` (`backend.view_plugins`, granted to no role in code; superusers always pass). GET `/plugins` lists the plugins the application was built with from the `party.Installed` metadata `summer build` bakes (name, description, version, source, module and package), or only the IDs of `party.Activated` for an application built before that metadata existed, with the framework version and the state of the plugin registry (`plugins.registry_url`, read through `kiosk.RegistryURL`). With the registry configured, cabana (never the SPA) looks up each versioned plugin's releases through `kiosk.Client` and marks an update when `kiosk.NewestCompatible` finds a release newer than the installed version by `kiosk.Newer` (a `git describe` string or a pseudo-version compares by the tag it builds on), with the `summer plugin:update ` command; GET `/plugins/marketplace` searches the registry and adds installed and compatibility markers (compatible when `summer plugin:install` can install some release with the built framework, looking up the releases of a plugin whose newest one needs a newer framework; always compatible when the built framework version is not a release) and the `summer plugin:install ` command. Registry calls have a 4 second timeout, at most four run at once, and answers are cached in process (searches 5 minutes, at most 256 distinct searches with expired and then the oldest dropped first, releases 15 minutes, failures 1 minute); a failing registry gives `status` unavailable and never a non-200 answer.
- Administrators screen: when some plugin registers admin controllers, `cabana.Activate` also compiles the admin's own screens, an internal plugin with ID `summercms.cabana`. Settings → System → Administrators (controller `cabana.AdministratorsControllerID`, permission `cabana.PermissionManageUsers`) lists backend administrators with their role and last sign-in, opens a preview of each, where record actions (the admin's own and contributed ones) are offered, and creates and edits administrators: login, email, names, a password (hashed at `admin.password.bcrypt_cost`, at least 4 characters and at most 72 bytes), the role and per-administrator permission overrides. The server enforces the privilege rules in the save transaction: only a superuser sees superusers or sends the superuser switch, an administrator can neither grant permissions or roles above their own grants nor change an administrator who holds more than they do, their own role, superuser flag, permissions and password are not changed here, and the last active superuser cannot be demoted. A password set for another administrator ends their sessions (personal API tokens stay valid, as with `admin:reset-password`). Administrators are activated, deactivated and restored by record and bulk actions and deleted softly through `deleted_at` (never hard-deleted); the list shows deleted and deactivated rows with their row states and filters deleted ones, and the preview shows a status hint. Deactivating or deleting an administrator ends their sessions and stops their personal API tokens; the last active superuser cannot be demoted, deactivated or deleted on any of these paths (a transaction-scoped advisory lock serializes the check). The permission codes `cabana.PermissionManageUsers` and `cabana.PermissionManageRoles` are registered with no role grant, so after an upgrade only superusers see the screens until an administrator grants them. An application without admin controllers still activates no admin.
-- Mail screens (Settings → Mail): when the application publishes postcard's Mailer (`postcard.EditorFrom` succeeds; `party.Activate` runs `postcard.Activate`), the internal plugin also registers the mail screens over postcard's tables, the permission codes `cabana.PermissionManageMailTemplates` (`system.manage_mail_templates`) and `cabana.PermissionManageMailLayouts` (`system.manage_mail_layouts`), both granted to no role in code, and their Settings entries in category `backend::lang.settings.category_mail`. Mail templates (controller `cabana.MailTemplatesControllerID`, model `cabana.MailTemplate`) lists one row per template of this process's catalog (rows of uninstalled plugins are hidden; the row is the template's own, or the lowest locale variant when only variants ship) with code, subject, description, customized locales (`cabana.MailTemplate.CustomizedLocales`: Default and the locale codes of the customized versions, at most three then +N) and layout, and edits the subject, the Markdown body and the layout (a `relation` over `cabana.MailLayout` rows: every database-only layout and the catalog's file layouts). There is no create and no delete. A save marks the row customized, stamps `base_hash` with the file's current hash and `customized_at`, and validates the result through `postcard.Editor.Validate` inside the save's transaction; a `postcard.DraftError` is a 422 on its field with `backend::lang.mail.invalid_` (`:message`, `:name`). The index rows are written by `postcard.SyncIndex` and `postcard.EnsureLocaleRows` through `lagoon.OnDatabase` at activation; a failed sync is logged and retried on the first mail list request of the process, and a list request syncs again when the mail locales changed. The mail locales are the locales the translator's catalog holds plus, when a `cabana.TranslationWriter` is published, its enabled locales; the default locale is the writer's default locale, else the translator's. A template is one record per locale version: its own row (Default), a row per locale variant file (`welcome-en`) and a row per other mail locale that ships no file (`welcome-de`, created by `postcard.EnsureLocaleRows`, showing and sending the default version until it is customized). The update form's locale switcher lists them (`meta.localeVariants`); the record title is the template's base code, and the show response first ensures the template's missing locale rows, so a newly enabled locale can be opened without a restart. A save of a locale without a file stamps `base_hash` with the base file's hash; until it is customized, its form shows the base template's current version (its customization when there is one), and reset returns it to the base file. Mail layouts (`cabana.MailLayoutsControllerID`, model `cabana.MailLayout`) lists postcard's default layout first, then the file layouts and the custom (database-only, `source` NULL, shown as Custom) layouts by name; it creates custom layouts (code `^[a-z0-9-]+$`, free, create-only) and deletes them, refusing one that template rows still reference with a `cabana.ForbiddenError` whose message names the layout and the count (CLDR plural). Mail partials (`cabana.MailPartialsControllerID`, model `cabana.MailPartial`) edits the partials' HTML and text sections. Both need `cabana.PermissionManageMailLayouts`; saves are stamped and validated as templates are. On all three, the record action `reset` (danger, offered on a customized file-backed row) calls `postcard.ResetOverride` in the action's transaction; rows from files are never deleted. The list row states are `customized` (an override) and `outdated` (an override whose `base_hash` differs from the file's `file_hash`), the lists have a status filter (customized, not customized, outdated); on the templates list both apply to the whole template, any of its locale versions. The forms carry the `info` and `file_version` partials: the file (the base template's for a locale without a file), the status, on a template with locale versions the Default line or the line of a locale without a file (`backend::lang.mail.info_locale_default`, `info_locale_fallback`), the sample variables or the partial's call, the drift callout, and a 3-line-context LCS line diff of the serialized override (`postcard.FormatTemplate`, `FormatLayout`, `FormatPartial`) against the file, skipped above 2000 lines per side. The mail controllers declare `recordActions` without a preview block: the admin offers them in the update form's footer, a boot rule only these internal controllers are exempt from. Layout and partial content fields use the built-in `codeeditor` type (`language: html|css|text`, optional `mailImages`); Branding is the settings form `mail_brand` on `cabana.MailBrandSetting` (postcard's brand row, 13 `colorpicker` colours and a `mailimage` logo; the first save switches mail from `mail.brandCss` to the compiled colours). Mail images is the singleton controller `cabana.MailImagesControllerID` (`cabana.MailImageLibrary`) with a public attachMany `images` fileupload; GET/POST `/mail/images` and GET `/mail/images/{id}` return absolute public URLs (`attach.AbsolutePublicURL`) and refuse with `mail.images.no_public_url` when neither `storage.uploads.public_url` nor `app.url` is set. Listing answers either mail permission; upload and the singleton form need `system.manage_mail_layouts`. POST `/mail/preview` renders an unsaved draft (`cabana.AdminMailPreviewRequest`: `mode`, `id`, `values`) through `postcard.Editor.Preview` and answers `cabana.AdminMailPreviewResult` (subject, html, text); mode `template` needs `system.manage_mail_templates`, modes `layout`, `partial` and `branding` need `system.manage_mail_layouts`. POST `/mail/test-send` (interactive sessions only) sends a template, layout or partial draft to the signed-in administrator's own email (`cabana.AdminMailTestSendResult`), refuses recipient keys in the body, and is limited to five sends per administrator per ten minutes through a published `cooler.Attempter` when `serve` has one, otherwise an in-process fixed window (429 with `Retry-After`). Forms carry `mailpreview` fields (`mode` matching the screen).
+- Mail screens (Settings → Mail): when the application publishes postcard's Mailer (`postcard.EditorFrom` succeeds; `party.Activate` runs `postcard.Activate`), the internal plugin also registers the mail screens over postcard's tables, the permission codes `cabana.PermissionManageMailTemplates` (`system.manage_mail_templates`) and `cabana.PermissionManageMailLayouts` (`system.manage_mail_layouts`), both granted to no role in code, and their Settings entries in category `backend::lang.settings.category_mail`. Mail templates (controller `cabana.MailTemplatesControllerID`, model `cabana.MailTemplate`) lists one row per template of this process's catalog (rows of uninstalled plugins are hidden; the row is the template's own, or the lowest locale variant when only variants ship) with code, subject, description, customized locales (`cabana.MailTemplate.CustomizedLocales`: Default and the locale codes of the customized versions, at most three then +N) and layout, and edits the subject, the Markdown body and the layout (a `relation` over `cabana.MailLayout` rows: every database-only layout and the catalog's file layouts). There is no create and no delete. A save marks the row customized, stamps `base_hash` with the file's current hash and `customized_at`, and validates the result through `postcard.Editor.Validate` inside the save's transaction; a `postcard.DraftError` is a 422 on its field with `backend::lang.mail.invalid_` (`:message`, `:name`). The index rows are written by `postcard.SyncIndex` and `postcard.EnsureLocaleRows` through `lagoon.OnDatabase` at activation; a failed sync is logged and retried on the first mail list request of the process, and a list request syncs again when the mail locales changed. The mail locales are the locales the translator's catalog holds plus, when a `cabana.TranslationWriter` is published, its enabled locales; the default locale is the writer's default locale, else the translator's. A template is one record per locale version: its own row (Default), a row per locale variant file (`welcome-en`) and a row per other mail locale that ships no file (`welcome-de`, created by `postcard.EnsureLocaleRows`, showing and sending the default version until it is customized). The update form's locale switcher lists them (`meta.localeVariants`); the record title is the template's base code, and the show response first ensures the template's missing locale rows, so a newly enabled locale can be opened without a restart. A save of a locale without a file stamps `base_hash` with the base file's hash; until it is customized, its form shows the base template's current version (its customization when there is one), and reset returns it to the base file. Mail layouts (`cabana.MailLayoutsControllerID`, model `cabana.MailLayout`) lists postcard's default layout first, then the file layouts and the custom (database-only, `source` NULL, shown as Custom) layouts by name; it creates custom layouts (code `^[a-z0-9-]+$`, free, create-only) and deletes them, refusing one that template rows still reference with a `cabana.ForbiddenError` whose message names the layout and the count (CLDR plural). Mail partials (`cabana.MailPartialsControllerID`, model `cabana.MailPartial`) edits the partials' HTML and text sections. Both need `cabana.PermissionManageMailLayouts`; saves are stamped and validated as templates are. On all three, the record action `reset` (danger, offered on a customized file-backed row) calls `postcard.ResetOverride` in the action's transaction; rows from files are never deleted. The list row states are `customized` (an override) and `outdated` (an override whose `base_hash` differs from the file's `file_hash`), the lists have a status filter (customized, not customized, outdated); on the templates list both apply to the whole template, any of its locale versions. The forms carry the `info` and `file_version` partials: the file (the base template's for a locale without a file), the status, on a template with locale versions the Default line or the line of a locale without a file (`backend::lang.mail.info_locale_default`, `info_locale_fallback`), the sample variables or the partial's call, the drift callout, and a 3-line-context LCS line diff of the serialized override (`postcard.FormatTemplate`, `FormatLayout`, `FormatPartial`) against the file, skipped above 2000 lines per side. The mail controllers declare `recordActions` without a preview block: the admin offers them in the update form's footer, a boot rule only these internal controllers are exempt from. Layout and partial content fields use the built-in `codeeditor` type (`language: html|css|text`, optional `mailImages`); Branding is the settings form `mail_brand` on `cabana.MailBrandSetting` (postcard's brand row, a `mailimage` logo, the `site_name` text field shown by the built-in layouts' header and footer (trimmed, at most 255 characters, empty falls back to the display name of `mail.from`) and 13 `colorpicker` colours; the first save switches mail from `mail.brandCss` to the compiled colours). Mail images is the singleton controller `cabana.MailImagesControllerID` (`cabana.MailImageLibrary`) with a public attachMany `images` fileupload; GET/POST `/mail/images` and GET `/mail/images/{id}` return absolute public URLs (`attach.AbsolutePublicURL`) and refuse with `mail.images.no_public_url` when neither `storage.uploads.public_url` nor `app.url` is set. Listing answers either mail permission; upload and the singleton form need `system.manage_mail_layouts`. POST `/mail/preview` renders an unsaved draft (`cabana.AdminMailPreviewRequest`: `mode`, `id`, `values`) through `postcard.Editor.Preview` and answers `cabana.AdminMailPreviewResult` (subject, html, text); mode `template` needs `system.manage_mail_templates`, modes `layout`, `partial` and `branding` need `system.manage_mail_layouts`. POST `/mail/test-send` (interactive sessions only) sends a template, layout or partial draft to the signed-in administrator's own email (`cabana.AdminMailTestSendResult`), refuses recipient keys in the body, and is limited to five sends per administrator per ten minutes through a published `cooler.Attempter` when `serve` has one, otherwise an in-process fixed window (429 with `Retry-After`). Forms carry `mailpreview` fields (`mode` matching the screen).
- Danger record actions: `pact.AdminRecordAction.Danger` is served as `danger` on the record response's `cabana.RecordAction` (absent when false, so existing payloads are unchanged); the admin's confirm dialog then uses its danger variant.
- Prompted record actions: a `pact.AdminRecordAction` with a `Prompt` (`pact.AdminActionPrompt`) asks the administrator for one text value in its confirm dialog. The record response serves it as `prompt` on the action's `cabana.RecordAction` (absent for every other action, so existing payloads are unchanged), and the action route accepts the body key `payload`, a JSON string, only for such an action: trimmed, not empty and at most `max_length` runes (422 on `payload` with `backend::lang.form.action_prompt_required` or `action_prompt_too_long`, `backend::lang.form.action_prompt_invalid` for another JSON type), then handed to `Run` as `pact.AdminRecordActionInput.Value`. Every other record action keeps refusing `record_id`, `values` and `payload`. A prompt without a label fails boot, owned or contributed.
- My account contributions: a plugin implementing `pact.HasAccountContributions` adds sections (`pact.AccountContribution`) to the administrator's own account page, each with a status line and buttons (`pact.AccountAction`). GET `/account/contributions` lists them for the signed-in administrator and POST `/account/contributions/{name}/actions/{action}` runs one for that administrator only, behind the interactive-only guard, the action's permissions and its `Applies` rule, inside a transaction; the answer may carry a URL the admin opens in a new tab. That URL is kept only when it is an absolute `http`/`https` URL with a host or a same-origin path (one leading `/`); anything else, `javascript:` and `data:` included, is dropped and logged without the URL. A section whose `Status` fails is listed with an empty status and `error: true`, and an action whose `Applies` fails is left out and marks its section `error: true` as well; both are logged and the other sections are answered as usual. A status is translated only when it is a phrase key. Names are generic: cabana never names the contributing plugin. The existing `/account*` and `/auth/me` payloads are unchanged. A non-identifier or duplicate section name, an empty label, a duplicate or non-identifier action name, a nil `Run` or an empty action label stops the boot.
diff --git a/modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml b/modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
index c3a41712..2f9cae08 100644
--- a/modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
+++ b/modules/cabana/backendscreens/models/mailbrandsetting/fields.yaml
@@ -4,6 +4,11 @@ fields:
comment: backend::lang.mail.brand.logo_comment
type: mailimage
span: full
+ site_name:
+ label: backend::lang.mail.brand.site_name
+ comment: backend::lang.mail.brand.site_name_comment
+ type: text
+ span: left
body_bg:
label: backend::lang.mail.brand.body_bg
type: colorpicker
diff --git a/modules/cabana/mail_admin.go b/modules/cabana/mail_admin.go
index 1afc940a..fe029c4d 100644
--- a/modules/cabana/mail_admin.go
+++ b/modules/cabana/mail_admin.go
@@ -1745,6 +1745,7 @@ func partialUsage(code, sections string) string {
type MailBrandSetting struct {
ID uint `gorm:"column:id;primaryKey"`
LogoFileID *uint `gorm:"column:logo_file_id"`
+ SiteName string `gorm:"column:site_name"`
BodyBg string `gorm:"column:body_bg"`
ContentBg string `gorm:"column:content_bg"`
HeaderColor string `gorm:"column:header_color"`
@@ -1766,7 +1767,7 @@ func (MailBrandSetting) TableName() string { return postcard.BrandTable }
func (MailBrandSetting) Fillable() []string {
return []string{
- "logo_file_id", "body_bg", "content_bg", "header_color", "footer_color",
+ "logo_file_id", "site_name", "body_bg", "content_bg", "header_color", "footer_color",
"heading_color", "text_color", "link_color", "button_text_color",
"button_primary_bg", "button_positive_bg", "button_negative_bg",
"panel_bg", "table_border_color",
@@ -1776,6 +1777,7 @@ func (MailBrandSetting) Fillable() []string {
func (MailBrandSetting) Rules() map[string]string {
return map[string]string{
"logo_file_id": "nullable",
+ "site_name": "nullable|max:255",
"body_bg": "nullable",
"content_bg": "nullable",
"header_color": "nullable",
@@ -1794,9 +1796,10 @@ func (MailBrandSetting) Rules() map[string]string {
var brandColourPattern = regexp.MustCompile(`^#[0-9a-f]{6}$`)
-// BeforeValidate lower-cases colours, refuses anything but #rrggbb or empty,
-// and checks logo_file_id is null or a library image.
+// BeforeValidate trims the site name, lower-cases colours, refuses anything
+// but #rrggbb or empty, and checks logo_file_id is null or a library image.
func (b *MailBrandSetting) BeforeValidate(tx *gorm.DB) error {
+ b.SiteName = strings.TrimSpace(b.SiteName)
details := map[string]any{}
for _, col := range []struct {
name string
diff --git a/modules/cabana/mail_routes.go b/modules/cabana/mail_routes.go
index 481d4913..5da5c0d4 100644
--- a/modules/cabana/mail_routes.go
+++ b/modules/cabana/mail_routes.go
@@ -587,6 +587,7 @@ func (s *service) mailBrandDraft(ctx context.Context, values map[string]any) (po
ButtonNegativeBg: stringValue(values["button_negative_bg"]),
PanelBg: stringValue(values["panel_bg"]),
TableBorderColor: stringValue(values["table_border_color"]),
+ SiteName: strings.TrimSpace(stringValue(values["site_name"])),
}
if raw, ok := values["logo_file_id"]; ok && raw != nil {
id, err := asUint(raw)
diff --git a/modules/cabana/mail_screens_smoke_test.go b/modules/cabana/mail_screens_smoke_test.go
index dc76a97f..161119d9 100644
--- a/modules/cabana/mail_screens_smoke_test.go
+++ b/modules/cabana/mail_screens_smoke_test.go
@@ -908,6 +908,24 @@ Hi **{{ .name }}**, thanks for joining the Acme blog.
t.Fatalf("stored colour = %#v", row["button_primary_bg"])
}
env.expect(t, http.StatusUnprocessableEntity, http.MethodPut, "/settings/mail_brand", rootToken, map[string]any{"logo_file_id": 999999})
+
+ // The site name is saved trimmed and is shown in the default
+ // layout's header and footer by the Branding preview.
+ saved = env.expect(t, http.StatusOK, http.MethodPut, "/settings/mail_brand", rootToken, map[string]any{"button_primary_bg": "#d66829", "site_name": " Acme Mail "})
+ if name := saved["data"].(map[string]any)["data"].(map[string]any)["site_name"]; name != "Acme Mail" {
+ t.Fatalf("stored site_name = %#v", name)
+ }
+ var stored cabana.MailBrandSetting
+ if err := env.gdb.First(&stored, 1).Error; err != nil || stored.SiteName != "Acme Mail" {
+ t.Fatalf("brand row = %+v err=%v", stored, err)
+ }
+ env.expect(t, http.StatusUnprocessableEntity, http.MethodPut, "/settings/mail_brand", rootToken, map[string]any{"site_name": strings.Repeat("x", 256)})
+ preview := env.expect(t, http.StatusOK, http.MethodPost, "/mail/preview", rootToken, map[string]any{
+ "mode": "branding", "id": 0, "values": map[string]any{"site_name": "Preview Name"},
+ })
+ if html := fmt.Sprint(preview["data"].(map[string]any)["html"]); !strings.Contains(html, "Preview Name") || !strings.Contains(html, "Preview Name
") {
+ t.Fatalf("branding preview lacks the site name: %s", html)
+ }
})
t.Run("images", func(t *testing.T) {
diff --git a/modules/phrasebook/backend/lang/en/lang.yaml b/modules/phrasebook/backend/lang/en/lang.yaml
index 1eaf7881..82694dd5 100644
--- a/modules/phrasebook/backend/lang/en/lang.yaml
+++ b/modules/phrasebook/backend/lang/en/lang.yaml
@@ -698,7 +698,9 @@ mail:
menu_label: "Mail branding"
menu_description: "Set the colours and logo used by every message."
logo: "Logo"
- logo_comment: "Layouts show the logo where they use {{ .logoUrl }}."
+ logo_comment: "The built-in layouts show the logo in their header. Your own layouts show it where they use {{ .logoUrl }}."
+ site_name: "Site name"
+ site_name_comment: "Shown in the header and footer of the built-in layouts. Leave it empty to use the sender name from mail.from."
body_bg: "Body background"
content_bg: "Content background"
header_color: "Header colour"
diff --git a/modules/phrasebook/backend/lang/pl/lang.yaml b/modules/phrasebook/backend/lang/pl/lang.yaml
index 2b4f9576..b76e928f 100644
--- a/modules/phrasebook/backend/lang/pl/lang.yaml
+++ b/modules/phrasebook/backend/lang/pl/lang.yaml
@@ -736,7 +736,9 @@ mail:
menu_label: "Wygląd wiadomości"
menu_description: "Ustaw kolory i logo używane we wszystkich wiadomościach."
logo: "Logo"
- logo_comment: "Układy pokazują logo tam, gdzie używają {{ .logoUrl }}."
+ logo_comment: "Wbudowane układy pokazują logo w nagłówku. Własne układy pokazują je tam, gdzie używają {{ .logoUrl }}."
+ site_name: "Nazwa witryny"
+ site_name_comment: "Wyświetlana w nagłówku i stopce wbudowanych układów. Zostaw puste, aby użyć nazwy nadawcy z mail.from."
body_bg: "Główne tło"
content_bg: "Tło treści"
header_color: "Kolor górnego nagłówka"
diff --git a/modules/postcard/README.md b/modules/postcard/README.md
index 18626b25..cb93bed0 100644
--- a/modules/postcard/README.md
+++ b/modules/postcard/README.md
@@ -30,7 +30,7 @@ Use cases:
- 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, a customized row of `system_mail_layouts` or `system_mail_partials` replaces a layout or a partial, and `system_mail_layouts` also holds layouts that exist only in the database. The mailer reads them 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.
-- Branding: once the branding settings have been saved, the brand CSS is compiled from their colours (`postcard.CompileBrandCSS`) and replaces `mail.brandCss`, and layouts get the logo's absolute URL as `{{ .logoUrl }}`.
+- Branding: once the branding settings have been saved, the brand CSS is compiled from their colours (`postcard.CompileBrandCSS`) and replaces `mail.brandCss`, and layouts get the logo's absolute URL as `{{ .logoUrl }}` and the site name as `{{ .siteName }}` (else the display name of `mail.from`). The built-in default layout shows them in a header and a copyright footer.
- Sample values: a template's header may give its variables sample values with `sample.` keys. Previews and save checks use them, and show every other variable as a visible `[path]` placeholder.
- An editor API for admin code (`postcard.Editor`): validate, preview and test-send an unsaved draft of a template, layout or partial through the same render path as a real send; one index row per file (`postcard.SyncIndex`) with a hash of the file for detecting that it changed under an override, and reset to the file version (`postcard.ResetOverride`).
- No locale selection: callers pass the full template name, including any locale suffix. A `-` name whose locale ships no file sends the default-locale version (see "Locale variants").
@@ -175,18 +175,22 @@ Markdown drops raw HTML, so a call in a body does not insert the partial's HTML
| Layout alias | Full name | Renders |
|--------------|-----------|---------|
-| `default` | `postcard::mail.layouts.default` | The message in a `content-body` block. Used when a template names no layout. |
+| `default` | `postcard::mail.layouts.default` | WinterCMS's default layout (`wrapper layout-default`): the `header` partial with the logo or the site name, the message in the `inner-body` card, and the `footer` partial with `© `. Used when a template names no layout. |
| `system` | `postcard::mail.layouts.system` | WinterCMS's system layout: the message in a centred table, followed by a note that the message is automatic. |
| `minimal` | `postcard::mail.layouts.minimal` | The message directly in the page body. |
A template selects one with `layout = "system"`. A plugin's own alias of the same name wins, except `default`, which plugins cannot redefine. Every built-in layout has the `{{ .brandCss }}{{ .css }}` style block.
+Both wrappers of every layout get these keys: `Content`, `Subject`, `css`, `brandCss`, `logoUrl` (see [Branding](#branding)), `siteName` (the Branding's site name, else the display name of `mail.from`, else empty) and `year` (the current year). The default layout calls the header only when `logoUrl` or `siteName` is set, and builds the footer line from `year` and `siteName`, `© 2026 Acme`, or `© 2026` without a name. Its text wrapper is the message, a blank line and the footer's text section.
+
| Partial | Arguments | Renders |
|---------|-----------|---------|
| `button` | `url`, `body`, `type` (`primary` by default, `positive` or `negative`) | A link styled as a button (`button button-`); in text, the label and the address. |
| `panel` | `body` (Markdown) | A highlighted block (`panel`). |
| `table` | `body` (a Markdown table) | A table in a `table` block. |
| `subcopy` | `body` (Markdown) | Small print under a rule (`subcopy`). |
+| `header` | `logo` (an image URL), `body` (a name), `url` (optional) | A layout's header row (`td.header`): `img.logo` with `body` as its alternative text when `logo` is set, else `body` in a `span`; wrapped in a link when `url` is set. In text, the name. |
+| `footer` | `body` (Markdown) | A layout's footer row (`table.footer`). In text, a rule line and the body. |
### Overrides from the admin
@@ -240,7 +244,7 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile
### Branding
-Layouts have two CSS slots, `{{ .brandCss }}` and `{{ .css }}`, and a logo slot, `{{ .logoUrl }}`. What fills the brand slot depends on the row with `id` 1 of `system_mail_brand_settings`:
+Layouts have two CSS slots, `{{ .brandCss }}` and `{{ .css }}`, a logo slot, `{{ .logoUrl }}`, and a name slot, `{{ .siteName }}`. What fills the brand slot depends on the row with `id` 1 of `system_mail_brand_settings`:
- While the row does not exist, the slot holds `mail.brandCss` from the configuration and `{{ .logoUrl }}` is empty, so an application that never saves Branding is unchanged.
- Once the row exists, the slot holds `postcard.CompileBrandCSS` of the row's colours, and `mail.brandCss` is no longer used. An empty colour column is that colour's default (`postcard.DefaultBrand`).
@@ -271,6 +275,8 @@ The row's `logo_file_id` names a public `system_files` row. Its URL is not store
{{ if .logoUrl }}
{{ end }}
```
+The row's `site_name` column is `postcard.Brand.SiteName`. The built-in layouts show it in their header (as the logo's alternative text when there is a logo) and footer. While it is empty, and while no Branding row exists, `{{ .siteName }}` is the display name of `mail.from` parsed with `net/mail` (`Acme` for `Acme `), or empty when the address has none. The name is HTML-escaped by `html/template` wherever a layout prints it.
+
A mail that falls back to its file version because an override failed still gets the Branding.
### Sample values
@@ -391,7 +397,7 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
| `postcard.LayoutOverride` | A layout's name, HTML wrapper, text wrapper and CSS from the database. In `postcard.Overrides.Layouts` under a file layout's full name it replaces that layout; under another code it is a database-only layout. |
| `postcard.PartialOverride` | A partial's HTML and text sections from the database, in `postcard.Overrides.Partials` under the partial's full name. |
| `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. It builds the Branding logo's URL from the app's configuration. |
-| `postcard.Brand` | The Branding: thirteen colours and `postcard.Brand.LogoURL`, the logo's absolute URL. |
+| `postcard.Brand` | The Branding: thirteen colours, `postcard.Brand.LogoURL`, the logo's absolute URL, and `postcard.Brand.SiteName`, the name the built-in layouts show. |
| `postcard.DefaultBrand` | WinterCMS's default mail colours. |
| `postcard.CompileBrandCSS` | Checks a brand's colours and returns the brand CSS compiled from them. |
| `postcard.Migrations` | The gormigrate set that creates the mail tables; lagoon runs it under the `summercms.postcard` history. |
@@ -423,7 +429,7 @@ A draft is rendered by the code that renders a send, with the mailer's CSS and t
| 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.from` | empty | Sender address. Required by the SMTP driver. Its display name is the layouts' `{{ .siteName }}` while the Branding has no site name. |
| `mail.css` | empty | CSS placed in the layout's style block, after the brand CSS. Always applied. |
| `mail.brandCss` | empty | Brand CSS placed before `mail.css`. Used only until the branding settings are saved; from then on the CSS compiled from their colours replaces it (see [Branding](#branding)). |
| `mail.smtp.host` | none | SMTP host. Required when `mail.driver` is `smtp`. |
diff --git a/modules/postcard/assets/brand.css.tmpl b/modules/postcard/assets/brand.css.tmpl
index 18c67a0b..d37dd8c0 100644
--- a/modules/postcard/assets/brand.css.tmpl
+++ b/modules/postcard/assets/brand.css.tmpl
@@ -90,6 +90,14 @@ img {
font-weight: bold;
text-decoration: none;
}
+img.logo {
+ border: 0;
+ display: inline-block;
+ height: auto;
+ max-height: 60px;
+ max-width: 200px;
+ vertical-align: middle;
+}
/* Body */
.body {
background-color: {{ .ContentBg }};
diff --git a/modules/postcard/assets/default.htm b/modules/postcard/assets/default.htm
index dbb6c366..57113b1d 100644
--- a/modules/postcard/assets/default.htm
+++ b/modules/postcard/assets/default.htm
@@ -1,14 +1,37 @@
name = "Default"
==
{{ .Content }}
+
+{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "body" $copy }}
==
+
-{{ .Content }}
+
+{{ if or .logoUrl .siteName }}{{ partial "header" "logo" .logoUrl "body" .siteName }}{{ end }}
+
+
+
+
+
+
+
+|
+{{ .Content }}
+ |
+
+
+ |
+
+
+ |
+
+{{ $copy := printf "© %v" .year }}{{ with .siteName }}{{ $copy = printf "%s %s" $copy . }}{{ end }}{{ partial "footer" "body" $copy }}
+
diff --git a/modules/postcard/assets/partials/footer.htm b/modules/postcard/assets/partials/footer.htm
new file mode 100644
index 00000000..ffc17d25
--- /dev/null
+++ b/modules/postcard/assets/partials/footer.htm
@@ -0,0 +1,16 @@
+name = "Footer"
+==
+-------------------
+{{ .body }}
+==
+
+|
+
+ |
+
diff --git a/modules/postcard/assets/partials/header.htm b/modules/postcard/assets/partials/header.htm
new file mode 100644
index 00000000..7f4fc5c7
--- /dev/null
+++ b/modules/postcard/assets/partials/header.htm
@@ -0,0 +1,9 @@
+name = "Header"
+==
+{{ .body }}
+==
+
+
+
diff --git a/modules/postcard/brand.go b/modules/postcard/brand.go
index a4f08004..15e64c1c 100644
--- a/modules/postcard/brand.go
+++ b/modules/postcard/brand.go
@@ -29,6 +29,11 @@ type Brand struct {
// LogoURL is the absolute URL of the logo, given to layouts as
// {{ .logoUrl }}. It is not part of the CSS.
LogoURL string
+ // SiteName is the name the built-in layouts show in their header (when
+ // there is no logo, and as the logo's alternative text) and footer,
+ // given to layouts as {{ .siteName }}. Empty uses the display name of
+ // mail.from. It is not part of the CSS.
+ SiteName string
}
// DefaultBrand returns WinterCMS's default mail colours.
diff --git a/modules/postcard/brand_smoke_test.go b/modules/postcard/brand_smoke_test.go
index b68e58b7..0ee1853f 100644
--- a/modules/postcard/brand_smoke_test.go
+++ b/modules/postcard/brand_smoke_test.go
@@ -191,7 +191,7 @@ func TestMailBrandSmoke(t *testing.T) {
if strings.Contains(css, ".cfg{color:blue}") || !strings.HasSuffix(css, "p{margin:1px}") {
t.Errorf("the draft CSS must replace mail.brandCss and leave mail.css after it:\n%s", css)
}
- for _, want := range []string{``, `class="button button-primary"`, `
\n", `class="button button-primary"`, `
\n
",
+ `class="inner-body"`,
+ "\n Hi Ada ",
+ `class="button button-primary"`,
+ ` |