groundmail

Official Node.js / TypeScript client for the Groundmail transactional email API.

npm install groundmail

export GROUNDMAIL_API_KEY=gm_your_key_here

import { Groundmail } from 'groundmail'

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

const email = await tx.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your receipt',
  html: '<p>Thanks for your purchase.</p>',
})

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

Azure managed identity (no API key)

On Azure, authenticate with the workload's managed identity instead of a key. Pass a token provider; the client caches the token until shortly before it expires and asks for a new one after a 401:

import { DefaultAzureCredential } from '@azure/identity'
import { Groundmail } from 'groundmail'

const credential = new DefaultAzureCredential()
const client = new Groundmail({ getToken: () => credential.getToken('https://api.groundmail.dev/.default') })

getToken may return a string or { token, expiresOnTimestamp }. Add the Groundmail app to your Entra tenant once (az ad sp create --id 0146ad5c-4051-4703-aece-e4edf9805d8e) and register the identity in the dashboard first: https://docs.groundmail.dev/authentication/azure-managed-identity

Testing

Use a test key (gm_test_…, create one with tx.apiKeys.create({ test: true }) or in the dashboard) to run sends through validation, templates and webhooks without delivering anything. Simulator addresses produce a specific outcome with any key and never leave Groundmail:

import { simulatorAddress } from 'groundmail'

await tx.emails.send({
  from: '[email protected]',
  to: simulatorAddress('bounce', 'signup-42'), // [email protected]
  subject: 'Bounce handling test',
  html: '<p>Simulated.</p>',
})
// status `bounced`, then an `email.bounced` webhook with `data.test: true`

Outcomes: delivered, bounce, block, complaint, suppressed, delayed. Details: https://docs.groundmail.dev/testing

Tenants

If you send email for your own customers, create one tenant per customer. Each tenant has its own domains, suppression list, stats, pause switch and daily limit, so one customer's bounces or complaints never affect the others. Tenants are included on the Scale and Dedicated plans.

await tx.tenants.create({ external_id: 'cus_123', name: 'Acme', daily_limit: 5000 })
await tx.tenants.domains.assign('cus_123', 'mail.acme.com')

await tx.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your invoice',
  html: '<p>Thanks!</p>',
  tenant: 'cus_123',
})

const { stats } = await tx.tenants.stats('cus_123', { days: 7 })
await tx.tenants.pause('cus_123', 'Unpaid invoice')
await tx.tenants.resume('cus_123')

tenant (your external id or the Groundmail id) also works on emails.list, domains.create and domains.list, suppressions, apiKeys.create (a key limited to one tenant) and emails.testWebhook. Webhook endpoints take tenants: ['cus_123'] to receive only those tenants' email events. Details: https://docs.groundmail.dev/tenants

DMARC monitoring

Free for every domain. Turn it on, publish the record it returns, and read sources, pass rates and whether it's safe to enforce once the daily reports arrive:

const { dmarc } = await tx.dmarc.enable('yourdomain.com') // or { apply: 'cloudflare' }
console.log(dmarc.dns.suggested_record) // your record with our report address in rua=

const report = await tx.dmarc.get('yourdomain.com')
if (report.dmarc.enabled) console.log(report.dmarc.readiness.label, report.dmarc.sources)

Details: https://docs.groundmail.dev/dmarc

Adapters

Optional entry points (install peer deps as needed):

| Import | Package / peer | |--------|----------------| | groundmail/nodemailer | groundmail-nodemailer + nodemailer | | groundmail/better-auth | groundmail-better-auth | | groundmail/authjs | groundmail-authjs | | groundmail/clerk | groundmail-clerk | | groundmail/payload | groundmail-payload |

Docs

• Quickstart: https://docs.groundmail.dev/quickstart
• Node / Nodemailer: https://docs.groundmail.dev/frameworks/node
• Testing (test keys, simulator): https://docs.groundmail.dev/testing
• DMARC monitoring: https://docs.groundmail.dev/dmarc
• API reference: https://docs.groundmail.dev/api/emails
• Product: https://groundmail.dev

License

MIT