GroundmailDocs
Markdown

Drupal and Drupal Commerce email with Groundmail

Send Drupal email through Groundmail by pointing Drupal's mailer at the Groundmail SMTP relay. This covers account emails (registration, password reset, email verification), contact forms and, with Drupal Commerce, order receipts.

Updated Nov 14, 20264 min read

Drupal 10.2 and later include a Symfony Mailer backend that reads an SMTP connection from the mailer_dsn setting. On older sites, or if you prefer an admin screen, use the contributed Symfony Mailer module instead.

Prerequisites

  • A Groundmail account with a verified sending domain.
  • An SMTP credential: in the Groundmail dashboard, open SMTP and choose Create SMTP credential. The password (gmsmtp_…) is shown once, so copy it. See SMTP relay.
  • Access to the site's settings.php, or admin access to install a module.

Everything Drupal sends through the relay goes out as transactional email, so use it for account, order and notification email. Send opt-in newsletters through the API with category: "newsletter" once your account is approved, and never send cold email.

Option 1: Drupal core (10.2 and later, 11)

Core still sends with PHP's mail() by default. Switch it to the Symfony Mailer backend and give it the relay's connection in settings.php:

PHP
// settings.php
$config['system.mail']['interface'] = ['default' => 'symfony_mailer'];
$config['system.mail']['mailer_dsn'] = [
  'scheme' => 'smtp',
  'host' => 'smtp.groundmail.dev',
  'port' => 587,
  'user' => 'groundmail',
  'password' => getenv('GROUNDMAIL_SMTP_PASSWORD'),
  'options' => [],
];

Set GROUNDMAIL_SMTP_PASSWORD to your SMTP credential (gmsmtp_…) in the server environment, so the password stays out of version control. On port 587 the smtp scheme upgrades the connection with STARTTLS, which is what the relay expects; there is no separate TLS setting.

Drupal labels this backend "Symfony mailer (Experimental)". It is the backend core's mailer_dsn setting is built for. If you use the Mail System module to pick a backend per module, choose it there instead of setting interface in settings.php.

Match the sender. Go to Configuration, then System, then Basic site settings, and set Email address to an address on your verified domain, such as noreply@yourdomain.com. Drupal sends account emails from it.

Option 2: Symfony Mailer module

The contributed Symfony Mailer module (1.x) has its own transport settings in the admin:

  1. Install and enable the module with Composer and Drush, or under Extend.
  2. Go to Configuration, then System, then Mailer, and open Transport.
  3. Add an SMTP transport and fill in:
Field Value
Host name smtp.groundmail.dev
Port 587
User name groundmail
Password Your SMTP credential (gmsmtp_…)
  1. Leave Perform TLS peer verification on, save, and make it the default transport.

The module's 2.x branch has been renamed and reorganised; if your admin screens differ, match the same host, port, username and password to the fields you see.

Drupal Commerce

Drupal Commerce sends its order receipt through Drupal's mail system, so once Option 1 or 2 is in place, receipts go through Groundmail.

  • Sender. Receipts come from the store's Email field (go to Commerce, then Configuration, then Stores, and edit the store). Set it to an address on your verified domain. If it's empty, Drupal uses the site email address.
  • Turn receipts on. Edit the order type (for example Commerce, Configuration, Order types, Default) and check Email the customer a receipt when an order is placed. Send a copy of the receipt to this email adds a store copy.

Test it

Groundmail's simulator addresses work over SMTP and never reach a real inbox. Request a password reset for a test user whose email is:

delivered@simulator.groundmail.dev

For Drupal Commerce, place a test order with that address as the order email. Then confirm in Groundmail: open Emails in the dashboard, or run:

Terminal
curl "https://api.groundmail.dev/emails?limit=5" \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY"

The email appears with the status delivered and "test": true. Use bounce@simulator.groundmail.dev to see a hard bounce. The full list is in Testing. Drupal logs send errors under Reports, then Recent log messages.

Troubleshooting

Email still goes out through PHP mail(). The mailer_dsn setting only applies to the symfony_mailer backend. Check $config['system.mail']['interface'] (or Mail System) selects it, and clear the cache with drush cr.

Authentication failed. The username must be exactly groundmail, and the password must be the SMTP credential (gmsmtp_…), not an API key (gm_…).

Connection timed out or refused. Check the host is smtp.groundmail.dev and the port is 587. If your host blocks outbound port 587, use 2525 with the same settings.

The message is rejected because of the From address. The site email address and the Commerce store email must use a verified domain on your account. Until then you can only send from the sandbox sender, and only to your own account email.

A recipient never receives the email. The address may be on your suppression list, usually after a hard bounce. See Suppressions, and create a webhook for email.bounced to get notified.

Sends are deferred. A new account has a daily ramp-up limit, and the Free plan has a daily limit. The relay replies with a temporary error and a retry time. See Sending limits.

Was this page helpful?