SMTP Authentication Support
Allows Drupal to send emails through an external SMTP server instead of using the default PHP mail() function.
smtp
Install
composer require 'drupal/smtp:8.x-1.4'
composer require 'drupal/smtp:8.x-1.2'
Overview
The SMTP Authentication Support module enables Drupal to send emails directly to an SMTP server of your choice, instead of using the default PHP mail() function. This is essential for sites that need authenticated SMTP for outgoing mail, or those hosted in environments where PHP mail() is unreliable or unavailable.
The module integrates with the PHPMailer library to provide robust email delivery capabilities, supporting SSL/TLS encryption, authentication, HTML emails, file attachments, and backup SMTP servers. It can be configured through an administrative interface or via settings.php for environment-specific deployments.
Key capabilities include connection testing, email rerouting for development environments, configurable logging levels, SMTP keep-alive for batch operations, and automatic TLS negotiation. The module also provides migration support from Drupal 7 and integrates with the Mail System module for advanced mail routing scenarios.
Features
- Send all site emails through an external SMTP server with optional authentication
- Support for SSL and TLS encryption protocols with automatic TLS negotiation
- Backup SMTP server configuration for failover scenarios
- HTML email support with automatic plain-text conversion
- File attachment handling for emails sent via SMTP
- Email rerouting feature to redirect all outgoing mail to a test address
- Built-in connection testing to verify SMTP server connectivity
- Configurable logging levels (Emergency through Debug) for troubleshooting
- SMTP keep-alive option to maintain persistent connections for batch email operations
- Environment-specific configuration through settings.php overrides
- Debug mode with detailed SMTP server response logging
- Integration with Mail System module for advanced mail routing
- Migration path from Drupal 7 SMTP module configurations
- Configurable timeout settings for SMTP operations
- Custom hostname and HELO string configuration for SMTP handshake
Use Cases
Sending emails through Gmail
Configure SMTP to use Gmail's servers for outgoing mail. Use smtp.gmail.com as the server, port 587 with TLS protocol, and your Gmail credentials. Note that Gmail requires OAuth2 for newer accounts, which is not currently supported by this module. For accounts that support it, you may need to enable 'Less secure app access' or use an App Password.
Office 365 / Exchange Online integration
Send emails through Microsoft's Office 365 SMTP servers. Use smtp.office365.com as the server, port 587 with TLS, and your Office 365 email and password. Note that the From Name field may be ignored by Office 365.
Development environment email testing
Use the reroute address feature to redirect all outgoing emails to a developer's address during testing. This prevents accidental emails to real users while allowing email functionality testing.
High-volume email sending
Enable the SMTP keep-alive feature when sending batch emails (newsletters, notifications) to maintain a persistent connection and improve performance by avoiding repeated connection overhead.
Secure credential management
Store SMTP credentials in settings.php using environment variables instead of the database. This keeps sensitive passwords out of configuration exports and allows different credentials per environment.
GoDaddy shared hosting
For GoDaddy shared hosting environments with firewall restrictions, use localhost as the SMTP server with port 25, no encryption, and no authentication to utilize GoDaddy's local mail relay.
Connection testing and diagnostics
Use the Test tab to verify SMTP connectivity before deploying. Enable debugging mode to see detailed SMTP server responses for troubleshooting connection issues.
Tips
- Store SMTP credentials in settings.php using environment variables for better security: $config['smtp.settings']['smtp_password'] = getenv('SMTP_PASSWORD');
- Use the reroute address feature in development to prevent sending emails to real users
- Enable keep-alive when sending batch emails to improve performance
- Set log level to Error for production, Debug only when troubleshooting
- The backup server is tried only if the primary server hostname cannot be resolved, not if authentication fails
- Auto TLS should be enabled for modern email providers but disabled for simple relay servers without encryption
- Test your SMTP configuration using the Test tab before going live
- Check the status report for SMTP connection status and PHPMailer version information
Technical Details
Admin Pages 2
/admin/config/system/smtp
Main configuration page for the SMTP module. Configure SMTP server settings, authentication credentials, email options, and debugging features. All settings can be overridden via settings.php for environment-specific configurations.
/admin/config/system/smtp/test
Send a test email to verify your SMTP configuration is working correctly. Useful for validating settings before deploying to production.
Permissions 1
Hooks 6
hook_mail
Implements hook_mail() to define the smtp-test mail key used for sending test emails from the configuration page.
hook_modules_installed
Disables SMTP mail system when the mailsystem module is installed, as mailsystem takes over mail routing.
hook_migration_plugins_alter
Adds mapping for SmtpMailSystem to SMTPMailSystem in the d7_system_mail migration for proper Drupal 7 migration support.
hook_help
Provides help text for the SMTP module including links to configuration and help topics.
hook_requirements
Checks SMTP requirements during runtime including PHPMailer library presence, version compatibility, and SMTP connection status.
hook_uninstall
Cleans up SMTP configuration and restores the previous mail system when the module is uninstalled.
Troubleshooting 8
Run 'composer require phpmailer/phpmailer:6.6.3' to install the correct version. The status report will show PHPMailer version and location.
PHP's openssl extension is not installed or enabled. Install openssl and restart your web server.
Gmail requires OAuth2 for most accounts. Try using an App Password if 2FA is enabled, or consider using a transactional email service instead.
Enable debugging mode in SMTP settings and set log level to Debug. Send a test email and check Recent log messages for detailed SMTP server responses.
GoDaddy shared hosting often blocks external SMTP connections. Use localhost server with port 25, no encryption, and no authentication to use GoDaddy's local mail relay.
SMTP debugging interrupts HTTP responses. Only enable debugging for manual test emails, then immediately disable it.
Settings are being overridden in settings.php. The form shows '(Overridden)' prefix in descriptions for such fields.
Check if Mail System module is installed - it takes over mail routing. Configure SMTP as the sender in Mail System settings instead.
Security Notes 6
- SMTP passwords are stored as plain text in Drupal configuration - use settings.php overrides with environment variables for production
- The 'administer smtp module' permission should be restricted to trusted administrators only
- Consider using dedicated transactional email services (SendGrid, Mailgun, Amazon SES) for production sites
- Enable TLS encryption whenever possible to protect credentials in transit
- Do not enable debugging in production as it exposes detailed server communication
- Restrict file permissions on settings.php (444 or 400) when storing credentials there