Groundmail for NestJS

A NestJS module for the Groundmail transactional email API.
Register it once, then inject a ready Groundmail client into any provider.

Docs · Get a free account · groundmail.dev

---

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 <receipts@yourdomain.com>',
      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

• Mailboxes for your agents. Give an agent its own email address: it receives mail, replies in the thread and picks up sign-up codes on its own. No account needed to start. Agent mailboxes
• Each kind of mail on its own IPs. Transactional email (sign-in codes, password resets, receipts), product email and opt-in newsletters send from separate IPs, so your newsletter never shares a pool with your password resets. We run our own mail servers and never send cold outreach or bought lists.
• Start free. Free covers 3,000 emails a month. After that, pay as you go is $15 a month with 20,000 emails included, then from $0.70 per 1,000, less as you grow. Pricing
• 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