Mime Mail
A MIME Mail component module that sends HTML emails with embedded images and attachments, supporting theme integration and user plaintext preferences.
mimemail
Install
composer require 'drupal/mimemail:^2.0'
Overview
Mime Mail is a comprehensive email module that enables Drupal to send MIME-encoded HTML emails with embedded images and file attachments. It serves as both a component module (API for other modules) and provides its own configuration interface.
The module transforms standard Drupal mail into rich HTML emails by MIME-encoding the message body, automatically embedding local images as MIME attachments, and including your theme's stylesheets for consistent branding. When a recipient prefers plaintext (configurable per-user via a boolean field), the HTML content is automatically converted to plain text.
Mime Mail supports template theming with suggestions based on the sending module and mail key, allowing site builders to create customized email templates for specific notification types. It also offers an optional CSS inlining feature (via the mimemail_compress submodule) to ensure email client compatibility with services like Gmail and Outlook 2007.
Features
- Sends MIME-encoded HTML emails with full support for embedded images and file attachments
- Automatically includes theme CSS stylesheets or uses a dedicated mail.css file for email styling
- Supports per-user plaintext preference via a configurable boolean field on user profiles
- Provides themeable email templates with suggestions based on module and mail key (mimemail-message--[module]--[key].html.twig)
- Automatically converts local image URLs to Content-ID references for inline embedding
- Supports both file path and dynamic content attachments with MIME type detection
- Handles RFC2822-compliant email address formatting with display names and UTF-8 encoding
- Option to link images externally instead of embedding to reduce email size
- Configurable sender name and email address override for site-wide consistency
- Advanced incoming message processing capability for mail-based workflows
Use Cases
Sending branded HTML newsletters
Use Mime Mail with a custom mail.css file in your theme to send visually consistent newsletters. The module automatically includes your theme's styles and can embed images directly in the email for offline viewing.
Transactional emails with attachments
Send order confirmations, invoices, or reports with PDF attachments. Use the attachments parameter in hook_mail() to include files by path or dynamically generated content.
User-preferred email format
Create a boolean field on user profiles (e.g., 'Prefer plaintext email') and configure Mime Mail to respect this preference. Users who enable it will receive plaintext versions of all emails.
Module-specific email templates
Create targeted email templates like mimemail-message--commerce--order-receipt.html.twig to customize the appearance of specific email types while keeping a consistent base template for others.
Testing email configuration
Enable the Mime Mail Example submodule to access a test form at /admin/config/system/mimemail/mimemail_example where you can send test emails with attachments to verify your mail configuration.
Tips
- Create a mail.css file in your theme's root directory for email-specific styling that won't affect your website appearance
- Use the mimemail-message--[module]--[key].html.twig naming pattern to create targeted templates for specific email types
- When embedding images, use stream wrappers like public://image.jpg instead of full URLs for reliable embedding
- Test emails with the Mime Mail Example submodule before deploying to production
- Consider the 'Link images only' option for newsletters to reduce email size and improve deliverability
Technical Details
Admin Pages 1
/admin/config/system/mimemail
Global configuration page for Mime Mail settings including sender information, styling options, and advanced features.
Permissions 2
Hooks 2
hook_mail
Standard Drupal mail hook. When using Mime Mail, the $params array can include additional keys for controlling the email format.
hook_mail_alter
Allows modules to alter outgoing mail before it is sent. Can be used to add attachments, modify headers, or change the message format.
Troubleshooting 5
Ensure Mail System is configured to use 'Mime Mail mailer' as both the formatter and sender. Check that 'Send plain text email only' is disabled in Mime Mail settings.
Use relative URLs or stream wrappers (public://) for images instead of absolute URLs. Check that 'Link images only' is disabled. Only files in the public files directory can be embedded unless the sender has 'send arbitrary files' permission.
Some email clients (Gmail, Outlook 2007) only support inline CSS. Consider enabling the mimemail_compress module to convert CSS to inline styles. Verify your mail.css file exists in the theme directory.
Enable 'Use simple address format' in Mime Mail settings if you don't have an SMTP solution installed. Windows servers require special handling for RFC2822 formatted addresses.
Check the 'Email format' setting and ensure the selected text format has 'Convert URLs into links' filter enabled with a sufficient maximum link length.
Security Notes 4
- The 'send arbitrary files' permission allows access to any file on the server including sensitive files like settings.php - grant only to highly trusted roles
- Incoming message processing (advanced setting) should only be enabled if you understand the security implications and have properly configured validation
- The message validation key for incoming messages should be kept secret and changed if compromised
- File attachments are restricted to the public files directory by default for security - this is intentional