# Shopware email with Groundmail

Send Shopware 6 store email through Groundmail. Order confirmations, order status and delivery updates, customer registration and password recovery emails, and every other mail template then go out from your own domain.

There are two ways to connect:

- **SMTP**, set in the admin or in `MAILER_DSN`. Nothing to install.
- **The API**, with the [`groundmail/symfony-mailer`](https://docs.groundmail.dev/frameworks/symfony) transport and a `groundmail+api://` DSN. Use it if your host blocks outbound SMTP ports.

---

## Prerequisites

- A Groundmail account with a [verified sending domain](https://docs.groundmail.dev/domains).
- For SMTP: 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).
- For the API: an API key (`gm_…`) from **API keys**, and shell access to run Composer.
- Admin access to Shopware.

Everything the store sends through Groundmail goes out as transactional email, so use it for order, account and notification email. Never send cold email.

---

## Option 1: SMTP in the admin

1. In the Shopware admin, go to **Settings**, then **System**, then **Mailer**.
2. Under **Preferred email agent**, choose **SMTP server**, and fill in:

| Shopware field | Value |
|----------------|-------|
| Host | `smtp.groundmail.dev` |
| Port | `587` |
| Username | `groundmail` |
| Password | Your SMTP credential (`gmsmtp_…`) |
| Encryption | `TLS` |
| Sender address | An address on your verified domain, for example `orders@yourdomain.com` |

3. Click **Save**.

**Encryption** set to `TLS` upgrades the connection on port 587 with STARTTLS, which is what the relay expects. Don't choose `SSL` or port 465, and don't choose **No encryption**: in Shopware it also turns off certificate checks.

---

## Option 2: SMTP with MAILER_DSN

To keep the credential out of the admin, set it in `.env.local` (or your host's environment):

```bash
MAILER_DSN=smtp://groundmail:gmsmtp_your_credential@smtp.groundmail.dev:587
```

Then go to **Settings**, **System**, **Mailer** and choose **Use environment's configuration**. Any other choice there overrides `MAILER_DSN`. If your password contains characters such as `@`, `:` or `/`, URL-encode them in the DSN.

---

## Option 3: The API with groundmail/symfony-mailer

Shopware sends email with Symfony Mailer, so the Groundmail transport plugs in with a DSN.

1. Install the transport in your Shopware project:

```bash
composer require groundmail/symfony-mailer
```

2. Register its factory so Symfony Mailer knows the `groundmail+api` scheme:

```yaml
# config/services.yaml
services:
  Groundmail\Symfony\Transport\GroundmailTransportFactory:
    tags: ['mailer.transport_factory']
```

3. Set the DSN in `.env.local`:

```bash
MAILER_DSN=groundmail+api://gm_your_key_here@default
```

4. Clear the cache (`bin/console cache:clear`), then go to **Settings**, **System**, **Mailer** and choose **Use environment's configuration**.

Use a [Send only](https://docs.groundmail.dev/api-keys) API key here. See [Symfony Mailer](https://docs.groundmail.dev/frameworks/symfony) for the transport's headers and options.

### Match the sender

Every option needs the sender on your verified domain. With the admin SMTP option, that's **Sender address**. Otherwise Shopware sends from the shop's email address under **Settings**, **Shop**, **Basic information**. Set it to an address on your verified domain.

---

## Test it

Groundmail's simulator addresses never reach a real inbox. Register a customer, or place a test order in the storefront, with the email:

```text
delivered@simulator.groundmail.dev
```

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).

Shopware sends some emails from its message queue, so make sure the message consumer (or the admin worker) is running.

---

## Troubleshooting

**`MAILER_DSN` is ignored.** Check **Preferred email agent** is **Use environment's configuration**, and clear the cache after changing `.env.local`.

**`The "groundmail+api" scheme is not supported`.** The factory isn't registered. Check step 2 of Option 3 and clear the cache.

**Authentication failed.** Over SMTP, the username must be exactly `groundmail` and the password must be the SMTP credential (`gmsmtp_…`), not an API key. Over the API, the DSN needs 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`, or switch to the API (Option 3).

**The message is rejected because of the From address.** The sender 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. 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)
- [Sylius](https://docs.groundmail.dev/integrations/sylius)
- [Testing](https://docs.groundmail.dev/testing)
- [Webhooks](https://docs.groundmail.dev/webhooks)