Markdown

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.

Updated Nov 17, 20261 min read

Install the SDK

Terminal
npm install groundmail

Configure your API key

Terminal
export GROUNDMAIL_API_KEY=gm_your_key_here

Send an email

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

Terminal
npm install groundmail-nodemailer groundmail nodemailer
TypeScript
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):

Terminal
npm install groundmail-better-auth groundmail better-auth
TypeScript
import { createBetterAuthEmail } from 'groundmail-better-auth'

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

Auth.js / NextAuth

Terminal
npm install groundmail-authjs groundmail next-auth
TypeScript
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:

Terminal
npm install groundmail @react-email/render react
TypeScript
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.

Was this page helpful?