Markdown

AI app builders

Use Groundmail in Lovable, Replit, Bolt, Base44, v0, Emergent, Macaly, Rocket and similar AI builders.

Updated Nov 17, 20266 min read

Two kinds of install surface:

  1. Agent tools (MCP) — the builder’s AI can call Groundmail while you develop (Replit one-click MCP; Cursor/Claude via MCP).
  2. App runtime (Secrets + code) — your deployed app sends mail via GROUNDMAIL_API_KEY and POST /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

  1. Create a Groundmail account and an API key (gm_…).
  2. Store it as GROUNDMAIL_API_KEY in the builder’s secrets / env UI (server-side only).
  3. 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.
  4. Sending to other people needs a verified domain and a payment method on file (the Free plan is not charged).

Standard env var

Terminal
GROUNDMAIL_API_KEY=gm_your_key_here

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

  1. Add GROUNDMAIL_API_KEY to .env for local work, and to your host's env settings (Netlify, Vercel, etc.) when you deploy.
  2. Make sure .env is in .gitignore. Never commit gm_ keys.
  3. Don't name the key VITE_GROUNDMAIL_API_KEY. Vite puts every VITE_ 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:

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

  1. Paste the prompt (with rule 6 below) in Emergent's chat. The agent adds the name GROUNDMAIL_API_KEY to the project's .env.
  2. Fill in the value (gm_…) in .env yourself for preview. Don't paste the key in chat: everything in chat is sent to the AI model.
  3. Before you publish, open Preview → Manage → Secrets, set GROUNDMAIL_API_KEY under 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

  1. In Macaly, open Settings → MCP Servers → Add server and choose Advanced.
  2. Name: Groundmail. Server URL: https://mcp.groundmail.dev/mcp. Transport: Streamable HTTP.
  3. Authentication: OAuth (sign in). Or choose API headers and add Authorization: Bearer gm_your_key_here.
  4. 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.
  5. Turn on Read-only tools and Write tools. send_email, create_domain and verify_domain are 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.

  1. In the editor, click Code and add GROUNDMAIL_API_KEY= to the .env file at the project root.
  2. Open your task's Settings → Environment and set the value (gm_…) on the Staging and Production tabs. Never name it NEXT_PUBLIC_GROUNDMAIL_API_KEY: NEXT_PUBLIC_ variables go to the browser.
  3. 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.

Terminal
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

Was this page helpful?