Two kinds of install surface:
- Agent tools (MCP) — the builder’s AI can call Groundmail while you develop (Replit one-click MCP; Cursor/Claude via MCP).
- App runtime (Secrets + code) — your deployed app sends mail via
GROUNDMAIL_API_KEYandPOST /emails(or SMTP).
Most of this page covers (2). Replit and Macaly also connect (1) with the hosted MCP server.
Pick your builder
| Builder | Best for | Where the key goes | Guide |
|---|---|---|---|
| Lovable | React + Supabase apps, chat-driven features | Lovable Secrets | Lovable |
| Replit | Full-stack Replit Agent projects | Replit Secrets, plus the MCP badge | Replit |
| Bolt.new | Vite / React prototypes from chat | .env and your host's env settings |
Bolt |
| Base44 | Base44 apps that need your own domain | Base44 project secrets | Base44 |
| v0 | Next.js apps from Vercel v0 | Vercel environment variables | Next.js: v0 |
| Emergent | Full-stack apps built by Emergent's agent | .env, then Secrets for the live app |
Emergent |
| Macaly | Sites and apps, with MCP tools in the agent | Project Secrets, plus the MCP server | Macaly |
| Rocket | Web and mobile apps from Rocket | .env, then Settings → Environment |
Rocket |
Before you paste a prompt
- Create a Groundmail account and an API key (
gm_…). - Store it as
GROUNDMAIL_API_KEYin the builder’s secrets / env UI (server-side only). - For a first send before your domain verifies, use the sandbox sender:
from: "noreply@mail.groundmail.dev",to: your Groundmail account email. Details in Test sends and idempotency. - Sending to other people needs a verified domain and a payment method on file (the Free plan is not charged).
Standard env var
GROUNDMAIL_API_KEY=gm_your_key_hereUse this exact name in generated code so it matches our SDK, docs and prompts.
The prompt
Paste this in the builder's chat. Replace the last rule with the line for your builder from the sections below.
Integrate Groundmail transactional email into this project.
Docs (read first):
- https://docs.groundmail.dev/llms.txt
- https://docs.groundmail.dev/ai/safe-defaults
- https://docs.groundmail.dev/builders
Rules:
1. GROUNDMAIL_API_KEY is in the project's secrets or environment settings. Use it in server-side code only: never in client bundles or client-visible config, and never logged.
2. Send with POST https://api.groundmail.dev/emails (header Authorization: Bearer $GROUNDMAIL_API_KEY; JSON fields from, to, subject, html, text, reply_to), or the "groundmail" npm package on Node (it throws GroundmailError on failure).
3. Give every send an Idempotency-Key header (SDK option: idempotencyKey) that is unique to the message, for example "password-reset-<userId>-<tokenId>", and reuse it if you retry.
4. Test first: send from "noreply@mail.groundmail.dev" to my Groundmail account email only. Do not email anyone else until I have verified a domain and added a payment method in Groundmail (the Free plan is not charged).
5. On an error, read error.code and error.hint from the JSON response and follow the hint (https://docs.groundmail.dev/errors). Retry only on 429, 500, 502 or 503, with backoff and the same Idempotency-Key.
6. <the line for your builder>
When my domain is verified, switch from to an address on it, for example noreply@ourdomain.com.Lovable and Replit have their own prompts in their guides. Emergent, Macaly and Rocket use this one.
Bolt
Bolt often generates a Vite single-page app, which runs in the browser. Keep sends on a server.
- Add
GROUNDMAIL_API_KEYto.envfor local work, and to your host's env settings (Netlify, Vercel, etc.) when you deploy. - Make sure
.envis in.gitignore. Never commitgm_keys. - Don't name the key
VITE_GROUNDMAIL_API_KEY. Vite puts everyVITE_variable into the browser bundle, where anyone can read it.
Rule 6 for the prompt:
6. If this is a Vite SPA, add a small API route or serverless function for sends and never call the Groundmail API from the browser. If this is Next.js, follow the App Router server pattern in https://docs.groundmail.dev/frameworks/nextjs.A server function the browser calls instead of the API:
// Example: server handler (adapt to your Bolt stack)
export async function sendTransactionalEmail(payload: {
to: string
subject: string
html: string
}) {
const res = await fetch('https://api.groundmail.dev/emails', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GROUNDMAIL_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
from: process.env.MAIL_FROM ?? 'noreply@yourdomain.com',
...payload,
}),
})
if (!res.ok) throw new Error(await res.text())
return res.json()
}If you started with a RESEND_API_KEY pattern, the migration guide maps the fields.
Base44
Base44 has built-in email. It is fine for early prototypes, internal tools and low volume where Base44's default sender is acceptable. Add Groundmail when you need branded mail from @yourdomain.com, password reset and auth mail on dedicated transactional sending, delivery webhooks, or the same POST /emails call your other services use.
Add GROUNDMAIL_API_KEY as a project secret or environment variable (the exact screen depends on the Base44 project type). Read it only from server-side code or automation steps, never from client-visible config.
Rule 6 for the prompt:
6. Use Groundmail instead of or alongside Base44 built-in email. Explain when Base44 built-in email is still fine and when Groundmail is needed (own domain, production volume, webhooks).Before you go live: verify your domain, add a payment method, set from to an address on that domain, and handle bounces and complaints with webhooks if you need them.
Emergent
Emergent has no email of its own. You bring your own key and the agent writes the code that calls the API. Groundmail isn't in Emergent's Connectors catalogue; for services outside it, Emergent asks for your key and writes the connection itself, which is all Groundmail needs.
- Paste the prompt (with rule 6 below) in Emergent's chat. The agent adds the name
GROUNDMAIL_API_KEYto the project's.env. - Fill in the value (
gm_…) in.envyourself for preview. Don't paste the key in chat: everything in chat is sent to the AI model. - Before you publish, open Preview → Manage → Secrets, set
GROUNDMAIL_API_KEYunder Custom keys, and choose Save and re-publish.
Rule 6 for the prompt:
6. Add the name GROUNDMAIL_API_KEY to .env and ask me to fill in the value; never ask me to paste the key in chat. Send from the backend only, never from the frontend, and add one real flow: password reset, email verification or a welcome email.Test send: ask the agent to send one email from noreply@mail.groundmail.dev to your Groundmail account email, and check it arrives.
Go live: add your domain at app.groundmail.dev, publish the DNS records and verify it, add a payment method, then ask the agent to change from to an address on that domain.
Macaly
Macaly connects any MCP server to its agent, so it can use Groundmail two ways:
- The Groundmail MCP server, so Macaly's agent can add and verify your domain, send test emails and check delivery while it builds.
- An API key in Secrets, so your published app sends mail. You need this one for real sends; the MCP server only helps the agent.
Connect the MCP server
- In Macaly, open Settings → MCP Servers → Add server and choose Advanced.
- Name:
Groundmail. Server URL:https://mcp.groundmail.dev/mcp. Transport: Streamable HTTP. - Authentication: OAuth (sign in). Or choose API headers and add
Authorization: Bearer gm_your_key_here. - Click Test connection. With OAuth, a window opens on Groundmail: sign in and approve (allow pop-ups for macaly.com if nothing opens). Then Save changes.
- Turn on Read-only tools and Write tools.
send_email,create_domainandverify_domainare write tools. Leave Destructive tools off.
More on the tools: MCP server.
Add the API key for your app
In your Macaly project, open Settings → Secrets and add GROUNDMAIL_API_KEY with your gm_… key. Don't paste the key in chat.
Rule 6 for the prompt:
6. GROUNDMAIL_API_KEY is in Macaly Secrets. If the Groundmail MCP tools are connected, use create_domain and verify_domain to set up my domain and send_email for the first test, but the app itself must send through the API from server code. If this project already sends with Brevo for transactional email, move those sends to Groundmail.Test send: ask the agent to send a test email to your Groundmail account email (through the MCP tools or the app), then check it with list_emails.
Go live: ask the agent to add your domain with create_domain, publish the DNS records it returns (or use apply_domain_dns with a connected Cloudflare, Vercel, GoDaddy, Netlify, DigitalOcean or DNSimple account), then run verify_domain. Add a payment method in Groundmail and switch from to an address on the domain.
Rocket
Rocket can call any REST API, with your key stored as an environment variable. Import the Groundmail API from our OpenAPI file or a cURL command, or let the prompt write the call.
- In the editor, click Code and add
GROUNDMAIL_API_KEY=to the.envfile at the project root. - Open your task's Settings → Environment and set the value (
gm_…) on the Staging and Production tabs. Never name itNEXT_PUBLIC_GROUNDMAIL_API_KEY:NEXT_PUBLIC_variables go to the browser. - Optional: in the preview toolbar choose … → APIs → Add APIs. On the Swagger tab, upload openapi.yaml (download it first); on the cURL tab, paste the command below. Map the bearer token to
GROUNDMAIL_API_KEY.
Mobile tasks keep variables in env.json instead. Don't put the key there: anything in the app bundle can be read. Send from a server function and keep the key on that server.
curl -X POST https://api.groundmail.dev/emails \
-H "Authorization: Bearer $GROUNDMAIL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: welcome-123" \
-d '{"from":"noreply@mail.groundmail.dev","to":"you@example.com","subject":"Hello from Rocket","html":"<p>It works.</p>"}'Rule 6 for the prompt:
6. If this is a Next.js app, send from a Route Handler or Server Action (https://docs.groundmail.dev/frameworks/nextjs) that reads process.env.GROUNDMAIL_API_KEY. If it is a React or mobile app, add a small server function for sends. If an API is integrated on a screen element, have it call that server code, never api.groundmail.dev from the browser or the app.Test send: replace you@example.com with your Groundmail account email and trigger the flow in the Staging preview.
Go live: verify your domain at app.groundmail.dev, add a payment method, and set from to an address on that domain before you publish.
v0
v0 generates Next.js apps. See Next.js: v0 for the Vercel setup and the prompt line.
Reference
- Agent skill notes — integration defaults for AI agents
- Test sends and idempotency — safe testing and retries
- Errors — every error code and how to fix it
- OpenAPI — API contract
- Next.js — server-side send pattern
- Auth providers — Supabase, Clerk, Auth.js and Better Auth
- Supabase Auth email — Send Email hook + Edge Function