Markdown

Groundmail — Quickstart

Send your first transactional email in about five minutes.

Updated Nov 17, 20268 min read

Let your coding agent do this page

Paste one prompt into Claude Code, Cursor or Codex. It signs you in, verifies your domain and wires up sending, and asks before it emails anyone but you.

3 ways to send your first email with Groundmail (dashboard, CLI, AI agent). Video, with captions.

Migrating from another provider? Start with Resend, Postmark, Amazon SES, or SendGrid, then mirror send + webhook flows from the hosted API Explorer.

Building auth email? See password reset, Supabase Auth, and Clerk / Auth.js.

Using React Email components? See Send React Email.

Hosted docs: docs.groundmail.dev
Dashboard: app.groundmail.dev
API: https://api.groundmail.dev


For AI agents

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.


Create an account

  1. Open the dashboard at 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.


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.

  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 and Groundmail MCP server.


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.
Terminal
export GROUNDMAIL_API_KEY=gm_your_key_here

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.

  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:

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


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:

Terminal
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:

Terminal
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:

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>"
  }'

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:

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


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.

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. To retry safely, send an Idempotency-Key header: see Test sends and idempotency.

Test without sending

Two ways to exercise your code without delivering real mail (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.
Terminal
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."}'

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 POSTs.
TypeScript
await client.webhooks.create({
  url: 'https://yourapp.com/webhooks/groundmail',
})

See the API reference for payload shape and signature verification. To see each event arrive, send to the simulator addresses in Testing.


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 for the full flow and the MX conflict warning.


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

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

Then send the trigger event from your app:

Terminal
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 and Events.


Next steps

Was this page helpful?