# 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 `::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). Three layouts are built in and usable from any plugin's templates: `default`, `system` and `minimal`. - Partials: reusable blocks named `::mail.partials.`, loaded from `views/mail/partials/.htm` and declared through `pact.HasMailPartials`. Bodies and layouts call them with `{{ partial "" "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.` 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 }} ==
{{ .text }}
``` 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-`); 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 }}{{ 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: 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.