Easy Email
A simple HTML email system for Drupal that provides email templates, token replacement, attachments, email logging, and the ability to override system emails.
easy_email
Install
composer require 'drupal/easy_email:^3.0'
Overview
Easy Email is an HTML email system designed to be as simple as possible to configure while providing a robust set of features. Unlike other HTML email modules that require significant configuration and in-depth knowledge of Drupal's email MIME processing, Easy Email handles everything out of the box with sensible defaults.
The module provides a complete email management solution including configurable email templates with token replacement, support for To/CC/BCC recipients, customizable sender information, HTML and plain text body options, dynamic attachments using tokens or file paths, and comprehensive email logging with user account linking. The entity-based architecture allows developers to use standard lifecycle hooks to alter or extend email processing.
Email templates are fieldable, allowing custom fields to be added for specific use cases (e.g., adding an entity reference field for Drupal Commerce orders to access order-derived tokens). The module includes submodules for overriding core and contrib module emails (Easy Email Overrides) and for Drupal Commerce integration (Easy Email Commerce).
Features
- Token replacement for all email fields including recipients, sender, subject, body, and attachments
- Support for To, CC, and BCC recipients with automatic user account linking
- Customizable sender name, address, and reply-to address per template
- HTML body with optional inbox preview text (hidden in body but visible in email client inbox preview)
- Optional plain text body that can be entered manually or auto-generated from HTML
- Dynamic attachments using tokens, relative paths, or URIs with security validation
- Comprehensive email log containing all sent emails with full content preview
- Automatic linking of logged emails to user accounts for easy tracking
- Entity-based architecture supporting standard Drupal lifecycle hooks (hook_entity_presave, hook_entity_update, etc.)
- Fieldable email templates for adding custom fields per use case
- Unique key pattern to prevent duplicate emails
- Automatic email purging based on configurable retention periods
- Email preview functionality for templates before sending
- Revision support for email entities with revert and delete capabilities
- Attachment security controls including path whitelisting, extension/MIME type blocking, and size limits
- Integration with Drupal Symfony Mailer or Symfony Mailer Lite for HTML email delivery
- Drush command for manual email purging
- Override system for replacing core and contrib module emails with Easy Email templates
- Drupal Commerce integration for order-related email templates
Use Cases
Transactional email notifications
Create email templates for common transactional notifications like order confirmations, password resets, or account updates. Add entity reference fields to templates to access related entity data through tokens. Configure automatic saving to maintain a complete email audit trail.
Replace Drupal core user emails
Enable the Easy Email Overrides submodule to replace core user module emails with custom HTML templates. Override password reset emails, welcome emails, account activation notices, and other user-related communications while maintaining Drupal's security features.
Commerce order receipts
Enable the Easy Email Commerce submodule to create branded HTML order receipt emails. Access order data, line items, customer information, and pricing through Commerce-specific tokens. Configure per-store or per-order-type email templates.
Marketing campaign emails
Create templates for marketing communications with custom fields for campaign tracking. Use the unique key pattern feature to prevent duplicate sends. Leverage the email log to track delivery and link emails to recipient user accounts.
System notification emails
Build templates for admin notifications, content moderation alerts, or system status emails. Use token replacement for dynamic content and configure automatic purging to manage database growth.
Multi-recipient personalized emails
Send personalized emails to multiple recipients using unsafe tokens that evaluate per-recipient. The module automatically handles splitting emails when per-user personalization is needed while maintaining a single email record for logging.
Tips
- Use the unique key pattern to prevent sending duplicate emails - combine entity IDs and timestamps for reliable deduplication
- Add custom entity reference fields to templates for accessing related data through tokens (e.g., order reference for Commerce emails)
- Enable email logging selectively per template - high-volume templates may not need permanent storage
- Use the preview functionality to test token replacement before sending
- Configure attachment security carefully - the default blocked extensions protect against common attack vectors
- Use Drush commands for bulk purging during off-peak hours to avoid cron timeouts
- Create theme template suggestions (e.g., easy-email-body-html--[bundle].html.twig) for per-template styling
Technical Details
Admin Pages 12
/admin/structure/email-templates/templates
Manage email templates. View, create, edit, delete, and preview email templates. Each template defines the default recipients, sender information, subject, body content, attachments, and storage settings for a type of email.
/admin/structure/email-templates/templates/add
Create a new email template. Initial form captures only the label and machine name. After saving, the full template configuration form is displayed.
/admin/structure/email-templates/templates/{easy_email_type}/edit
Configure all aspects of an email template including recipients, sender, content, attachments, and storage settings.
/admin/structure/email-templates/templates/{easy_email_type}
Preview how an email template will render. Shows headers, inbox preview, HTML body, and plain text body in an interactive preview interface with resizable sections.
/admin/structure/email-templates/settings
Configure global Easy Email settings including automatic purging, attachment security, and report visibility.
/admin/structure/email-templates/theme
Configure Easy Email Theme integration. Allows enabling a dedicated theme for email rendering.
/admin/reports/email
View log of all saved emails sent from the website. Lists email ID, label, template type, recipients, creation date, sent status, and provides view/edit/delete operations.
/admin/reports/email/{easy_email}
View complete details of a sent or unsent email including status, sent time, headers, inbox preview, HTML body, plain text body, and attachments.
/admin/reports/email/add/{easy_email_type}
Manually create and send an email using a template. Allows customizing all template fields and optionally sending or saving the email.
/admin/structure/email-templates/overrides
Manage email overrides that replace core and contrib module emails with Easy Email templates. List view shows configured overrides with edit/delete operations.
/admin/structure/email-templates/overrides/add
Create a new override to replace a system email with an Easy Email template.
/admin/structure/email-templates/overrides/{easy_email_override}/edit
Configure parameter mapping and field copying for an email override.
Permissions 16
Hooks 1
hook_easy_email_type_delete
React to deletion of an Easy Email template type. Used by easy_email_override to clean up related overrides.
Drush Commands 1
drush easy_email:purge_emails
Purge Easy Email entities based on template configuration or specified criteria
Troubleshooting 6
Verify that Drupal Symfony Mailer Lite or Drupal Symfony Mailer is installed and configured. Check that the mail system is properly configured. Review the email log at /admin/reports/email to see if emails are being created but not sent.
Check global attachment settings at /admin/structure/email-templates/settings. Verify paths are in allowed_attachment_paths list. Ensure file extensions and MIME types are not in blocked lists. Check that files exist at specified paths and are readable.
Verify tokens are correct by using the token browser in the template edit form. Ensure related entity reference fields are populated when creating emails. Check that token module is installed and enabled.
Confirm the Easy Email Overrides submodule is enabled. Verify the override is configured at /admin/structure/email-templates/overrides. Check parameter mapping configuration. Individual overrides take precedence over module-level overrides.
Configure automatic purging in template settings (Email storage > Automatic deletion). Enable cron-based purging in global settings. Use the Drush command for manual purging: drush easy_email:purge_emails
Enable 'Generate plain text body from HTML body' in the template settings. Ensure the HTML body field contains content. Check that html2text conversion is working properly with your mailer module.
Security Notes 7
- Attachment paths are validated against a whitelist - only files matching allowed_attachment_paths patterns can be attached
- Dangerous file extensions (exe, php, js, etc.) are blocked by default to prevent email-based attacks
- MIME type validation provides additional security layer beyond extension checking
- Maximum attachment size limits prevent resource exhaustion attacks
- Email entity access is controlled through granular permissions - configure carefully for multi-user sites
- The unique key pattern helps prevent email flooding by rejecting duplicate submissions
- XSS filtering is applied to plain text body content before rendering