# Groundmail — Quickstart

Send your first transactional email in about five minutes.

Migrating from another provider? Start with [Resend](https://docs.groundmail.dev/migration), [Postmark](https://docs.groundmail.dev/migration/postmark), [Amazon SES](https://docs.groundmail.dev/migration/ses), or [SendGrid](https://docs.groundmail.dev/migration/sendgrid), then mirror send + webhook flows from the hosted [API Explorer](https://docs.groundmail.dev/api-explorer).

Building auth email? See [password reset](https://docs.groundmail.dev/guides/password-reset-emails), [Supabase Auth](https://docs.groundmail.dev/guides/supabase), and [Clerk / Auth.js](https://docs.groundmail.dev/guides/password-reset-emails#auth-providers).

Using React Email components? See [Send React Email](https://docs.groundmail.dev/guides/react-email).

**Hosted docs:** [docs.groundmail.dev](https://docs.groundmail.dev)  
**Dashboard:** [app.groundmail.dev](https://app.groundmail.dev)  
**API:** `https://api.groundmail.dev`

---

## For AI agents

- **Index:** [docs.groundmail.dev/llms.txt](https://docs.groundmail.dev/llms.txt)
- **Full bundle:** [docs.groundmail.dev/llms-full.txt](https://docs.groundmail.dev/llms-full.txt)
- **OpenAPI:** [docs.groundmail.dev/openapi.yaml](https://docs.groundmail.dev/openapi.yaml)
- **Agent skill notes:** [docs.groundmail.dev/ai/agent-skill](https://docs.groundmail.dev/ai/agent-skill)
- **MCP server:** [docs.groundmail.dev/ai/mcp](https://docs.groundmail.dev/ai/mcp) (`groundmail-mcp` on npm)
- **AI app builders:** [docs.groundmail.dev/builders](https://docs.groundmail.dev/builders) (Lovable, Replit, Bolt, Base44, v0 prompts)

Use **Copy agent prompt** on the dashboard **Home** page to hand the whole setup to a coding agent. The prompt has no API key in it: the agent signs in through your browser with `groundmail login`.

---

## 1. Create an account

1. Open the dashboard at [app.groundmail.dev](https://app.groundmail.dev).
2. Sign up with email + password (or email code if you prefer), or continue with Google, GitHub or GitLab.
3. If using email code: enter the code emailed to you.
4. Answer four quick questions (or skip them). You land on **Home**.

**AI agents** can create their own account with **Continue with AgentID**: the agent signs in as itself with its own verified inbox, and gets its own Groundmail account.

---

## 2. Send a sandbox test (fastest path)

**Home** lists four steps: send a test email, connect your sending domain, add Groundmail to your code, and unlock production sending. Each one ticks off as it's done, whether you, your agent or a DNS change finished it.

### Let your AI agent do it (recommended)

1. On **Home**, click **Copy agent prompt** and paste it into Claude Code, Cursor or any coding agent.
2. The agent runs `groundmail login`, which opens your browser: click **Approve**.
3. The agent sends the sandbox test, sets up your domain (asking you first), creates a send-only key for your app, and wires in the SDK.

Prefer a direct connection? Home also has one-line setups for Claude Code, Cursor, Claude.ai and ChatGPT. All of them sign in with OAuth, with no key in your config.

### Do it yourself

1. On **Home**, click **Send test email**. It goes to your account email from the sandbox sender; no domain, DNS or API key needed.
2. Check your inbox for the test message.

After you verify a domain, you can self-test from that domain too (still only to your account email until a payment method is on file).

See [Groundmail agent skill notes](https://docs.groundmail.dev/ai/agent-skill) and [Groundmail MCP server](https://docs.groundmail.dev/ai/mcp).

---

## 3. Create an API key (if you skipped the dashboard flow)

1. Go to **API Keys → Create** (or use an existing `gm_…` key).
2. Copy the secret — it is shown **once**.

```bash
export GROUNDMAIL_API_KEY=gm_your_key_here
```

---

## 4. Verify a sending domain (DNS setup — self-test from your domain on free)

Add and verify your domain on the Free plan to complete DNS setup. On the free plan you can **self-test from your verified domain to your account email** to confirm DNS and branding. **Free production** (send to other recipients) unlocks after a **verified domain and a payment method on file**. Free is never charged; you're only billed if you turn on pay as you go. Caps: 3,000 emails/mo · 100/day · 3 domains. Turn on pay as you go at **Settings → Billing** to keep sending past 3,000 a month.

### Dashboard (recommended)

1. Optional but easiest: **Integrations** → paste a Cloudflare API token (Zone DNS Edit) → Save.
2. Go to **Domains → Add domain** and enter the domain to send from. We suggest a subdomain such as `mail.yourdomain.com`: your app's email builds its own reputation, and your team's email and existing DNS records stay as they are.
3. On the domain page:
   - If Cloudflare is connected: click **Apply DNS (Cloudflare)**, then **Verify DNS**.
   - If your DNS is at GoDaddy: switch to **GoDaddy**, paste a GoDaddy Personal Access Token for a one-time apply, then **Verify DNS**.
   - Otherwise paste the shown records at your DNS host, then **Verify DNS**. A record marked **Already set** (your existing DMARC record) needs nothing.
4. Optional after verification: set **Delivery settings** on the domain detail page for:
   - open tracking
   - click tracking
   - `tls_mode` (`opportunistic` or `enforced`)
5. Check the built-in DMARC/BIMI guidance on the same page before you roll out branded inbox features.

| Type | Purpose |
|------|---------|
| TXT `_groundmail.mail.yourdomain.com` | Domain ownership |
| TXT `{selector}._domainkey.mail.yourdomain.com` | DKIM (domain signing key) |
| CNAME `rp.mail.yourdomain.com` | Return path → `rp.groundmail.dev` |
| TXT `mail.yourdomain.com` | SPF (`include:spf.groundmail.dev`), subdomains only |
| TXT `_dmarc.mail.yourdomain.com` | DMARC, unless you already have one |

Sending from your main domain (`yourdomain.com`) instead? There is no SPF record to add: your mail passes SPF on the return-path subdomain, so your existing SPF record stays as it is. An existing DMARC record is shown as **Already set** and left alone.

Ownership, DKIM, return path and, for a subdomain, SPF are required to verify. Verify also confirms mail-server DKIM readiness so sends are signed with your domain (not the shared pool). Local Docker auto-verifies when `GROUNDMAIL_DEV_AUTO_VERIFY=true`.
If a domain is already attached to another Groundmail team, `POST /domains` returns a 409 with claim instructions instead of creating a duplicate owner.

### CLI (from your editor / terminal)

Save a Cloudflare token under **Integrations** first (recommended). Then:

```bash
export GROUNDMAIL_API_KEY=gm_your_key_here

npx -y --package=groundmail-cli -- groundmail domains add yourdomain.com

# Uses the Cloudflare token stored in Groundmail (no local CLOUDFLARE_API_TOKEN needed)
npx -y --package=groundmail-cli -- groundmail domains apply yourdomain.com --provider cloudflare

npx -y --package=groundmail-cli -- groundmail domains verify yourdomain.com
```

Optional override: set `CLOUDFLARE_API_TOKEN` locally to apply with a machine token instead of the dashboard one. Vercel uses `VERCEL_API_TOKEN` and optional `VERCEL_TEAM_ID` the same way. GoDaddy can use stored dashboard credentials or a local `GODADDY_PAT` (a Personal Access Token).

---

## 5. Send from your app

Pick one integration method below. Replace `you@yourdomain.com` with an address on your **verified** domain.

### Sandbox self-test (before DNS)

Use the shared sandbox sender on `mail.groundmail.dev`, but only send to **your own account email**:

```bash
curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@mail.groundmail.dev",
    "to": "you@example.com",
    "subject": "Sandbox check",
    "html": "<p>Groundmail sandbox works.</p>"
  }'
```

Once your domain is verified, you can self-test from your own domain to your account email:

```bash
curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "you@example.com",
    "subject": "Verified domain check",
    "html": "<p>My domain works.</p>"
  }'
```

Add a payment method at **Settings → Billing** to unlock Free production (send to other recipients). Turn on pay as you go there to keep sending past 3,000 a month.

### Production

Send to anyone with cURL, the Node.js SDK (`npm install groundmail`) or the CLI:

<!-- tabs -->

```bash cURL
curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "user@example.com",
    "subject": "Hello from Groundmail",
    "html": "<p>It works.</p>"
  }'
```

```ts Node.js
import { Groundmail } from 'groundmail'

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

const { id, status } = await client.emails.send({
  from: 'you@yourdomain.com',
  to: 'user@example.com',
  subject: 'Hello from Groundmail',
  html: '<p>It works.</p>',
})

console.log(id, status)
```

```bash CLI
GROUNDMAIL_API_KEY=$GROUNDMAIL_API_KEY npx -y --package=groundmail-cli -- groundmail emails send \
  --from you@yourdomain.com \
  --to user@example.com \
  --subject "Hello from Groundmail" \
  --html "<p>It works.</p>"
```

<!-- /tabs -->

For the CLI, install globally: `npm install -g groundmail-cli`, then run `groundmail emails send …`.

### Save a sender instead of typing `from`

Once your domain is verified, add a sender under **Domains › Senders** (name people see, address, where replies go, and a handle such as `billing`). Then name it instead of writing the address:

```ts
await client.emails.send({
  sender: 'billing',
  to: 'user@example.com',
  template: { id: 'receipt', variables: { amount: '$20.00' } },
})
```

Your first sender becomes the default, so a send with no `from` goes out as it. A `from` you pass still wins. Templates and automation emails can use senders too: see [Senders](https://docs.groundmail.dev/senders).

---

## Success response

```json
{
  "id": "msg_abc123…",
  "status": "queued"
}
```

`queued` means the email is accepted and on its way: Groundmail answers as soon as it is stored and hands it to the mail server in the background. Watch it land with `GET /emails/{id}`, webhooks (`email.delivered`, or `email.failed` with the reason), or `groundmail emails send … --watch` from the CLI.

---

## Plan limits

The Free plan includes 3,000 emails a month and 100 a day. Until a payment method is on file, sends are limited to your account email, from the shared sandbox sender or from a verified domain. Unlock Free production with a verified domain **and** a payment method on file (Free is never charged). Free stops at its limits. Pay as you go has no monthly stop: $15 a month includes 20,000 emails, then $0.70 per 1,000 up to 100,000, $0.50 from 100,000 to 1 million and $0.30 above, each rate only on the emails in its band. On Free, over the limit:

```json
{ "error": { "code": "plan_limit", "message": "…", "hint": "…", "docs_url": "https://docs.groundmail.dev/errors#plan_limit", "upgrade_url": "/settings/billing" } }
```

HTTP **429**. Turn on pay as you go in the dashboard under **Settings → Billing** to keep sending.

New accounts on pay as you go also ramp up: 1,000 product and 3,000 transactional recipients a day at first (tag sign-in codes and receipts `category: "transactional"`; at first, email without a category counts as product), doubling each day you use at least half of the limit with low bounces and complaints, until it reaches 1,000,000 a day. It keeps our shared sending IPs trusted by mailbox providers. Turning on pay as you go does not skip it; email support@groundmail.dev if you need more sooner. Details: [Sending limits](https://docs.groundmail.dev/sending-limits#new-account-ramp-up).

## Common errors

| HTTP | Meaning | Fix |
|------|---------|-----|
| 401 | Invalid or missing API key | Check `Authorization: Bearer gm_…` |
| 403 | From domain not verified, sandbox/verified-domain recipient mismatch, or send to other recipients without Free production unlocked | Verify domain; self-test to your account email; add a payment method at Settings → Billing to unlock Free production |
| 400 | Missing `from`, `to`, or `subject` | Send required fields + `html` or `text` |
| 429 | Plan send limit (`plan_limit`) or new-account ramp-up limit (`daily_ramp_limit`) | `plan_limit`: turn on pay as you go at Settings → Billing. `daily_ramp_limit`: send the rest after `details.resets_at` (00:00 UTC) or email support |
| 503 | Mail delivery temporarily unavailable | Retry later or contact support |

Every error body includes a stable `code`, a `hint` that says how to fix it, and a `docs_url`. Full list: [Errors](https://docs.groundmail.dev/errors). To retry safely, send an `Idempotency-Key` header: see [Test sends and idempotency](https://docs.groundmail.dev/ai/safe-defaults).

## Test without sending

Two ways to exercise your code without delivering real mail ([Testing](https://docs.groundmail.dev/testing)):

- A **test key** (`gm_test_…`): create one on the API keys page with **Test key** ticked, or `groundmail keys create --test`. Sends with it run every check and fire webhooks but deliver nothing, and do not count toward your plan.
- **Simulator addresses**: send to `delivered@`, `bounce@`, `block@`, `complaint@`, `suppressed@` or `delayed@simulator.groundmail.dev` (with any key, from the sandbox address too) to get that outcome and its webhooks. `bounce+anything@…` works, so you can tell tests apart.

```bash
curl -X POST https://api.groundmail.dev/emails \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"noreply@mail.groundmail.dev","to":"bounce@simulator.groundmail.dev","subject":"Bounce test","text":"Simulated."}'
```

---

## 6. Webhooks (optional)

1. Go to **Webhooks** in the dashboard (or use the API).
2. Add your HTTPS endpoint URL.
3. Copy the signing secret (`whsec_…`) — shown once.
4. Verify `Groundmail-Signature` on incoming `POST`s.

```ts
await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/groundmail',
})
```

See the [API reference](https://docs.groundmail.dev/api-explorer) for payload shape and signature verification. To see each event arrive, send to the simulator addresses in [Testing](https://docs.groundmail.dev/testing).

---

## 7. Receive email (optional)

Want an app inbox or agent mailbox?

1. Create a dedicated inbound subdomain such as `inbound.example.com`.
2. Add it with `inbound_enabled: true` (API) or `groundmail domains add inbound.example.com --inbound true` (CLI).
3. Verify the domain, then publish the returned MX record.
4. Subscribe to `email.received` and/or poll `GET /received-emails`.

See [Inbound email API](https://docs.groundmail.dev/inbound) for the full flow and the MX conflict warning.

---

## 8. Event-driven automations (optional)

Groundmail can trigger transactional sequences from custom events.

**Dashboard:** open **Automations**, create from a starter (or blank) on the visual canvas, configure steps in the side panel (send-email can use a published **Templates** entry or inline HTML), then Activate.

**CLI / API:** create and activate from a JSON file (handy in Cursor or CI):

```bash
groundmail automations create --file ./welcome.json
groundmail automations activate --id "$AUTOMATION_ID"
```

Then send the trigger event from your app:

```bash
curl -X POST https://api.groundmail.dev/events \
  -H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt_user_created_123" \
  -d '{
    "name": "user.created",
    "user_id": "user_123",
    "email": "user@example.com",
    "data": {
      "name": "Ada Lovelace"
    }
  }'
```

Response:

```json
{
  "event": {
    "id": "ae_123",
    "name": "user.created",
    "user_id": "user_123",
    "email": "user@example.com",
    "data": { "name": "Ada Lovelace" },
    "source": "api",
    "created_at": "2026-07-26T12:00:00.000Z"
  },
  "matched_automations": 1,
  "resumed_runs": 0,
  "cancelled_runs": 0
}
```

See [Automations](https://docs.groundmail.dev/automations) and [Events](https://docs.groundmail.dev/events).

---

## Next steps

- Docs home: [docs.groundmail.dev](https://docs.groundmail.dev)
- API reference: [docs.groundmail.dev/api-explorer](https://docs.groundmail.dev/api-explorer)
- Next.js quickstart: [docs.groundmail.dev/frameworks/nextjs](https://docs.groundmail.dev/frameworks/nextjs)
- React Email: [docs.groundmail.dev/guides/react-email](https://docs.groundmail.dev/guides/react-email)
- Node.js quickstart: [docs.groundmail.dev/frameworks/node](https://docs.groundmail.dev/frameworks/node)
- Send API: [Emails](https://docs.groundmail.dev/emails)
- Domains API: [Domains API](https://docs.groundmail.dev/domains)
- Inbound email API: [Inbound email API](https://docs.groundmail.dev/inbound)
- Deliverability: [Deliverability API](https://docs.groundmail.dev/deliverability)
- Events: [Events](https://docs.groundmail.dev/events)
- Templates: [Templates](https://docs.groundmail.dev/templates)
- Automations: [Automations](https://docs.groundmail.dev/automations)
- SMTP relay: [SMTP relay](https://docs.groundmail.dev/smtp)
- Webhooks: [Webhooks](https://docs.groundmail.dev/webhooks)
- Testing (test keys, simulator addresses): [Testing](https://docs.groundmail.dev/testing)
- AI onboarding: [docs.groundmail.dev/llms.txt](https://docs.groundmail.dev/llms.txt), [docs.groundmail.dev/llms-full.txt](https://docs.groundmail.dev/llms-full.txt), [Groundmail agent skill notes](https://docs.groundmail.dev/ai/agent-skill), [Groundmail MCP server](https://docs.groundmail.dev/ai/mcp) (`groundmail-mcp` npm package)
- OpenAPI spec: [docs.groundmail.dev/openapi.yaml](https://docs.groundmail.dev/openapi.yaml)
