Groundmail + Replit

Two install surfaces, depending on the job:

Surface Use when
MCP (Agent tools) Replit Agent should call Groundmail (send, domains, templates) while building
Secrets + app code Your running repl sends mail (password reset, invites, notifications)

Most projects use both: MCP while building, Secrets for production paths in the app.

Add to Replit (MCP)

One-click install of the hosted MCP server (https://mcp.groundmail.dev/mcp). Replit uses OAuth — no API key in the link.

Install Groundmail

Or open: Add Groundmail MCP

After install, authorize with your Groundmail account when prompted. Full MCP docs: MCP server.

Wire email into your app (Secrets)

1. Add your API key

  1. Create an API key at app.groundmail.dev (gm_…).
  2. In Replit, open Tools → Secrets (or Integrations → secrets, depending on Replit UI).
  3. Create a secret:
Key Value
GROUNDMAIL_API_KEY gm_your_key_here

Replit injects secrets as environment variables. Access via process.env.GROUNDMAIL_API_KEY (Node) or os.environ["GROUNDMAIL_API_KEY"] (Python). Never expose the key to the client.

2. Paste this prompt in Replit Agent

Integrate Groundmail transactional email into this Replit project.

Docs:
- https://docs.groundmail.dev/ai/agent-skill
- https://docs.groundmail.dev/openapi.yaml
- https://docs.groundmail.dev/builders/replit
- https://docs.groundmail.dev/ai/mcp

Rules:
1. Read GROUNDMAIL_API_KEY from Replit Secrets (already configured). Never log or expose the key to the client.
2. Send with POST https://api.groundmail.dev/emails and Authorization: Bearer <key>.
3. Until domain verification and Free production unlock (both required: verified domain + payment method on file), use from "noreply@mail.groundmail.dev" and send only to the Groundmail account email.
4. Implement server-side email for at least one flow (welcome, reset, or notification).
5. Use html and text fields; prefer groundmail npm package on Node.

For production: verify a domain, add a payment method to unlock Free production (no charge until you upgrade), then set from to an address on that domain. Upgrade to Pro or Scale for more volume.

3. Minimal Express route (Node)

import express from 'express'

const app = express()
app.use(express.json())

app.post('/api/send-test', async (req, res) => {
  const apiKey = process.env.GROUNDMAIL_API_KEY
  if (!apiKey) return res.status(500).json({ error: 'Missing GROUNDMAIL_API_KEY' })

  const upstream = await fetch('https://api.groundmail.dev/emails', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(req.body),
  })

  const data = await upstream.json()
  res.status(upstream.status).json(data)
})

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

Production

  1. Verify a sending domain in Groundmail.
  2. Add a payment method to unlock Free production (no charge until you upgrade), or upgrade for higher volume.
  3. Set from to noreply@yourdomain.com (or similar on your verified domain).