fix(postcard): an inlined result that fails the safety check sends the style block

- inlineHTML treats a failing post-inline check like an inliner error:
  the un-inlined HTML, which already passed validateHTML, is sent with
  its style block and the rate-limited inline:<layout> warning
- mail is never stopped by the inliner, as the docs promise (WR-05)
- README and docs/services/mail.md describe the check before inlining
- TestMailSafetySmoke/inline_unsafe_output
This commit is contained in:
Jakub Zych
2026-11-14 15:25:03 +01:00
parent 701ce8979d
commit cd91cf2e64
4 changed files with 47 additions and 8 deletions

View File

@@ -183,7 +183,7 @@ A template selects one with `layout = "system"`. A plugin's own alias of the sam
### CSS inlining
After a layout's HTML wrapper has rendered and passed the safety checks, postcard inlines it, as WinterCMS's `MailManager` does with CssToInlineStyles: `github.com/vanng822/go-premailer` with its default options reads the rules of every style element, writes them into the `style` attributes of the matching elements by specificity, mirrors CSS `width` and `height` to the attributes of the same name, keeps `class` attributes, and puts the rules it cannot inline (media queries, pseudo-classes such as `:hover`, selectors with `*`) back in one style element, marked `!important`. The inlined HTML is checked again, so a `javascript:`, `vbscript:` or `data:` address that reaches a `style` attribute fails the render as before. HTML with no style element is left as it is. Preview, test send and sends run the same code; the text part is never changed.
After a layout's HTML wrapper has rendered and passed the safety checks, postcard inlines it, as WinterCMS's `MailManager` does with CssToInlineStyles: `github.com/vanng822/go-premailer` with its default options reads the rules of every style element, writes them into the `style` attributes of the matching elements by specificity, mirrors CSS `width` and `height` to the attributes of the same name, keeps `class` attributes, and puts the rules it cannot inline (media queries, pseudo-classes such as `:hover`, selectors with `*`) back in one style element, marked `!important`. The safety checks run on the decoded markup before inlining, whether or not the layout opts out, so CSS in a style element with a `javascript:`, `vbscript:` or `data:` address is refused there. The inlined HTML is checked again, and an inlined result that fails the check is sent as its style-block version, with the same warning as an inliner error. HTML with no style element is left as it is. Preview, test send and sends run the same code; the text part is never changed.
A layout opts out with WinterCMS's option name, `disable_auto_inline_css`:
@@ -191,7 +191,7 @@ A layout opts out with WinterCMS's option name, `disable_auto_inline_css`:
- a row of `system_mail_layouts` sets the column `disable_auto_inline_css` (`postcard.LayoutOverride.DisableAutoInlineCSS`); `postcard.SyncIndex` mirrors the file's value into rows that are not customized and `postcard.ResetOverride` writes it back;
- a layout draft sets `postcard.Draft.DisableAutoInlineCSS`.
An opted-out layout keeps its style block as rendered. When the inliner fails on a message, the message is sent with its style block only and a warning keyed by the layout is logged at most once a minute.
An opted-out layout keeps its style block as rendered; it passed the same safety checks as an inlined one. When the inliner fails on a message, or its result fails the safety checks, the message is sent with its style block only and a warning keyed by the layout is logged at most once a minute.
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 and system layouts call 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.