Drupal Symfony Mailer Lite
A lightweight email sending module that leverages Symfony Mailer library to send HTML and plain text emails through various transport methods including SMTP, Sendmail, and custom DSN configurations.
symfony_mailer_lite
Install
composer require 'drupal/symfony_mailer_lite:^2.0'
Overview
Drupal Symfony Mailer Lite is a modern email sending solution for Drupal that replaces the deprecated Swiftmailer module. It uses the Symfony Mailer component to provide reliable email delivery with support for multiple transport mechanisms.
The module offers a clean administrative interface for configuring email transports, message formatting options, and testing email delivery. It supports HTML emails with automatic CSS inlining using the CssToInlineStyles library, automatic generation of plain text alternatives using Html2Text, and embedding of images within email content.
Key capabilities include multiple transport configurations (SMTP, Sendmail, Native PHP mail, DSN, and Null for testing), themeable email templates with Twig, file attachments support compatible with MimeMail module, and seamless integration with the Mail System module for flexible mail routing.
Features
- Multiple email transport options: SMTP with TLS/SSL support, Sendmail, Native PHP mail function, custom DSN strings, and Null transport for development/testing
- HTML email support with automatic CSS inlining - transforms external CSS stylesheets into inline styles for better email client compatibility
- Automatic plain text alternative generation from HTML content using the Html2Text library for email clients that don't support HTML
- Embedded image support - allows embedding images directly in emails using the 'image:path' syntax with security validation
- Themeable email templates using Twig with support for module-specific and key-specific template overrides
- File attachment support compatible with both native format and MimeMail attachment format
- Multiple transport management with ability to set a default transport and switch between transports per-message
- Test email functionality to verify transport configuration is working correctly
- Migration support from Swiftmailer module - automatically imports existing Swiftmailer settings during installation
- Character set configuration with support for numerous character encodings including UTF-8, ISO-8859-x, and Asian character sets
- Integration with Mail System module for flexible mail formatter and sender configuration
Use Cases
Sending transactional emails via SMTP
Configure an SMTP transport with your email provider's credentials (e.g., SendGrid, Mailgun, Amazon SES, or your own SMTP server). Set it as default, then configure Mail System to use symfony_mailer_lite for desired modules. All outgoing emails will be sent through your SMTP server with proper authentication and TLS encryption.
HTML email with inline CSS styling
Create a custom email template in your theme as symfony-mailer-lite-email--mymodule.html.twig. Add a library definition in your theme's libraries.yml that includes CSS files. Reference the library in your theme.info.yml. The module will automatically fetch CSS from the library and inline it for maximum email client compatibility.
Embedding images in HTML emails
In your email body content, reference images using the special 'image:' prefix: <img src="image:/sites/default/files/logo.png">. The module validates that the image exists in the public files directory, then embeds it as a CID attachment, replacing the src with the appropriate cid: reference.
Development environment with disabled emails
Add a Null transport and set it as default in development environments. All emails will be processed but not actually sent, allowing you to test email generation without sending real messages. Review logs to verify email content.
Using third-party Symfony Mailer transports
For services like Mailchimp Transactional, Postmark, or other providers with Symfony Mailer packages, install the package via Composer and use the DSN transport type with the appropriate DSN string (e.g., 'postmark://ID@default'). This gives access to the full Symfony Mailer ecosystem.
Adding attachments to emails programmatically
Implement hook_symfony_mailer_lite_attach() to add file attachments to outgoing emails. Return an array of file objects with uri, filename, and filemime properties. Alternatively, pass attachments in the $params['files'] or $params['attachments'] array when calling MailManager::mail().
Migrating from Swiftmailer
Simply install and enable Symfony Mailer Lite while Swiftmailer is still installed. The module automatically imports your Swiftmailer transport configuration (SMTP or Sendmail) and message settings. Then update Mail System to use symfony_mailer_lite instead of swiftmailer, and finally uninstall Swiftmailer.
Specifying transport per email
When sending emails programmatically, you can specify a different transport by adding 'symfony_mailer_lite_transport' key to the message array with the transport ID. This allows routing certain emails through different transports (e.g., transactional vs marketing).
Tips
- Use the Test page to verify your transport configuration before relying on it for critical emails
- For development, use the Null transport to prevent accidentally sending emails while still testing email generation
- When using SMTP with authentication, store credentials securely and consider using environment variables via settings.php overrides
- Create module-specific email templates to customize the look of emails from different modules without affecting others
- The module supports the Symfony Messenger component for async email sending - install symfony/messenger for high-volume sites
- Check Drupal's Recent log messages after sending test emails to verify successful delivery or diagnose failures
- For maximum email client compatibility, keep HTML emails simple and rely on the CSS inlining feature rather than complex layouts
Technical Details
Admin Pages 4
/admin/config/system/symfony-mailer-lite/transport
Main administration page for managing email transports. Lists all configured transports showing their type, label, and default status. Allows adding new transports, editing existing ones, setting a transport as default, and deleting non-default transports.
/admin/config/system/symfony-mailer-lite/transport/add/{plugin_id}
Form for adding a new email transport. The available fields vary based on the selected transport type.
/admin/config/symfony-mailer-lite/message-settings
Configure default message formatting options including content type, text format conversion, plain text generation, and character set.
/admin/config/system/symfony-mailer-lite/test
Send a test email to verify that the email transport is configured correctly.
Permissions 1
Hooks 2
hook_symfony_mailer_lite_attach
Allows modules to add file attachments to outgoing emails. Called during the mail() method before sending.
hook_symfony_mailer_lite_transport_info_alter
Allows modules to alter the transport plugin definitions before they are cached.
Troubleshooting 6
Check that a default transport is configured and set. Navigate to /admin/config/system/symfony-mailer-lite/transport and verify at least one transport is marked as 'Default'. Also verify Mail System is configured to use symfony_mailer_lite for the sending module.
Verify username and password are correct. Some providers require app-specific passwords. Check if your SMTP server requires a specific port (587 for TLS, 465 for SSL, 25 for unencrypted). Temporarily disable TLS peer verification for debugging self-signed certificates.
Ensure your theme defines a 'symfony_mailer_lite' library with your CSS files. The library name must exactly match 'themename/symfony_mailer_lite'. CSS from this library will be automatically inlined into HTML emails.
Images must be located within the public files directory. Remote images or images outside the public directory are rejected for security. Check the Drupal logs for validation errors. Verify the image path uses the correct format: image:/path/to/file.png
Verify 'Generate alternative plain text version' is enabled in Message Settings. This requires the html2text/html2text Composer package. Check that emails are being sent as HTML (text/html content type).
This error appears when no active transports exist or the default transport has been deleted. Create a new transport and set it as default. If transports exist, verify they are enabled and the default_transport setting in symfony_mailer_lite.settings points to a valid transport ID.
Security Notes 6
- The 'administer symfony_mailer_lite configuration' permission is marked as 'restrict access' due to the sensitive nature of email transport configuration including SMTP credentials
- SMTP passwords are stored in configuration and may be visible to users with configuration export permissions
- Embedded images are validated to ensure they exist within the public files directory to prevent path traversal attacks
- The Sendmail transport validates the command to prevent command injection attacks
- TLS peer verification is enabled by default for SMTP connections - only disable in development environments with self-signed certificates
- Consider using environment-specific settings.php overrides for SMTP credentials rather than storing them in exportable configuration