Works with NestJS 10, 11 and 12, in CommonJS and ESM apps.

Install

npm install nestjs-groundmail

GROUNDMAIL_API_KEY=gm_your_key_here

Usage

// 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 {}

// 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 <[email protected]>',
      to,
      subject: 'Your receipt',
      html: '<p>Thanks for your purchase.</p>',
    })
  }
}

The injected client is the full groundmail SDK: emails, templates, domains, webhooks and suppressions.

Config from ConfigService

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

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

Inject by token with @Inject(GROUNDMAIL_CLIENT) if you prefer it to the decorator.

Contributing

Found a bug or want something added? Open an issue. This code is published here on each release, so we port fixes rather than merging pull requests directly. The HTTP client itself is the groundmail package.

Why Groundmail

• Our own mail servers and IP space. Your password resets and receipts don't share a pool with bulk marketing senders.
• Transactional email only. No newsletters or cold outreach on the platform, which keeps the sending reputation clean.
• Start free. 3,000 emails a month on the Free plan; Pro is 50,000 emails for $20/month. Dedicated IPs on Scale.
• Built for code and for agents. REST API, SMTP, SDKs for Node, Python, Go, PHP and Ruby, a CLI, and an MCP server for Claude, ChatGPT and Cursor.

All Groundmail libraries

| Use | Package | |-----|---------| | Node.js / TypeScript | groundmail on npm | | Python (Django), Go, Ruby (Rails Action Mailer) | Groundmail/groundmail-sdks | | PHP | Groundmail/groundmail-php | | Laravel | Groundmail/groundmail-laravel | | Symfony Mailer | Groundmail/groundmail-symfony-mailer | | Nodemailer | Groundmail/groundmail-nodemailer | | NestJS | Groundmail/nestjs-groundmail | | Strapi | Groundmail/strapi-provider-email-groundmail | | Medusa | Groundmail/medusa-notification-groundmail | | AdonisJS | Groundmail/adonisjs-groundmail | | Phoenix (Swoosh) | Groundmail/swoosh_groundmail | | CLI | groundmail-cli on npm | | MCP server (Claude, ChatGPT, Cursor) | Groundmail/groundmail-mcp | | Agent skills and Claude Code plugin | Groundmail/groundmail-skills | | Email templates (React Email, MJML, HTML) | Groundmail/email-templates |

Website · Docs · Pricing · Sign up free