Files
summercms/modules/postcard/README.md
Jakub Zych 2bf9081c1b feat(postcard): mail branding and the logo URL
- Brand, DefaultBrand and CompileBrandCSS: thirteen colours, each checked
  as a six-digit hex colour, compiled into CSS for plain elements and the
  built-in layouts and partials
- once the branding row exists its compiled CSS replaces mail.brandCss;
  mail.css still follows, and the file version sent after a failing
  override keeps the Branding
- layouts get logoUrl, built per send from storage.uploads.public_url or
  app.url through attach.AbsolutePublicURL; a logo that cannot be shown is
  left out with a rate-limited warning
- Editor previews and validates a Branding draft (rule colour)

Plan 35-01, task 5.
2026-11-13 11:06:43 +01:00

449 lines
31 KiB
Markdown

# 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/`, and plugins that implement `pact.HasMailPartials` ship reusable blocks for them; at boot, `postcard.Activate` publishes one app-scoped `postcard.Mailer` built from the compass `mail.*` config, and `postcard.BootPlugin` registers each plugin's templates, layouts and partials 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, layout or partial has a customized row, the mailer uses 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`, and uses only lagoon's `attach` package, for the logo's URL. 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). Three layouts are built in and usable from any plugin's templates: `default`, `system` and `minimal`.
- Partials: reusable blocks named `<plugin>::mail.partials.<name>`, loaded from `views/mail/partials/<name>.htm` and declared through `pact.HasMailPartials`. Bodies and layouts call them with `{{ partial "<name>" "key" value }}`. The partials `button`, `panel`, `table` and `subcopy` are built in.
- Every message gets an HTML part (Markdown converted with goldmark) and a plain-text part. The brand CSS (`mail.brandCss`, or the saved Branding) and `mail.css` go 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, 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 }}`.
- Sample values: a template's header may give its variables sample values with `sample.<path>` 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.
## 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)
}
}
```
### Partials
A partial is a block of mail that several templates and layouts share, such as a button. Its file has the layout format: a header with a `name`, a `==` line, the text section, a `==` line, then the HTML section. A plugin ships `views/mail/partials/note.htm`:
```text
name = "Note"
==
NOTE: {{ .text }}
==
<div class="note">{{ .text }}</div>
```
and declares it next to its templates:
```go
package blog
import (
"embed"
"io/fs"
"git.golem15.com/golem15/summercms/modules/pact"
)
//go:embed views/mail
var mailFS embed.FS
type Plugin struct{}
var _ pact.HasMailPartials = Plugin{}
func (Plugin) ID() string { return "acme.blog" }
func (Plugin) MailPartialsFS() fs.FS { return mailFS }
func (Plugin) MailPartials() []string {
return []string{"acme.blog::mail.partials.note"}
}
```
A name must be in the plugin's own namespace and under `mail.partials.`; a name outside either, a missing file or a duplicate fails `postcard.BootPlugin` with the dotted name. A plugin may implement `pact.HasMailPartials` without `pact.HasMailTemplates`, and any plugin's templates may call its partials.
A template body or a layout calls a partial with its name followed by pairs of a key and a value, which become the partial's variables:
```text
subject = "Your order {{ .code }}"
==
Thanks for your order.
{{ partial "button" "url" .link "body" "Track the order" "type" "positive" }}
{{ partial "acme.blog::mail.partials.note" "text" .note }}
```
A bare name such as `button` is one of postcard's built-in partials; a plugin's partial is called by its full name. The HTML section goes into the HTML part and the text section into the plain-text part. An unknown name, an odd number of key and value arguments or a key that is not a string fails the render with the partial's name.
Inside a partial's HTML section, `{{ markdown .body }}` renders a value as Markdown, tables included; in the text section it returns the value unchanged. A partial cannot call `partial`.
Markdown drops raw HTML, so a call in a body does not insert the partial's HTML directly. It leaves a token of letters and digits, `MAILPARTIAL` followed by a random value drawn for that one render, and postcard swaps the token for the rendered partial after the body has been converted. A variable's value cannot contain that token, so text that only looks like one stays text. Put a call on its own line, with blank lines around it, to get the partial as a block of its own. Markdown rendering of bodies is unchanged: raw HTML in a body is still dropped.
### Built-in layouts and partials
| Layout alias | Full name | Renders |
|--------------|-----------|---------|
| `default` | `postcard::mail.layouts.default` | The message in a `content-body` block. 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.
| Partial | Arguments | Renders |
|---------|-----------|---------|
| `button` | `url`, `body`, `type` (`primary` by default, `positive` or `negative`) | A link styled as a button (`button button-<type>`); 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`). |
### 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.
Layouts and partials are overridden the same way. A row of `system_mail_layouts` with `is_custom` set and a full layout name in `code` replaces that layout's HTML and text wrappers; a row with another `code` is a layout that exists only in the database, which a template override can select. A layout row's `content_css` is placed before `mail.css` in the layout's `{{ .css }}` slot. A row of `system_mail_partials` with `is_custom` set replaces the HTML and text sections of the partial named in its `code`.
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 an override (of the template, its layout or a partial it calls) 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 message is sent from the files alone.
- 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{}})
}
```
### 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`:
- 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`).
`mail.css` fills `{{ .css }}` in both cases, after the brand CSS, with a layout's own CSS before it.
The compiled CSS styles the page, links, headings, paragraphs and tables, and the classes of the built-in layouts and partials (`button button-primary`, `panel`, `table`, `subcopy`, `layout-system` and others), so the colours also apply in a plugin's layout that has the style block and no brand classes of its own. A colour must be a six-digit hexadecimal colour such as `#2da7c7`; `postcard.CompileBrandCSS` refuses anything else with an error naming the column. If a stored colour is invalid at send time, a warning is logged and `mail.brandCss` is used.
| Column | `postcard.Brand` field | Default |
|--------|------------------------|---------|
| `body_bg` | `BodyBg` | `#f5f8fa` |
| `content_bg` | `ContentBg` | `#ffffff` |
| `header_color` | `HeaderColor` | `#bbbfc3` |
| `footer_color` | `FooterColor` | `#aeaeae` |
| `heading_color` | `HeadingColor` | `#2f3133` |
| `text_color` | `TextColor` | `#74787e` |
| `link_color` | `LinkColor` | `#2da7c7` |
| `button_text_color` | `ButtonTextColor` | `#ffffff` |
| `button_primary_bg` | `ButtonPrimaryBg` | `#d66829` |
| `button_positive_bg` | `ButtonPositiveBg` | `#52a838` |
| `button_negative_bg` | `ButtonNegativeBg` | `#e01346` |
| `panel_bg` | `PanelBg` | `#edeff2` |
| `table_border_color` | `TableBorderColor` | `#edeff2` |
The row's `logo_file_id` names a public `system_files` row. Its URL is not stored: on every send it is built from the configuration with `attach.AbsolutePublicURL`, from `storage.uploads.public_url`, or from `app.url` and `storage.uploads.public_path_prefix`, so a worker process and `serve` produce the same absolute URL and a changed CDN address applies at once. When the file is missing or not public, or neither base is configured, `{{ .logoUrl }}` is empty, a warning is logged at most once a minute, and the mail is sent. A layout that shows the logo guards it:
```text
{{ if .logoUrl }}<img src="{{ .logoUrl }}" alt="">{{ end }}
```
A mail that falls back to its file version because an override failed still gets the Branding.
### Sample values
A preview has no caller to supply variables, so a template can carry sample values in its header. A key is `sample.` followed by the variable's path, and the path keeps its case, because template variables are case-sensitive:
```text
subject = "Your order {{ .order.code }}"
description = "Sent when an order is paid"
sample.name = "Ada"
sample.order.code = "ZAM-1"
==
Hi {{ .name }}, we received the payment for **{{ .order.code }}**.
{{ range .order.items }}- {{ .description }}
{{ end }}
```
Sample values are strings and are used only by `postcard.Editor`; `Send` never reads them, and a file without them works as before. For a preview postcard walks the draft's subject and body and gives every variable they read a value: its sample, or the placeholder `[path]`, as in `[order.items.description]`. A field of a variable becomes a nested value and the target of a `range` a list of one element, so a body that reads `.order.code` or ranges over `.order.items` renders without the caller's data.
### Editing drafts
`postcard.EditorFrom` returns the `postcard.Editor` of the mailer `postcard.Activate` published. Admin code describes unsaved content as a `postcard.Draft` and asks the editor to check, render or send it:
```go
package blog
import (
"context"
"errors"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/postcard"
)
// previewWelcome renders an edited welcome mail without saving it.
func previewWelcome(ctx context.Context, app *backpack.App, subject, body string) (postcard.Preview, error) {
editor, ok := postcard.EditorFrom(app)
if !ok {
return postcard.Preview{}, errors.New("mailer not published")
}
draft := postcard.Draft{
Kind: postcard.KindTemplate,
Name: "acme.blog::mail.welcome",
Subject: subject,
Body: body,
}
if problem := editor.Validate(ctx, draft); problem != nil {
// problem.Field and problem.Rule say what to show next to which field.
return postcard.Preview{}, problem
}
return editor.Preview(ctx, draft)
}
```
A draft is rendered by the code that renders a send, with the mailer's CSS and the layouts and partials its override source returns, so a preview is what the saved content would send:
| `postcard.Draft.Kind` | `postcard.Draft.Name` | Content fields | Rendered as |
|-----------------------|-----------------------|----------------|-------------|
| `postcard.KindTemplate` | The template's full name | `Subject`, `Body`, `Layout` (a layout code; empty keeps the file's layout) | The template with its sample values and placeholders. |
| `postcard.KindLayout` | The layout's code | `HTML`, `Text`, `CSS` | The layout around postcard's sample message. |
| `postcard.KindPartial` | The partial's full name | `HTML`, `Text` | A message that is one call of the partial, with a placeholder for every argument it reads. |
| `postcard.KindBrand` | Not used | `Brand` (nil is the default brand) | The sample message in the default layout, with the draft's colours and logo in place of the saved Branding. |
`postcard.Editor.Validate` returns nil or a `postcard.DraftError`. `postcard.DraftError.Field` is the form field at fault: `subject`, `layout` or `body` for a template, `content_html`, `content_text` or `content_css` for a layout or a partial, the colour's column for Branding. `postcard.DraftError.Rule` is one of:
| Rule | Meaning |
|------|---------|
| `parse` | The content is not a valid template. |
| `render` | It does not render with the sample values and placeholders. |
| `unsafe` | It contains, or renders to, a script, iframe, object or embed tag, an inline event handler or a `javascript:`, `vbscript:` or `data:` address; a layout's CSS that would close the style block is refused the same way. `postcard.DraftError.Message` holds the text that matched. |
| `subject_line` | The subject renders to more than one line. |
| `layout` | The template's layout code names no layout. |
| `partial` | A call names a partial that does not exist; `postcard.DraftError.Name` holds the name. |
| `no_content` | A layout wrapper does not use `{{ .Content }}`. |
| `colour` | A Branding colour is not a six-digit hexadecimal colour; the field is its column, such as `button_primary_bg`. |
`postcard.DraftError.Message` carries the template parser's, the renderer's or the safety check's own text and nothing else. The safety checks are the ones a send runs, so text such as `metadata:` is refused at save as it would be at send, and the message shows where. A template body is also refused when its source contains one of the unsafe tags, which Markdown would otherwise drop without notice.
`postcard.Editor.Preview` and `postcard.Editor.SendDraft` return a draft problem as a `postcard.DraftError` too (use `errors.As`). `postcard.Editor.SendDraft` delivers the rendered draft to the one address it is given, through the mailer's driver and from `mail.from`.
### Index rows, drift and reset
`postcard.Catalog.Templates`, `postcard.Catalog.Layouts` and `postcard.Catalog.Partials` list the files as `postcard.TemplateFile`, `postcard.LayoutFile` and `postcard.PartialFile` values; each carries its `Source` and a `Hash`, the SHA-256 of the file's text with CRLF line endings normalized, so the same file hashes the same on every platform.
`postcard.SyncIndex` gives every file a row in its table, keyed by `code`. A row that is not customized mirrors the file, so lists and forms show the file version. A customized row keeps its content; only `source`, `description`, `locale`, `name` and `file_hash` follow the file. An override stores the hash of the file it was written against in `base_hash`, so it is outdated when `base_hash` and `file_hash` differ. `postcard.SyncIndex` never deletes a row, leaves database-only layouts alone, writes nothing when a row already matches, and may run in several processes at once. It needs the tables: when they are not migrated yet it returns the error.
`postcard.ResetOverride` returns one row to its file version and clears `is_custom`, `base_hash` and `customized_at`. A database-only layout has no file version and is refused.
`postcard.FormatTemplate`, `postcard.FormatLayout` and `postcard.FormatPartial` write content in the file format, so a file version and an override can be compared line by line. `postcard.TemplateLocale` reads the locale from a name such as `acme.blog::mail.welcome-en`, given the application's locales.
## 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 partials (`pact.HasMailPartials`) and its templates and layouts (`pact.HasMailTemplates`) 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, layouts and partials, including the built-in ones. |
| `postcard.NewCatalog` | Returns a catalog holding the built-in layouts and partials and no template. |
| `postcard.Catalog.Register` | Loads a plugin's templates and layout aliases from an `fs.FS`. |
| `postcard.Catalog.RegisterPartials` | Loads a plugin's partials 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`, partial content by name in `postcard.Overrides.Partials` and the saved Branding in `postcard.Overrides.Brand` (nil while it has never been saved). |
| `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 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.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. |
| `postcard.TemplatesTable`, `postcard.LayoutsTable`, `postcard.PartialsTable`, `postcard.BrandTable`, `postcard.ImageLibraryTable` | The names of the mail tables, for code that defines models over them. |
| `postcard.SyncIndex` | Upserts one index row per file template, layout and partial of a catalog; mirrors the file into rows that are not customized and refreshes `file_hash` on all. |
| `postcard.ResetOverride` | Returns one file-backed row to its file version. Takes the row's `postcard.Kind` and code. |
| `postcard.Kind` | What a draft or a row is: `postcard.KindTemplate`, `postcard.KindLayout`, `postcard.KindPartial` or `postcard.KindBrand` (a Branding draft; it has no index row). |
| `postcard.Editor` | Validates, previews and test-sends drafts with the mailer's catalog, configuration, override source and driver. |
| `postcard.EditorFrom` | Returns the editor of the mailer published on an app. |
| `postcard.Editor.Catalog` | The mailer's catalog. |
| `postcard.Editor.Validate` | Checks a draft; returns nil or a `postcard.DraftError`. |
| `postcard.Editor.Preview` | Renders a draft to a `postcard.Preview` (subject, HTML part, text part). |
| `postcard.Editor.SendDraft` | Renders a draft and delivers it to one address. |
| `postcard.Draft` | Unsaved content of one kind. |
| `postcard.DraftError` | Why a draft cannot be saved: field, rule, message and, for an unknown partial, its name. |
| `postcard.TemplateFile`, `postcard.LayoutFile`, `postcard.PartialFile` | A registered file with its parts, its normalized `Source` and its `Hash`. `postcard.TemplateFile.Samples` holds the sample values and `postcard.TemplateFile.Layout` the full name of the file's layout. |
| `postcard.Catalog.Templates`, `postcard.Catalog.Layouts`, `postcard.Catalog.Partials` | The registered files, sorted by name. |
| `postcard.Catalog.Template`, `postcard.Catalog.Layout`, `postcard.Catalog.Partial` | One registered file by full name. |
| `postcard.FormatTemplate`, `postcard.FormatLayout`, `postcard.FormatPartial` | Content written in the file format, for display and comparison. |
| `postcard.TemplateLocale` | The locale suffix of a template name, when it is one of the given locales. |
## Configuration
`postcard.Activate` reads these keys from the app's [compass](../compass/README.md) config. The Branding logo's URL also reads `storage.uploads.public_url`, `storage.uploads.public_path_prefix` and `app.url`, which belong to [lagoon](../lagoon/README.md)'s `attach` and to the application.
| 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 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`. |
| `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: <secret>
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), and the `attach` package of [lagoon](../lagoon/README.md) (`attach.AbsolutePublicURL` and `attach.BlobKey` for the logo's URL; lagoon itself is not imported).
- Third-party: `github.com/wneessen/go-mail` (SMTP), `github.com/yuin/goldmark` (Markdown, and its table extension inside partials), `gorm.io/gorm` (reading overrides), `github.com/go-gormigrate/gormigrate/v2` (the mail tables' migrations).
- Standard library: `bytes`, `context`, `crypto/rand`, `crypto/sha256`, `database/sql`, `embed`, `encoding/hex`, `errors`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `sort`, `strconv`, `strings`, `sync`, `text/template` (and `text/template/parse`), `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, index and reset tests a Postgres container, all 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.