GroundmailDocs
Markdown

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.

Updated Nov 14, 20262 min read

Prerequisites

  • A Groundmail account with a verified sending domain.
  • 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.
  • 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

TypeScript
// 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:

delivered@simulator.groundmail.dev

Then confirm in Groundmail: open Emails in the dashboard, or run:

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

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 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, and create a webhook 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.

Was this page helpful?