# Vendure email with Groundmail

Send Vendure email through Groundmail by giving the EmailPlugin an SMTP transport that points at the Groundmail SMTP relay. Vendure's default email handlers (order confirmation, email address verification, password reset and email address change) and any handlers you add then go out from your own domain.

---

## 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).
- A Vendure server with `@vendure/email-plugin` installed.

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

---

## Configure the EmailPlugin

```ts
// vendure-config.ts
import { EmailPlugin, defaultEmailHandlers } from '@vendure/email-plugin'

export const config: VendureConfig = {
  // ...
  plugins: [
    EmailPlugin.init({
      handlers: defaultEmailHandlers,
      // ...keep your existing templateLoader and other options
      transport: {
        type: 'smtp',
        host: 'smtp.groundmail.dev',
        port: 587,
        secure: false,
        auth: {
          user: 'groundmail',
          pass: process.env.GROUNDMAIL_SMTP_PASSWORD,
        },
      },
      globalTemplateVars: {
        fromAddress: '"Your Store" <orders@yourdomain.com>',
      },
    }),
  ],
}
```

Set `GROUNDMAIL_SMTP_PASSWORD` to your SMTP credential (`gmsmtp_…`).

- **`secure: false` on port 587** makes the connection upgrade with STARTTLS, which is what the relay expects. Don't set `secure: true` or use port 465.
- **`fromAddress`** must be on your verified domain. Vendure's default templates send every email from it.
- **`logging: true`** on the transport logs the SMTP conversation while you set it up.

If `devMode: true` is set, Vendure writes emails to files instead of sending them through `transport`. Turn it off, or set it from an environment variable, for the environment that should send.

---

## Test it

Groundmail's simulator addresses work over SMTP and never reach a real inbox. Register a customer in your storefront, or place a test order, 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).

Vendure sends email from its job queue, so the worker process must be running for anything to go out.

---

## Troubleshooting

**Nothing is sent and there's no error.** Check the Vendure worker is running, and that `devMode` is off.

**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 the TLS handshake fails.** Check the host is `smtp.groundmail.dev`, the port is `587` and `secure` is `false`. If your host blocks outbound port 587, use `2525` with the same settings.

**The message is rejected because of the From address.** `fromAddress` 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

- [Vendure plugin](https://docs.groundmail.dev/frameworks/vendure): send through the API instead of SMTP
- [SMTP relay](https://docs.groundmail.dev/smtp)
- [Medusa](https://docs.groundmail.dev/frameworks/medusa)
- [Testing](https://docs.groundmail.dev/testing)
- [Webhooks](https://docs.groundmail.dev/webhooks)