# AI app builders

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

**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](https://docs.groundmail.dev/ai/mcp)).
2. **App runtime (Secrets + code)** — your deployed app sends mail via `GROUNDMAIL_API_KEY` and `POST /emails` (or [SMTP](https://docs.groundmail.dev/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](https://docs.groundmail.dev/builders/lovable) |
| Replit | Full-stack Replit Agent projects | Replit Secrets, plus the MCP badge | [Replit](https://docs.groundmail.dev/builders/replit) |
| Bolt.new | Vite / React prototypes from chat | `.env` and your host's env settings | [Bolt](#bolt) |
| Base44 | Base44 apps that need your own domain | Base44 project secrets | [Base44](#base44) |
| v0 | Next.js apps from Vercel v0 | Vercel environment variables | [Next.js: v0](https://docs.groundmail.dev/frameworks/nextjs#v0) |
| Emergent | Full-stack apps built by Emergent's agent | `.env`, then **Secrets** for the live app | [Emergent](#emergent) |
| Macaly | Sites and apps, with MCP tools in the agent | Project **Secrets**, plus the MCP server | [Macaly](#macaly) |
| Rocket | Web and mobile apps from Rocket | `.env`, then **Settings → Environment** | [Rocket](#rocket) |

## Before you paste a prompt

1. Create a [Groundmail account](https://app.groundmail.dev) 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](https://docs.groundmail.dev/ai/safe-defaults).
4. Sending to other people needs a verified domain and a payment method on file (the Free plan is not charged).

## Standard env var

```bash
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.

```text
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}

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:

```text
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:

```ts
// 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](https://docs.groundmail.dev/migration) maps the fields.

## Base44 {#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:

```text
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](https://docs.groundmail.dev/webhooks) if you need them.

## Emergent {#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:

```text
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](https://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}

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](https://docs.groundmail.dev/ai/mcp).

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

```text
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}

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](https://docs.groundmail.dev/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.

```bash
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:

```text
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](https://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](https://docs.groundmail.dev/frameworks/nextjs#v0) for the Vercel setup and the prompt line.

## Reference

- [Agent skill notes](https://docs.groundmail.dev/ai/agent-skill) — integration defaults for AI agents
- [Test sends and idempotency](https://docs.groundmail.dev/ai/safe-defaults) — safe testing and retries
- [Errors](https://docs.groundmail.dev/errors) — every error code and how to fix it
- [OpenAPI](https://docs.groundmail.dev/openapi.yaml) — API contract
- [Next.js](https://docs.groundmail.dev/frameworks/nextjs) — server-side send pattern
- [Auth providers](https://docs.groundmail.dev/guides/password-reset-emails#auth-providers) — Supabase, Clerk, Auth.js and Better Auth
- [Supabase Auth email](https://docs.groundmail.dev/guides/supabase) — Send Email hook + Edge Function
