# Sylius email with Groundmail

Send Sylius store email through Groundmail. Sylius sends with Symfony Mailer, so you connect it with one `MAILER_DSN`. Order and shipment confirmations, account registration and verification, password reset and contact requests then go out from your own domain. These steps are for Sylius projects that use Symfony Mailer, as Sylius-Standard 1.14 and 2.x do.

There are two ways to connect:

- **SMTP**, with the Groundmail SMTP relay. 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**.

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

Sylius-Standard ships with `MAILER_DSN=null://null`, which sends nothing. Set it in `.env.local` (or your host's environment):

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

On port 587 the `smtp` scheme upgrades the connection with STARTTLS, which is what the relay expects. If your password contains characters such as `@`, `:` or `/`, URL-encode them in the DSN.

---

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

1. Install the transport:

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

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.

---

## Set the sender

Sylius sends from `no-reply@example.com` until you change it, and that address will be refused. Set the sender to an address on your verified domain:

```yaml
# config/packages/sylius_mailer.yaml
sylius_mailer:
  sender:
    name: Your Store
    address: orders@yourdomain.com
```

Clear the cache after changing `.env.local` or the config: `bin/console cache:clear`.

---

## Test it

Groundmail's simulator addresses never reach a real inbox. Register a customer, or place a test order in the shop, 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).

If your project routes email through Symfony Messenger, the messenger consumer must be running for email to go out.

---

## Troubleshooting

**Nothing is sent and there's no error.** Check `MAILER_DSN` isn't still `null://null` in the environment the app runs in, and clear the cache.

**`The "groundmail+api" scheme is not supported`.** The factory isn't registered. Check step 2 of Option 2 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 2).

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