Drupal's default mail plugin hands messages to PHP's mail(), which on most hosting has no mail server behind it and, where it does, sends unauthenticated mail that fails SPF and DKIM checks. This guide routes Drupal's mail system through Postwing instead.
| Setting | Value |
|---|---|
| SMTP host | smtp.postwing.app |
| Port | 587 |
| Encryption | STARTTLS (the connection is upgraded to TLS before login) |
| Username | The login of an SMTP token for your domain |
| Password | The password of that token — shown once, when the token is created |
The long-standing module, with a settings form at /admin/config/system/smtp:
composer require drupal/smtp
drush en smtp -y Rather than filling in the form, override the settings in settings.php so the token never reaches exported configuration:
<?php
// settings.php — keep credentials out of the exported configuration.
$config['smtp.settings']['smtp_on'] = TRUE;
$config['smtp.settings']['smtp_host'] = 'smtp.postwing.app';
$config['smtp.settings']['smtp_port'] = '587';
$config['smtp.settings']['smtp_protocol'] = 'tls'; // 'tls' = STARTTLS, 'ssl' = port 465
$config['smtp.settings']['smtp_username'] = getenv('SMTP_USER');
$config['smtp.settings']['smtp_password'] = getenv('SMTP_PASS');
$config['smtp.settings']['smtp_from'] = 'noreply@your-domain.com';
$config['smtp.settings']['smtp_fromname'] = 'Acme';settings.php override with an environment variable keeps the token out of the repository. Built on Symfony Mailer, configured with a single DSN. A better fit if you already know Symfony's mailer:
composer require drupal/symfony_mailer_lite
drush en symfony_mailer_lite -y<?php
// settings.php — Symfony Mailer Lite takes a single DSN.
// The @ in the username must be URL-encoded as %40.
$config['symfony_mailer_lite.settings']['default_transport'] = 'smtp';
$config['symfony_mailer_lite.transport.smtp']['configuration']['dsn'] =
'smtp://token-login%40your-domain.com:your-token-password@smtp.postwing.app:587'; Note the %40 — the DSN is a URL, so the @ in the token login must be encoded.
Under Configuration → System → Basic site settings, set the site email to an address on your verified domain. If Drupal sends as one domain while DKIM and SPF are published on another, DMARC fails and the mail is filtered.
# Send a test message through Drupal's mail system
drush php:eval "\Drupal::service('plugin.manager.mail')->mail('system', 'test', 'you@example.com', 'en', [], NULL, TRUE);"
# Check what mail plugin is actually in use
drush config:get system.mail| Symptom | Cause and fix |
|---|---|
| Settings saved, mail still not sent over SMTP | Another module owns the mail plugin. Check drush config:get system.mail. |
| Connection timeout | Outbound port blocked. Use 8587 (tls) or 8465 (ssl). |
| Authentication failed | Wrong token login or password. |
| SSL handshake error | ssl on port 587 or tls on 465 — match them. |
| Mail arrives in spam | The site email is not on your verified domain. |
| Two SMTP modules enabled | They fight over the mail plugin. Disable all but one. |
For Drupal 10 and 11 either SMTP Authentication Support (drupal/smtp), which is the long-standing option with a simple settings form, or Symfony Mailer Lite, which uses Symfony Mailer under the hood and configures a transport with a single DSN. Both work; do not enable both at once, since each overrides the mail plugin.
Check drush config:get system.mail. Another module — Mime Mail, Swift Mailer, or a leftover from a previous setup — may still own the mail plugin, in which case the SMTP module's settings are never consulted. Only one mail plugin can be active per key.
In settings.php, read from an environment variable, rather than in the module's settings form. Values entered in the form are stored in configuration, which usually gets exported to code and committed — putting the credential in your repository.
Use tls with port 587 — in this module tls means STARTTLS. Use ssl with port 465 for implicit TLS. Mismatching the two is the most common cause of a connection failure.
Usually the site's From address. Drupal defaults to whatever is in Basic site settings, which is often left as an address on a different domain. Set it to an address on the domain you verified so DKIM and SPF align.
Enable the SMTP module's debugging option, then read the messages at /admin/reports/dblog. Turn it off once the connection works — the debug log includes the authentication exchange.