# 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](#drupal-commerce), order receipts.

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](#symfony-mailer-module) module instead.

---

## Prerequisites

- A Groundmail account with a [verified sending domain](https://docs.groundmail.dev/domains).
- 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](https://docs.groundmail.dev/smtp).
- 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](https://docs.groundmail.dev/emails) 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 {#symfony-mailer-module}

The contributed [Symfony Mailer](https://www.drupal.org/project/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_…`) |

4. 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}

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:

```text
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:

```bash
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](https://docs.groundmail.dev/testing#simulator-addresses). 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](https://docs.groundmail.dev/domains) 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](https://docs.groundmail.dev/suppressions), and create a [webhook](https://docs.groundmail.dev/webhooks) 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](https://docs.groundmail.dev/sending-limits).

---

## Related

- [SMTP relay](https://docs.groundmail.dev/smtp)
- [Symfony Mailer](https://docs.groundmail.dev/frameworks/symfony)
- [Testing](https://docs.groundmail.dev/testing)
- [Webhooks](https://docs.groundmail.dev/webhooks)