Install the SDK
npm install groundmailConfigure your API key
export GROUNDMAIL_API_KEY=gm_your_key_hereSend 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 nodemailerimport 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-authimport { 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-authimport 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 reactawait 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.