Sending Email from Drupal
Drupal core hands outgoing mail to PHP's mail(), which is not configured in the containers Gesso's Drupal
runs in. The result is silent failure: password resets, webform notifications and Drupal Commerce order mail
are generated but never delivered.
Gesso's Drupal sends mail over SMTP instead, using two modules:
| Module | Purpose |
|---|---|
drupal/symfony_mailer_lite | Sends mail through Symfony Mailer, adding SMTP support. |
drupal/mailsystem | Assigns the sender and formatter plugins used by each part of Drupal. |
Installing the modules is not enough on its own. Out of the box Mail System still routes mail to core's
php_mail plugin, and Symfony Mailer Lite still has its native (sendmail) transport enabled — so mail
keeps failing exactly as before. The configuration below is the part that actually switches delivery to SMTP.
Configuration
Four pieces of configuration are required:
| Config object | Value | Effect |
|---|---|---|
mailsystem.settings | defaults.sender and defaults.formatter = symfony_mailer_lite | Drupal stops using php_mail. |
symfony_mailer_lite.settings | default_transport: smtp | Sends mail through the SMTP transport. |
symfony_mailer_lite.symfony_mailer_lite_transport.smtp | plugin: smtp, connection details empty | The transport itself; every environment supplies its own server details. |
symfony_mailer_lite.symfony_mailer_lite_transport.native | status: false | Turns off the module's default native sendmail transport (see the warning below). |
Making SMTP the default transport is not enough on its own. Symfony Mailer Lite builds every enabled
transport, not just the default one, and the native transport rejects the sendmail path some containers
use — Lando's included. When that happens it takes SMTP down with it and every send fails with
Error creating transports: Unsupported sendmail command flags. Disabling native avoids this (upstream
issue #3394230).
In the Gesso demo these ship as install config in the gesso_demo profile
(web/profiles/gesso_demo/config/install/), so every deploy — which reinstalls the profile from scratch —
comes up with working mail. On a site you configure by hand, the same result is reachable through the UI at
/admin/config/system/symfony-mailer-lite/transport (add an SMTP transport, then Operations → set as
default), disable the PHP native sendmail transport on the same page (Operations → Disable), and set
sender and formatter to Symfony Mailer Lite at /admin/config/system/mailsystem. Then run drush cex.
Leave host, port and credentials blank in the exported config. settings.php fills them in from the
environment, which keeps secrets out of git, lets one config work everywhere, and means an environment that
has not been told where to send mail cannot inherit another environment's mail server.
Environment variables
| Variable | Notes |
|---|---|
SMTP_HOST | SMTP server host name. Required — without it there is no mail server to talk to. |
SMTP_PORT | SMTP port: 1025 for a local catcher, 587 for a real provider. |
SMTP_USER | SMTP user name (apikey for SendGrid). |
SMTP_PASSWORD | SMTP password or API key. Injected from the drupal-secrets Kubernetes secret. |
SMTP_VERIFY_PEER | Set to true for a real provider over TLS. |
SITE_MAIL | The site's "from" address. |
Each variable overrides the stored config only when it is set, so anything you leave unset keeps its configured value.
Per-environment behaviour
Locally. DDEV ships Mailpit (ddev mailpit) and the Lando config declares a MailHog service. Both are
already wired up — .ddev/config.yaml sets SMTP_HOST=localhost and lando.env sets SMTP_HOST=mailhog —
so mail is captured and cannot leave your machine. This relies on the native transport being disabled (as
the gesso_demo profile ships it) — on Lando, mail fails until it is.
Review and staging environments. values/drupal.mr.yaml and values/drupal.main.yaml set
mailhog.enabled: true, so the platform Helm chart deploys a MailHog alongside Drupal, and their configmaps
point SMTP_HOST at it. Read the captured mail at https://mailhog.<environment host>/ (the chart protects
it with basic auth). Nothing can reach a real inbox from a demo environment.
Production. values/drupal.production.yaml points the configmap at SendGrid — the same shared account
the Next.js frontends use through their GESSO_EMAIL_SERVER_* variables:
SMTP_HOST: "smtp.sendgrid.net"
SMTP_PORT: "587"
SMTP_USER: "apikey"
SMTP_VERIFY_PEER: "true"
The API key reaches Drupal as SMTP_PASSWORD in the drupal-secrets secret, built in .gitlab-ci.yml from
the GESSO_EMAIL_SERVER_PASSWORD CI variable, and the sender address as SITE_MAIL from GESSO_EMAIL_FROM.
Testing
drush php:eval "\Drupal::service('plugin.manager.mail')->mail('system', 'test', 'test@example.com', 'en', ['context' => ['subject' => 'Gesso mail test', 'message' => 'It works']]);"
The message should appear in the mail catcher immediately. For an end-to-end check, request a password reset
at /user/password and confirm that mail arrives too.
Troubleshooting
-
Nothing is delivered and nothing is logged — Mail System is probably still on
php_mail. Check/admin/config/system/mailsystem. -
Connection could not be established— the transport has no host, or one that isn't there. ConfirmSMTP_HOST/SMTP_PORTare set for that environment, and that the mail catcher is actually running. -
Error creating transports: Unsupported sendmail command flags— thenativetransport is still enabled. Disable it at/admin/config/system/symfony-mailer-lite/transport. -
TLS handshake errors against a real provider — set
SMTP_VERIFY_PEER=trueand use port587. -
Mail is delivered but lands in spam — the sending domain needs SPF/DKIM records for the provider, and
SITE_MAILmust be an address on that domain. -
Config changes vanish after a deploy — deploys reinstall the
gesso_demoprofile, so mail config has to live in the profile'sconfig/install/, not be set by hand on the running site. -
Check what a site is really using (config plus environment overrides):
drush config:get symfony_mailer_lite.symfony_mailer_lite_transport.smtp --include-overridden