Short answer
To move a Python app from Mailgun, install pip install groundmail, replace the send call with groundmail.emails.send(), and swap MAILGUN_API_KEY for GROUNDMAIL_API_KEY. Then verify your sending domain in Groundmail, leaving Mailgun's DNS records in place until you cut over.
Mailgun's webhook events map onto Groundmail's email.* events, signed with HMAC-SHA256 in a Groundmail-Signature header. The free email migration scanner finds every place your repo sends through Mailgun and writes the pull request for your coding agent.
On this page
Before and after: the Python send call
The same password reset email, sent with Mailgun's Python code and then with Groundmail's. Groundmail answers with { id: "msg_…", status: "sent" }; keep the id if you match webhook events to sends, or put your own id in tags.
Swap the package
pip uninstall mailgun
pip install groundmailBefore: Mailgun (Python)
import os
from mailgun.client import Client
client = Client(auth=("api", os.environ["MAILGUN_API_KEY"]))
client.messages.create(
domain=os.environ["MAILGUN_DOMAIN"], # "mg.acme.com"
data={
"from": "no-reply@acme.com",
"to": ["ada@example.com"],
"subject": "Reset your password",
"html": "<p>Your reset link: https://acme.com/reset/abc123</p>",
},
)After: Groundmail (Python)
import os
from groundmail import Groundmail
groundmail = Groundmail(os.environ["GROUNDMAIL_API_KEY"])
email = groundmail.emails.send(
from_="no-reply@acme.com",
to="ada@example.com",
subject="Reset your password",
html="<p>Your reset link: https://acme.com/reset/abc123</p>",
)
print(email["id"]) # msg_…How the fields map
Beyond the basics above, these are the Mailgun fields you're most likely to be passing, and their Groundmail names.
| Mailgun | Groundmail |
|---|---|
| Sending domain in the URL or client call | Taken from the from address, which must be on a verified domain |
Form fields from, to, subject, html, text | JSON fields with the same names |
template + h:X-Mailgun-Variables (or t:variables) | template: { id: "<alias>", variables: { … } } |
h:Reply-To | reply_to |
o:tag, v: custom variables | tags: up to 10 { name, value } pairs, returned on every webhook |
attachment (multipart file) | attachments[] with base64 content and filename |
api.eu.mailgun.net for EU accounts | One endpoint, api.groundmail.dev |
Using Mailgun templates? Send them by alias with template: { id: "<alias>", variables: { … } }. The importer converts your Mailgun templates and publishes them under an alias. More field detail: Mailgun migration docs and Python docs.
Environment variables
| Today | On Groundmail |
|---|---|
MAILGUN_API_KEY | GROUNDMAIL_API_KEY (a gm_… key) |
MAILGUN_DOMAIN | Remove after cutover: the sending domain comes from the from address |
Your webhook secret, e.g. MAILGUN_WEBHOOK_SIGNING_KEY | GROUNDMAIL_WEBHOOK_SECRET: the signing secret shown once when you create the webhook |
Create the key under API keys in the dashboard: the Send only preset is enough for the app. Leave the Mailgun variables set until you cut over, so rolling back is a config change.
DNS: add Groundmail's records, keep Mailgun's until cutover
Add the domain you send from in the dashboard, or with POST /domains. Groundmail gives you these records; on Cloudflare, GoDaddy and Vercel one click writes them for you.
| Record | Type | Host | Value |
|---|---|---|---|
| Ownership | TXT | _groundmail.example.com | Token from the dashboard |
| DKIM | TXT | <selector>._domainkey.example.com | Public key from the dashboard |
| Return path | CNAME | rp.example.com | rp.groundmail.dev (DNS only, not proxied) |
| SPF | TXT | example.com | Add include:spf.groundmail.dev to your existing SPF record |
| DMARC | TXT | _dmarc.example.com | Keep yours; the dashboard suggests one if you have none |
Ownership, DKIM, the return path and SPF must resolve before the domain verifies.
Mailgun records to remove after cutover
- The DKIM TXT record (for example
smtp._domainkeyork1._domainkey) - The
email.tracking CNAME and the MX records on your Mailgun subdomain, if you used one - Take
include:mailgun.orgout of your SPF record (or the SPF record on your Mailgun subdomain).
Wait a few days after the last email goes out through the old provider, in case you need to roll back. Background on each record: SPF, DKIM and DMARC for transactional email.
Webhooks: what changes
| Mailgun | Groundmail | |
|---|---|---|
| Delivery | One event per POST: signature plus event-data | One JSON object per POST: type, created_at and data |
| Checking it came from them | HMAC-SHA256 of timestamp + token with your webhook signing key, sent in the body | Groundmail-Signature: t=…,v1=…: HMAC-SHA256 of t.rawBody with the endpoint's secret |
| Endpoints | Set per domain and per event type | Per URL, with any set of events across all your domains |
If your endpoint doesn't return a 2xx, Groundmail retries the delivery 4 more times: after 5 seconds, 30 seconds, 2 minutes and 2 minutes. Subscribe an endpoint to these events to replace the ones you handle today:
| Mailgun event | Groundmail event |
|---|---|
accepted | email.sent |
delivered | email.delivered |
temporary_fail | email.delivery_delayed |
permanent_fail | email.bounced and email.failed (data.bounce_type is hard or block) |
complained | email.complained |
opened | email.opened |
clicked | email.clicked |
unsubscribed | contact.unsubscribed |
Check the signature against the raw request body, before you parse it. In Python:
Verify a Groundmail webhook (Python)
import hashlib
import hmac
import time
def verify_groundmail_signature(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or not v1 or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
# Flask: verify_groundmail_signature(request.get_data(), request.headers["Groundmail-Signature"], secret)Use Send test event on the webhooks page, or POST /emails/test from CI, to try your handler before real mail flows. Payloads and every event: webhooks.
Mailgun and Groundmail at 50k, 100k and 1M emails
| Monthly volume | Mailgun | Groundmail |
|---|---|---|
| Free option | 100 emails/day, 1 domain | 3,000 emails/month (100/day), no time limit |
| 50,000 emails/month | $35 (Foundation 50k) | $20 (Pro) |
| 100,000 emails/month | $75 (Foundation 100k) | $35 (Pro) |
| 1,000,000 emails/month | $700 (Scale 1M) | $650 (Scale) |
USD per month, monthly billing, cheapest published plan that covers each volume. Mailgun prices as of October 2026 from mailgun.com/pricing; Groundmail prices from our pricing page.
Last checked on each vendor's public page.
Groundmail is $20 against $35 at 50,000 emails a month and $35 against $75 at 100,000. Mailgun's Foundation 100k includes a dedicated IP; Groundmail includes one from 500,000 emails a month.
Plans, overage and what each includes: Mailgun pricing. Everything else side by side: Groundmail vs Mailgun.
Cut over without losing mail
- 1
Put the provider behind a flag
Keep the Mailgun code path and add Groundmail next to it, chosen by an env var such as
EMAIL_PROVIDER, so rolling back is a config change. - 2
Send to yourself first
Trigger a password reset and a receipt to your own addresses, and check the headers show DKIM passing for your domain.
- 3
Move a small share
Send 5 to 10% of real mail through Groundmail for a day, and watch bounces and complaints on the dashboard next to what you see today.
- 4
Ramp to 100%
Then switch everything over, and keep Mailgun configured for a week in case you need to switch back.
- 5
Clean up
Remove the Mailgun package, its env vars and its DNS records, and cancel the plan.
Let the migration tool find every send
Then bring your Mailgun setup across with the importer: paste a Mailgun API key under Import and Groundmail copies your suppressions, templates, sending domains (with the DNS changes) and webhooks (created switched off until your handler is ready). Nothing changes in your Mailgun account, and the key is used for the import only. From a terminal:
Import from Mailgun with the CLI
npm install -g groundmail-cli
groundmail login
export MAILGUN_API_KEY=…
groundmail migrate mailgun --dry-run # preview, nothing written
groundmail migrate mailgun # importFrequently asked questions
How long does it take to move a Python app from Mailgun?
The code change is usually under an hour: one package, the send calls and one env var. Domain verification takes as long as your DNS host takes to publish the records, and is one click on Cloudflare, GoDaddy and Vercel. Plan a few days of partial sending before you turn Mailgun off.
Can I keep sending over SMTP instead?
Yes. If your app sends through smtp.mailgun.org today, point it at smtp.groundmail.dev on port 587 with STARTTLS (or 2525 if your host blocks 587), username groundmail, and an SMTP credential (gmsmtp_…) from the dashboard as the password. Same verified domains, limits and suppressions as the API. See SMTP.
What happens to my Mailgun suppression list?
The importer copies hard bounces, spam complaints and unsubscribes onto your Groundmail suppression list. Bounces that were blocks on Mailgun's servers are left off, because those addresses are fine.
Why do teams move from Mailgun to Groundmail?
Lower prices from 50,000 to 100,000 emails a month, transactional mail kept separate from marketing mail, and a dedicated server on the same API when you need one.
Sources
Facts on this page about other companies' products, prices and policies come from these public pages. They change, so check them before you decide.