# 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

```bash
npm install groundmail
```

## 2. Configure your API key

```bash
export GROUNDMAIL_API_KEY=gm_your_key_here
```

## 3. Send an email

```ts
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`](https://github.com/Groundmail/groundmail-nodemailer) (transport source of truth; also re-exported as `groundmail/nodemailer`).

```bash
npm install groundmail-nodemailer groundmail nodemailer
```

```ts
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):

```bash
npm install groundmail-better-auth groundmail better-auth
```

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

Same helper is also exported as `groundmail/better-auth`. Full setup: [Better Auth email](https://docs.groundmail.dev/guides/better-auth).

## Auth.js / NextAuth

```bash
npm install groundmail-authjs groundmail next-auth
```

```ts
import Groundmail from 'groundmail-authjs'
```

Same provider is also exported as `groundmail/authjs`. Full setup: [Auth.js / NextAuth email](https://docs.groundmail.dev/guides/authjs).

## React Email

Author components with [React Email](https://react.email), then pass them to the Node SDK’s `react` option:

```bash
npm install groundmail @react-email/render react
```

```ts
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](https://docs.groundmail.dev/guides/react-email).
