Groundmail with Node.js

Use the Node SDK in Express, Fastify, workers, cron jobs, queue consumers, or any other server runtime where your API key can stay private.

1. Install the SDK

npm install groundmail

2. Configure your API key

export GROUNDMAIL_API_KEY=gm_your_key_here

3. Send an email

import { Groundmail } from 'groundmail'

const tx = new Groundmail(process.env.GROUNDMAIL_API_KEY!)

const result = await tx.emails.send({
  from: 'ops@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your receipt',
  html: '<p>Thanks for your purchase.</p>',
})

console.log(result.id, result.status)

Nodemailer transport

Many Node apps and tools (Payload, Auth.js email, Strapi, Ghost, and custom apps) accept a Nodemailer transport. Use ours so existing transporter.sendMail(...) calls hit Groundmail over HTTP (not SMTP).

Dedicated package: groundmail-nodemailer (transport source of truth; also re-exported as groundmail/nodemailer).

npm install groundmail-nodemailer groundmail nodemailer

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',
    // 'X-Groundmail-Scheduled-At': '2030-01-01T00:00:00Z',
  },
})

X-Groundmail-Tag uses name=value. Pass an array of header values for multiple tags. Custom non-reserved headers are forwarded to the API headers field. Attachments must include inline content (Buffer or string); path / href are not supported yet.

Better Auth

Dedicated package (preferred for discoverability):

npm install groundmail-better-auth groundmail better-auth

import { createBetterAuthEmail } from 'groundmail-better-auth'

Same helper is also exported as groundmail/better-auth. Full setup: Better Auth email.

Auth.js / NextAuth

npm install groundmail-authjs groundmail next-auth

import Groundmail from 'groundmail-authjs'

Same provider is also exported as groundmail/authjs. Full setup: Auth.js / NextAuth email.

React Email

Author components with React Email, then pass them to the Node SDK’s react option:

npm install groundmail @react-email/render react

await tx.emails.send({
  from: 'ops@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  react: WelcomeEmail({ name: 'Ada' }),
})

Full walkthrough (Next.js, CLI template push, troubleshooting): Send React Email.