Getting started

Migrating from Swiftmailer

Please read this page before you begin.

Installation

The recommended installation method is with Composer. As an alternative, installation is possible using Ludwig.

Enable the Symfony Mailer (symfony_mailer) module to replace the Drupal mail system and to send all emails via Symfony Mailer. You don't need the Mail System module, as Symfony Mailer already includes similar features.

Configuration

Overriding

This module can override the email building of some other core/contrib modules with improved versions that take advantage of all of the features of this module. For example it can send core User and Contact emails as HTML with CSS styling. The supported modules page gives the full list of available modules.

You can enable overrides from the GUI at "Configuration » System » Mailer » Override" or you can use provided drush commands drush mailer:override-info and drush mailer:override. When overriding is enabled for a module:

• The 'old' email configuration (such as on "Account settings") is replaced with this module's Mailer Policy configuration GUI (see below) that's much more flexible.
• The 'old' hooks hook_mail() and hook_mail_alter() will not be called.
• You can import configuration from existing modules to create an equivalent Mailer Policy. Don't worry if you don't really understand what this means yet as it will become clear later. It's recommended to run the import now, before you start editing policy in the next step.

Mailer Policy

This module provides a GUI to customise outgoing emails in many different ways. Known as the Mailer Policy, it can be set at "Configuration » System » Mailer".

There are many possible policies to apply including: subject; body; addresses (from, to, ...); theme, transport, convert to plain text. Each policy can be set globally or for emails of a specific type.

Mailer Transport

By default, Symfony Mailer uses the sendmail transport. You can configure a different transport such as SMTP at "Configuration » System » Mailer » Transport".

This module provides a GUI for the built-in Symfony transports. The 3rd-party transports can be configured using the "DSN" transport, and entering the DSN directly.

Custom sendmail command

For security reasons, the sendmail transport doesn't allow entering of an arbitrary custom command. You can enable specific custom commands using settings.local.php:

$settings['mailer_sendmail_commands'] = [
  'command 1',
  'command 2',
];

Configure the sendmail transport, and there will be an option to use these commands.

Mailhog

If you're using mailhog to intercept emails locally, use the custom command ini_get('sendmail_path') . ' -t'.

Platform.sh

If you're hosting on Platform.sh, they provide msmtp to intercept sendmail emails and forward them to Sendgrid. Since the msmtp doesn't work with the default -bs sendmail option, you should use the custom  command ini_get('sendmail_path') . ' -t -i'.

Theming

By default, this module uses the active theme, falling back to the default theme. You can configure a different theme (either globally or for specific types of email) by editing the relevant policy and configuring a Theme policy element.

Templates

Emails can be themed using the email TWIG template, which supports suggestions as follows:

• email--TYPE--SUBTYPE--ENTITY-ID
• email--TYPE--SUBTYPE
• email--TYPE
• email

TYPE corresponds to $module on the old mail system, and SUBTYPE corresponds to $key. See EmailInterface for full descriptions. For example to set a template for user password reset emails the template would be email--user--password-reset.html.twig.

By default (coming from the pre-installed "Wrap and Convert" Mailer policy set for all emails), the email is wrapped in a second template email-wrap, with suggestions in the same way. It provides a variable is_html so plain text emails can be wrapped differently

Email Body Policy

You can use TWIG syntax directly in the Body Email Policy. For an example, see the default policy for update status notify messages which contains a for loop.

CSS

By default, this module adds CSS from the 'email' library in the selected theme. To use this, create a libraries.yml file in your theme and add a section like this

email:
  css:
    theme:
      css/mail.css: { preprocess: false }

(Please note, that since Drupal >= 10.1.0 the additional preprocess: false is needed, see #3371042: Drupal 10.1.0 new aggregation breaks InlineCssEmailAdjuster for details.)