SMTP for Drupal — site mail that arrives
By default, Drupal sends mail through the web server's PHP mail function: without authentication and without an established reputation. To Gmail and Outlook, such a message is barely distinguishable from spam — account activations and password reset emails that never arrive are the classic complaint.
The clean solution is Drupal's SMTP module. It replaces the default mail transport with a connection to an external SMTP server, without you having to change anything about your other modules or forms. The five fields below are all the module needs.
Why it goes wrong without a relay
A Drupal site is often more than a website: a member portal, an intranet, an application form for an association or a public body. That is exactly where mail is indispensable — someone who registers and gets no activation email gives up, and nobody tells you. The mail does leave, but it is rejected along the way because nothing proves it comes from your domain.
Setting up SMTP in Drupal
Collect your details
Log in to your 2mail account and retrieve your SMTP server, username and password there.
Fill them in inside Drupal
Install and enable Drupal's SMTP module. In that module's settings you switch it on as the mail transport, fill in host, port, encryption, username and password, and set the sender address to your own domain. The module has a built-in test email: send it to an external address at a major provider, not to an address on your own server.
Authenticate your domain
Make sure SPF, DKIM and DMARC are set correctly for your domain, so recipients can verify that the mail comes from you.
Test
From your platform, send a test message to an address at a major provider and check that it arrives in the inbox and not in the spam folder.
The fields Drupal asks for
Every platform names them slightly differently, but it is always the same five. The actual values are tied to your account and can be found in your 2mail account — take them from there, so you are sure to use the right ones.
| Field | What you enter |
|---|---|
| SMTP server (host) | The server name from your 2mail account. |
| Port | The port that matches your chosen encryption; your account shows which one. |
| Encryption | TLS. Never send unencrypted — your credentials would otherwise travel in plain text. |
| Username | The SMTP login of your 2mail account. |
| Password | The matching password. Never use the password of an employee's mailbox. |
SMTP configuration for Drupal in code
Working examples for port 587 with STARTTLS, ready to copy. Replace the sender address with an address on your own domain and check the server name and login in your 2mail account. The password belongs in an environment variable — never in the code and never in version control.
Installing the SMTP module
The module's full name is SMTP Authentication Support, and it is installed with Composer like every Drupal module today. After that you will find its settings in the administration area, under the system configuration.
composer require drupal/smtp
drush en smtp -ySettings and password through settings.php
You can fill in everything in the module's form, but then the password ends up in the configuration — and, with a configuration export, in version control. An override in settings.php wins over the stored value, stays out of the export and lets you use a different login per environment. The password itself comes from an environment variable on the server. Choose TLS as the protocol: in this module that means STARTTLS, which belongs with port 587; the SSL option is for port 465.
// sites/default/settings.php (or settings.local.php per environment)
// Route all Drupal mail through the SMTP module.
$config['system.mail']['interface']['default'] = 'SMTPMailSystem';
$config['smtp.settings']['smtp_on'] = TRUE;
$config['smtp.settings']['smtp_host'] = 'relay.2mail.eu';
$config['smtp.settings']['smtp_port'] = '587';
$config['smtp.settings']['smtp_protocol'] = 'tls'; // "Use TLS" in the form = STARTTLS
$config['smtp.settings']['smtp_username'] = getenv('SMTP_USERNAME');
$config['smtp.settings']['smtp_password'] = getenv('SMTP_PASSWORD');
$config['smtp.settings']['smtp_from'] = 'noreply@example.com';
$config['smtp.settings']['smtp_fromname'] = 'Example';Checking with Drush
Overrides from settings.php do not show up in the form: it displays the stored value. So ask Drush what is actually in effect, and then send the test email the module offers at the bottom of its settings page. If that fails, the real cause is in the log, not on the screen.
drush cache:rebuild
# Which mail system is active, and which host does Drupal really use?
drush config:get system.mail interface.default --include-overridden
drush config:get smtp.settings smtp_host --include-overridden
# What the module logged about failed deliveries (needs the dblog module):
drush watchdog:show --type=smtpWhich emails Drupal sends
As soon as the relay is set up, all of these run through 2mail — you do not have to configure them one by one.
Pitfalls with Drupal
The module has to actually be the mailer
Drupal can run several mail systems side by side. If the SMTP module is installed but not switched on as the mail transport, everything keeps going through the PHP mail function and nothing changes. Check that first when the test email arrives but real mail does not.
Sender on your own domain
The site email address in the basic settings is used as the sender. Set it to an address on your own domain — the same domain SPF, DKIM and DMARC are configured for. A free address fails DMARC, however correct the SMTP details are.
Configuration export and passwords
If you use configuration management, the SMTP settings travel along in the export. If an import overwrites them with the values of a test environment, your live site suddenly sends with the wrong details. Keep the password out of the export and set it separately per environment.
Common error messages with Drupal
The messages you get when host, port, encryption or login are wrong — quoted literally, so you recognise them in your log, with the cause and the fix next to them.
| Message | Cause | Fix |
|---|---|---|
Unable to send email. Contact the site administrator if the problem persists. | This is Drupal's own generic message, which only says that sending failed. The actual SMTP error is in the log, under the type smtp. | Open the recent log messages in the administration area or use drush watchdog:show --type=smtp, and look there for one of the messages below. |
SMTP Error: Could not connect to SMTP host. | The server cannot reach the relay, or protocol and port do not match: SSL selected on port 587, a typo in the host, or a hosting provider that blocks outbound traffic on port 587. | Set the protocol to TLS and the port to 587. If it keeps failing, test from the server with openssl s_client -starttls smtp -connect relay.2mail.eu:587 and ask your host to open the port. |
SMTP Error: Could not authenticate. | The relay rejects the login: a wrong username or password, or an environment variable that is empty inside the web server, so that the override passes an empty password. | Check that getenv('SMTP_PASSWORD') returns a value inside the web server, and use the SMTP login from your 2mail account — not the password of a mailbox. |
SMTP Error: The following recipients failed: … | The login is fine, but the relay refuses the message when the recipient is given — in practice because the sender address is on a domain that is not linked to your 2mail account. Often the site email address is still an address from the hosting provider or a free address. | Set both the sender address in the module and the site email address in the basic settings to an address on a domain you have added in 2mail. |
A different platform?
SMTP is a standard protocol: any system that speaks SMTP — a CRM, an ERP, a custom application or a server — can send through 2mail using the same five fields.