Groundmail with NestJS

Use nestjs-groundmail to register a Groundmail client once and inject it into any NestJS provider. It works with NestJS 10, 11 and 12, in CommonJS and ESM apps.

1. Install

npm install nestjs-groundmail

export GROUNDMAIL_API_KEY=gm_your_key_here

2. Register the module

// app.module.ts
import { Module } from '@nestjs/common'
import { GroundmailModule } from 'nestjs-groundmail'

@Module({
  imports: [GroundmailModule.forRoot({ apiKey: process.env.GROUNDMAIL_API_KEY, isGlobal: true })],
})
export class AppModule {}

To read the key from @nestjs/config, use forRootAsync:

GroundmailModule.forRootAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({ apiKey: config.getOrThrow('GROUNDMAIL_API_KEY') }),
  isGlobal: true,
})

3. Send an email

// receipts.service.ts
import { Injectable } from '@nestjs/common'
import { InjectGroundmail, type Groundmail } from 'nestjs-groundmail'

@Injectable()
export class ReceiptsService {
  constructor(@InjectGroundmail() private readonly groundmail: Groundmail) {}

  sendReceipt(to: string) {
    return this.groundmail.emails.send({
      from: 'Acme <receipts@yourdomain.com>',
      to,
      subject: 'Your receipt',
      html: '<p>Thanks for your purchase.</p>',
    })
  }
}

The injected client is the full Node SDK, so templates, idempotency keys, scheduling, domains and webhooks are all available.

Options

Option	Purpose
`apiKey`	Groundmail API key. Falls back to `GROUNDMAIL_API_KEY`
`baseUrl`	Override the API base URL
`isGlobal`	Make the client injectable in every module
`client`	Use an existing `Groundmail` instance (tests)

You can also inject by token with @Inject(GROUNDMAIL_CLIENT).

Source

Groundmail/nestjs-groundmail