Connect Your Mailgun Private API Key to Sparkforge

By Sparkforge Support Team ·Last reviewed May 3, 2026

Find your Mailgun Private API key under API Security, then paste it into Sparkforge at Settings > Email Services. Use the Agency level for shared sending or the Location level for client-specific Mailgun accounts.

The Mailgun Private API key authenticates Sparkforge with your Mailgun account so it can send mail through your verified sending domains and process replies. Treat the key like a password.

What the Private API key does

The key links Sparkforge to Mailgun. Once saved, eligible US-region verified domains appear in the domain dropdown for each Location.

Security note: Don't paste the key in support tickets or screenshots. Rotate it whenever you suspect exposure — generate a new key in Mailgun and update Sparkforge wherever it was stored.

Why agencies set this up

Centralized auth — one Agency-level key powers multiple Locations.
Location override — a specific Location can use its own Mailgun account and domain.
Domain visibility — selecting from a dropdown of verified domains avoids typos and misconfiguration.
Reply handling — a valid key plus the right inbound route lands replies in Conversations.
Rotation — keys can be regenerated in Mailgun and re-pasted into Sparkforge.
Multi-client scale — agencies can standardize onboarding while still respecting client-owned infrastructure.

Prerequisites

A Mailgun account with at least one verified US-region domain (green check).
Access to the Sparkforge Agency view and the relevant Location with permission to open Settings > Email Services.
Correct DNS records: DKIM, SPF, MX, and the tracking CNAME if you use link tracking.
Temporarily relax any Mailgun IP allowlist while syncing, then restore it after validation.

US vs. EU region

Sparkforge reads verified Mailgun domains only from the US region. EU domains won't show in the dropdown. If your domain lives in the EU, create or migrate to a US-region domain.

Set up the API key

Step 1: Copy the key from Mailgun

Log in to Mailgun, click your avatar in the top-right, and choose API Security. Copy the existing Private API key, or generate a new one.

Step 2: Add the key in Sparkforge (Agency level)

In the Agency view, go to Settings > Email Services, select Mailgun, paste the Private API key, pick the verified US domain, and save. Open a Location to confirm the domain appears in its dropdown after sync.

Step 3 (optional): Override at the Location level

You can configure each Location with its own Mailgun key and domain. The Location key overrides the Agency key for that Location.

Configuration patterns

Same Mailgun API + same domain across many Locations.
Same Mailgun API + different domains per Location.
Different Mailgun APIs and different domains per Location for full isolation.
Unique domain per Location for cold inbound email handling.

Troubleshooting

If the domain doesn't appear in the dropdown after saving:

Confirm the domain is in the US region, not EU.
Remove the Mailgun IP allowlist temporarily so Sparkforge can sync. Restore it after the sync completes.
Verify the green checkmark next to the domain in Mailgun.
Confirm you saved the key at the intended level (Agency vs. Location).

Frequently Asked Questions

Do I need the Private or Public API key?

Use the Private API key. Public keys won't authenticate the provider in Sparkforge.

My domain is verified in Mailgun EU. Why can't I select it?

Sparkforge reads verified domains only from the US region. Create or migrate a US-region domain to use it in Sparkforge.

What happens if I paste a key at both the Agency and Location?

The Location configuration overrides the Agency provider for that Location. This lets a specific client run on their own Mailgun account while the rest share the Agency key.

Can multiple Locations share one Mailgun key?

Yes. Paste the key at the Agency level to make verified US-region domains available across Locations. Use Location-level keys when a client needs isolation.

My domain doesn't appear after saving — what next?

Re-check the US region and domain verification, temporarily relax the Mailgun IP allowlist to allow sync, and confirm you saved at the intended level.