Skip to content

Latest commit

 

History

48 Commits

Folders and files

Repository files navigation

Groundmail

Groundmail for Nodemailer

A Nodemailer transport for the Groundmail transactional email API.
Keep transporter.sendMail(); deliver over the Groundmail HTTP API instead of SMTP.

npm License: MIT

Docs · Get a free account · groundmail.dev


Works anywhere Nodemailer does: Express apps, Payload, Auth.js email, Strapi, Ghost, background workers and custom stacks. Swap the transport and your existing sendMail calls keep working.

Install

npm install groundmail-nodemailer groundmail nodemailer
GROUNDMAIL_API_KEY=gm_your_key_here

Usage

import nodemailer from 'nodemailer'
import { createGroundmailTransport } from 'groundmail-nodemailer'

const transporter = nodemailer.createTransport(
  createGroundmailTransport({
    apiKey: process.env.GROUNDMAIL_API_KEY!,
  }),
)

await transporter.sendMail({
  from: 'ops@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your receipt',
  html: '<p>Thanks for your purchase.</p>',
  headers: {
    'X-Groundmail-Tag': 'campaign=welcome',
    'X-Groundmail-Idempotency-Key': 'receipt-123',
  },
})

The same transport is also exported from the main SDK as groundmail/nodemailer.

Headers

Header Purpose
X-Groundmail-Tag name=value tag (repeatable)
X-Groundmail-Idempotency-Key Send once, even when your code retries

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

Releases

Packages

Contributors

Languages