[meeting] 2026-07-01 core mailer beta planning

The plugin issue moved quite a bit #3539651: Introduce email plugins:

1. A new branch has been opened which prototypes a mail wrapper template and theme switching.
2. The api docs have been moved over and adapted from a previous branch.
3. All core emails were brought up-to-date on the core-emails branch.

The group discussed the theme switching and wrapper template proposal in depth. The merge request incorporates functionality which isn’t strictly necessary for an initial iteration. The possibility to declare email libraries in a theme info file is not a feature with the highest priority. In order to avoid inflating the size of the MR too much, this should be removed for now.

It was questioned whether the theme switching is occurring at the right point in time. It can be argued that the theme should be already switched when the email is built (i.e., when EmailPluginInterface::htmlBody() is called. Also it might be surprising to developers when hook_email_pre_render_alter and hook_email_post_render_alter are invoked outside of the context of a mail theme. One possible forward looking way to fix this is to implement something similar as #3536307: Execution environment: Safely run code inside an environment with partially substituted system state / config but just the bits which are necessary for an initial MR.

There is a potential problem with the proposed approach to collect the CSS. A library attached in a nested render element might only be available from the top-level #attached build key after the render array is rendered. This is because the metadata is bubbled up only during the rendering - and not before. This needs further investigation, and possibly a refined approach (similar to how html.html.twig works in combination with HtmlResponseAttachmentsProcessor.

During the discussion about theme switching the group briefly talked about separate email themes. In other words, whether sites would normally have a separate email theme or whether they will incorporate the email CSS into the default theme. This discussion led to the realization that the core email mechanism shouldn’t favor one approach over the other: It needs to work for both. Also the functionality available to email twig templates should be the same as for templates used to generate HTML responses.

API documentation was copied from a previous branch and adapted to the current plugin approach. The mailer.api.php docs have two sections: The first one is about how to implement email plugins using either a yaml file or a plugin attribute, the second one contains documentation about the hooks. During the discussion around context switching it was brought up that the hooks docs should specify whether they execute in the site context or in the email render context (where the theme, the language, the current user is potentially different).

The core emails branch was brought up-to-date with the current approach. Core is only missing the user mail notifier feature (#3539178: Extract _user_mail_notify() into a user NotificationHandler) before the core email branch is working without any core patches. The core emails branch now follows the current pattern for module based feature flags. All the PHP code is placed at a location where it eventually ends when the feature lands. The only thing which is left in the mailer module is the services file which is responsible for activating the experimental classes and replacing existing services with experimental ones.