# Groundmail with Vendure

Use [`vendure-plugin-groundmail`](https://www.npmjs.com/package/vendure-plugin-groundmail) as the email sender of the Vendure EmailPlugin (Vendure 2 and 3). Order confirmations, password resets and email address verification then go out through the Groundmail API. Vendure keeps rendering your templates; Groundmail sends them. If you'd rather not add a package, the EmailPlugin's built-in SMTP transport works too: see [Vendure over SMTP](https://docs.groundmail.dev/integrations/vendure).

## 1. Install

```bash
npm install vendure-plugin-groundmail
```

```bash
GROUNDMAIL_API_KEY=gm_your_key_here
```

## 2. Set up the EmailPlugin

Replace `EmailPlugin.init()` with `GroundmailEmailPlugin.init()`. It takes the same options (handlers, template loader, global template variables), without `transport`, plus `groundmail`:

```ts
// vendure-config.ts
import path from 'path'
import { VendureConfig } from '@vendure/core'
import { defaultEmailHandlers, FileBasedTemplateLoader } from '@vendure/email-plugin'
import { GroundmailEmailPlugin } from 'vendure-plugin-groundmail'

export const config: VendureConfig = {
  // ...
  plugins: [
    GroundmailEmailPlugin.init({
      handlers: defaultEmailHandlers,
      templateLoader: new FileBasedTemplateLoader(path.join(__dirname, '../static/email/templates')),
      globalTemplateVars: {
        fromAddress: '"Acme" <orders@yourdomain.com>',
        verifyEmailAddressUrl: 'https://shop.yourdomain.com/verify',
        passwordResetUrl: 'https://shop.yourdomain.com/password-reset',
        changeEmailAddressUrl: 'https://shop.yourdomain.com/verify-email-address-change',
      },
      groundmail: { apiKey: process.env.GROUNDMAIL_API_KEY },
    }),
  ],
}
```

The `fromAddress` must be on a domain you have [verified in Groundmail](https://docs.groundmail.dev/domains).

### Or set the sender yourself

If you already call `EmailPlugin.init()`, keep it and add two lines:

```ts
import { EmailPlugin } from '@vendure/email-plugin'
import { GroundmailEmailSender } from 'vendure-plugin-groundmail'

EmailPlugin.init({
  // handlers, templateLoader, globalTemplateVars as before
  transport: { type: 'none' },
  emailSender: new GroundmailEmailSender({ apiKey: process.env.GROUNDMAIL_API_KEY }),
})
```

## 3. What gets sent

Every email a handler generates is sent with:

- the rendered HTML, and the plain-text part when the handler sets one
- the handler's From, recipient, cc, bcc and reply-to (comma-separated lists become several recipients)
- attachments from `content` (a Buffer, a string or a stream) or from a `path` to a file, an `https://` URL or a `data:` URL

A failed send throws, so Vendure logs it, publishes an `EmailSendEvent` with `success: false` and retries the job like any other.

## Local development

With `devMode: true`, or the `file` or `testing` transport, emails go to the dev mailbox or your test callback as before and nothing reaches Groundmail. To run the real send path from a staging store without delivering anything, use a test key (`gm_test_…`): those emails land in your [test inbox](https://docs.groundmail.dev/test-inbox).

## Options

| Option | Purpose |
|--------|---------|
| `apiKey` | Groundmail API key. Falls back to `GROUNDMAIL_API_KEY` |
| `from` | From address when a handler sets none |
| `replyTo` | Reply-To when a handler sets none |
| `tags` | Tags added to every email, e.g. `{ app: 'shop' }` |
| `headers` | Headers added to every email |
| `baseUrl` | Override the API base URL |

## Source

[Groundmail/vendure-plugin-groundmail](https://github.com/Groundmail/vendure-plugin-groundmail)