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
- Index: docs.groundmail.dev/llms.txt
- Full bundle: docs.groundmail.dev/llms-full.txt
- OpenAPI: docs.groundmail.dev/openapi.yaml
- Agent skill notes: docs.groundmail.dev/ai/agent-skill
- MCP server: docs.groundmail.dev/ai/mcp (
groundmail-mcpon npm) - AI app builders: 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.
Create an account
- Open the dashboard at app.groundmail.dev.
- Sign up with email + password (or email code if you prefer), or continue with Google, GitHub or GitLab.
- If using email code: enter the code emailed to you.
- 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.
Let your AI agent do it (recommended)
- On Home, click Copy agent prompt and paste it into Claude Code, Cursor or any coding agent.
- The agent runs
groundmail login, which opens your browser: click Approve. - 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
- On Home, click Send test email. It goes to your account email from the sandbox sender; no domain, DNS or API key needed.
- 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)
- Go to API Keys → Create (or use an existing
gm_…key). - Copy the secret — it is shown once.
export GROUNDMAIL_API_KEY=gm_your_key_hereVerify 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)
- Optional but easiest: Integrations → paste a Cloudflare API token (Zone DNS Edit) → Save.
- 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. - 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.
- Optional after verification: set Delivery settings on the domain detail page for:
- open tracking
- click tracking
tls_mode(opportunisticorenforced)
- 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:), 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:
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.comOptional 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:
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:
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>"
}'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)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>"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:
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
{
"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:
{ "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, orgroundmail 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@ordelayed@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.
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)
- Go to Webhooks in the dashboard (or use the API).
- Add your HTTPS endpoint URL.
- Copy the signing secret (
whsec_…) — shown once. - Verify
Groundmail-Signatureon incomingPOSTs.
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?
- Create a dedicated inbound subdomain such as
inbound.example.com. - Add it with
inbound_enabled: true(API) orgroundmail domains add inbound.example.com --inbound true(CLI). - Verify the domain, then publish the returned MX record.
- Subscribe to
email.receivedand/or pollGET /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):
groundmail automations create --file ./welcome.json
groundmail automations activate --id "$AUTOMATION_ID"Then send the trigger event from your app:
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:
{
"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
- Docs home: docs.groundmail.dev
- API reference: docs.groundmail.dev/api-explorer
- Next.js quickstart: docs.groundmail.dev/frameworks/nextjs
- React Email: docs.groundmail.dev/guides/react-email
- Node.js quickstart: docs.groundmail.dev/frameworks/node
- Send API: Emails
- Domains API: Domains API
- Inbound email API: Inbound email API
- Deliverability: Deliverability API
- Events: Events
- Templates: Templates
- Automations: Automations
- SMTP relay: SMTP relay
- Webhooks: Webhooks
- Testing (test keys, simulator addresses): Testing
- AI onboarding: docs.groundmail.dev/llms.txt, docs.groundmail.dev/llms-full.txt, Groundmail agent skill notes, Groundmail MCP server (
groundmail-mcpnpm package) - OpenAPI spec: docs.groundmail.dev/openapi.yaml