Features and status

Last updated on
23 April 2023

Symfony Mailer module creates a new mail-system with a new API. For back-compatibility, all emails sent using the 'old' mail interface are converted to send via Symfony Mailer. For any module that sends emails, there are 3 possible levels of integration, described below.

  • Level 1: features available with no extra code and maximum back-compatibility (some limitations).
  • Level 2: extra features by overriding email building with an EmailBuilder plug-in (this module provides some for key core and contrib modules).
  • Level 3: change the module code to use the new API for code simplification.

Level 1 – Compatibility mode

Many applications that send emails using the old interface will work automatically without any code changes. This level gives good back-compatibility with previous modules (in particular swiftmailer) , and there are still benefits to running in this way.

  • Send emails as HTML, with plain-text alternative automatically generated using modern supported library code.
  • Customise emails with TWIG templates, optionally targeting specific email types with theme suggestions.
  • Style emails with CSS using the Drupal library mechanism, with automatic inline CSS for compatibility with email applications.
  • "Mailer Transport" GUI to configure any transport supported by Symfony. This includes integrations with popular 3rd-party email delivery services and support for load-balancing/failover. IN PROGRESS: the core transports have a dedicated GUI with specific fields, for the rest you have to enter a "DSN".
  • "Mailer Policy" GUI to configure:
    • Email body and subject. Limitation there are no module-specific template variables or tokens available until level 2. For example if overriding the core "password reset" email there is no way to include the user name or the login URL.
    • Common headers such as addresses, body, subject.
    • Transport, mail theme, skip sending, send as plain-text.
    • Each setting can change all emails, or restrict to a specific type.
  • Attach files. TODO allow embedding, and more configuration options.
  • Extensive customisation through hooks and plug-ins.
  • Fixes some bugs in the 'old' mail-system.

Level 2 – Override mode

A simple EmailBuilder plug-in overrides the hook_mail() sending code provided by the module. The new plug-in uses Symfony Mailer interfaces to access more features, yet sill without changing code in the sending modules.

  • Use tokens or TWIG variables in the email subject and body. For example you can change the subject and introductory wording in a contact email, using full HTML with links and classes to allow styling with CSS.
  • Categorise emails and configure separate Policy: for example apply different styling or wording a specific contact form.
  • Embed Mailer Policy configuration into the existing module configuration. For example on the Account settings page configure HTML body, subject, from address, theme or any other aspect of emails for all messages or a specific sub-type.
  • Automatically import configuration from the module to create Mailer Policy.
  • The old hook_mail_alter() interface is not called.

Level 3 – Native implementation

Modules can write directly to the new mailer API. The features are the same as level 2, however it simplifies code in the sending module. Several existing modules have responded to the limitations of the old API by adding features; this module includes many such features, often in a better way because there is direct access to the underlying Symfony classes.

Module code can be simplified yet more flexible and powerful – for example in simplenews, it saves over 2000 lines of code #3275129: Use Symfony Mailer API to send mails!

  • Use Mailer Policy instead of module-specific code to set email subject, body, from, ...
  • Built-in support for HTML, twig templates, tokens, language switching, entities, absolute URL conversion, ...
  • Move "written language" (fixed translatable sentences) out of code instead offering easy customisation via templates or config entities.

Help improve this page

Page status: No known problems

You can: