GroundmailDocs

Groundmail + Lovable

Lovable’s install surface is Secrets + a chat prompt: store your gm_ key, paste the prompt, and let Lovable wire server-side sends (often via Supabase Auth).

There is no separate Lovable “connector package.” The agent writes the Edge Function / hook against POST /emails (or SMTP if you prefer Supabase’s custom SMTP UI).

When to use Groundmail

  • Password reset, verification, receipts, and other transactional mail
  • Branded from on your own domain after DNS verify
  • Supabase Auth via a Send Email hook / Edge Function, or custom SMTP with a Groundmail credential

Lovable projects often use Supabase — see Supabase Auth email for the hook path and the SMTP alternative.

1. Add your API key (Secrets)

  1. Open app.groundmail.dev → API Keys → create a key (gm_…).
  2. In Lovable, open your project Settings → Secrets (or the env/secrets panel Lovable exposes for backend code).
  3. Add:
GROUNDMAIL_API_KEY=gm_your_key_here

Use the secret name exactly — server routes and Edge Functions should read process.env.GROUNDMAIL_API_KEY. Never put the key in client-side React components.

2. Paste this prompt in Lovable chat

Integrate Groundmail transactional email into this app.

Docs (read first):
- https://docs.groundmail.dev/guides/supabase
- https://docs.groundmail.dev/ai/agent-skill
- https://docs.groundmail.dev/openapi.yaml
- https://docs.groundmail.dev/builders/lovable
- https://docs.groundmail.dev/smtp

Rules:
1. Store the API key in GROUNDMAIL_API_KEY (already in Lovable Secrets). Never expose gm_ keys in the browser.
2. Prefer POST https://api.groundmail.dev/emails with Authorization: Bearer $GROUNDMAIL_API_KEY (Supabase Edge Function or server route).
3. Alternative: configure Supabase custom SMTP with Groundmail (host smtp.groundmail.dev, username groundmail, password from dashboard SMTP credentials).
4. Until domain verification and Free production unlock (both required: verified domain + payment method on file), sandbox sends must use from "noreply@mail.groundmail.dev" and to only our account email.
5. Add a server-side send path for password-reset / verification email.
6. Use canonical fields: html, text, reply_to. Prefer npm package groundmail if the backend is Node.

After domain verify + payment method on file (Free production, no charge until upgrade), switch from to noreply@ourdomain.com.

Replace “our account email” with the email on your Groundmail account if the agent asks.

3. Minimal server send (Node / Edge)

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: 'noreply@yourdomain.com',
    to: 'user@example.com',
    subject: 'Verify your email',
    html: '<p>Click the link to verify.</p>',
  }),
})

Or install groundmail and use the SDK — see Next.js.

Sandbox self-test

Send to your Groundmail account email only, with from: "noreply@mail.groundmail.dev", until your domain is verified and Free production is unlocked (payment method on file):

{
  "from": "noreply@mail.groundmail.dev",
  "to": "YOUR_ACCOUNT_EMAIL",
  "subject": "Groundmail sandbox check",
  "html": "<p>It works.</p>"
}

Production

  1. Add your domain in the Groundmail dashboard.
  2. Apply DNS (Cloudflare integration or registrar credentials).
  3. Verify, add a payment method to unlock Free production (no charge until you upgrade), then update from to an address on that domain.

Optional: MCP while you build

If you use Cursor (or another MCP client) alongside Lovable, connect hosted MCP at https://mcp.groundmail.dev/mcp with OAuth — see MCP server. That helps the coding agent; your Lovable app still needs Secrets (or SMTP) for runtime sends.