| 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.
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)
Add your API key
- Create an API key at app.groundmail.dev (
gm_…). - In Replit, open Tools → Secrets (or Integrations → secrets, depending on Replit UI).
- 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.
Paste this prompt in Replit Agent
Integrate Groundmail transactional email into this Replit project.
Docs (read first):
- https://docs.groundmail.dev/llms.txt
- https://docs.groundmail.dev/ai/safe-defaults
- https://docs.groundmail.dev/ai/mcp
- https://docs.groundmail.dev/builders/replit
Rules:
1. GROUNDMAIL_API_KEY is in Replit Secrets. Read it from the environment in server code only, never in client code, and never log it.
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. Implement server-side email for at least one flow: welcome, password reset or a notification.
7. If the Groundmail MCP tools are connected, use them to check domains and recent sends, but the app itself must send through the API.
When my domain is verified, switch from to an address on it, for example noreply@ourdomain.com.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
- Verify a sending domain in Groundmail.
- Add a payment method to unlock Free production (Free is never charged; you're only billed if you turn on pay as you go). Turn on pay as you go to keep sending past 3,000 a month.
- Set
fromtonoreply@yourdomain.com(or similar on your verified domain).