# Mailgun setup for PopMCP

You paste one Mailgun API key. An Account API key reaches every domain in both the US and EU regions; a Domain Sending Key also connects, send-only, when you type its domain in the optional default sending domain field.

- Auth: API credentials
- Setup time: 3 min
- API base URL: https://api.mailgun.net (EU domains: https://api.eu.mailgun.net)
- Credentials screen: https://app.mailgun.com/settings/api_security
- Provider docs: https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/

## Before you begin

- A Mailgun account with at least one sending domain. A sandbox domain, or a Free plan with no card on file, only delivers to Authorized Recipients until you add a custom domain.
- The admin role on the Mailgun account, because only admins can create API keys
- If you have several sending domains, the one tools should use when a request doesn't name one, such as mg.example.com
- No region to look up: PopMCP finds US and EU domains itself

## Get your credentials

### 1. Open API Security

Sign in at `app.mailgun.com` as an admin. Open the profile menu in the top right and choose API Security. Some Mailgun docs show the same page as Account Settings then API keys.

Screen: https://app.mailgun.com/settings/api_security

### 2. Add a key with the Admin or Developer role

Click Add new key, enter a description such as `PopMCP`, choose a role if your plan offers roles, and click Create Key. Admin reaches every tool. Developer covers everything except API keys, SMTP credentials and users. Analyst is read-only. A key's role can't be changed later, only replaced with a new key.

Screen: https://app.mailgun.com/settings/api_security

### 3. Copy the key while it is shown

Copy the new key straight away. It looks like 32 hex characters followed by two groups of 8, separated by hyphens. Mailgun shows a role-based key only once, so store it before closing the dialog.

Screen: https://app.mailgun.com/settings/api_security

### 4. Check your sending domains

Open Domains and note the domain tools should use by default, exactly as it is listed, for example `mg.example.com`. Using a Domain Sending Key instead of an account key? Select the domain, open its sending keys tab and click Add Sending Key; that key can only send mail for its own domain.

Screen: https://app.mailgun.com/

### 5. Paste the key into PopMCP

Paste the key into API key. Fill Default sending domain (optional) only if you have several domains or pasted a Domain Sending Key. You never pick a region: PopMCP lists your domains on both the US and EU hosts and sends each call to the domain's own region.

## Fields PopMCP asks for

- API key (apiKey) [required]: In Mailgun open API Security (profile menu, or app.mailgun.com/settings/api_security) and click Add new key. Admin unlocks every tool; Developer covers everything except API keys, SMTP credentials and users; Analyst is read-only. Stored encrypted and sent only to Mailgun.
- Default sending domain (optional) (domain): Used when a tool isn't told which domain to act on. Leave it empty if you have one sending domain. Fill it in if you paste a Domain Sending Key, which can only send mail for its own domain.

## Verify

PopMCP shows Mailgun as Verified with a label such as `Mailgun · mg.example.com (US)`, `Mailgun · 3 domains (US + EU)`, or `(send only)` for a Domain Sending Key. Ask for yesterday's failed deliveries: mailgun_list_events returns real events instead of an authentication error.

## Troubleshooting

### "Mailgun rejected this API key" when connecting

Cause: The key was cut short, revoked or expired, it is a Domain Sending Key with no domain typed, or your Mailgun account restricts API access to an IP allowlist.

Fix: Create a fresh Account API key under API Security with the Admin or Developer role and paste it whole. For a Domain Sending Key, also fill Default sending domain (optional).

### "That's the Public validation key, which can only validate addresses"

Cause: The pubkey-... value was copied instead of an account key.

Fix: Copy an Account API key from API Security (Add new key) instead.

### "The domain ... isn't in this Mailgun account"

Cause: The default sending domain has a typo, or it is the From domain (example.com) rather than the Mailgun sending domain (mg.example.com).

Fix: Copy the domain exactly as Mailgun lists it under Domains, or leave the field empty.

### "This Mailgun tool needs a domain and your account has several"

Cause: No default sending domain is set and the request didn't name one.

Fix: Tell the AI which domain to use, or reconnect with Default sending domain (optional) filled in.

### Sends from a sandbox domain fail with a message that the domain is not allowed to send

Cause: Sandbox domains, and Free plans with no card on file, only deliver to Authorized Recipients.

Fix: Add the recipient as an Authorized Recipient in Mailgun, or add and verify a custom sending domain.

### 403 "Valid credentials but access denied" on writes

Cause: The key's role is too narrow for that action, for example an Analyst key trying to send or a Developer key managing API keys.

Fix: Roles can't be edited. Create a new key with the Developer or Admin role and reconnect.

### "Domain not found" for a domain you know exists

Cause: The domain sits in the other region or was created after you connected, and Mailgun's regional hosts don't see each other's domains.

Fix: Try again once: PopMCP looks up a new domain's region the first time a tool uses it. If it persists, reconnect so PopMCP re-reads the domain list from both regions.

---

Source: https://www.docs.popmcp.com/docs/integrations/mailgun/