Mailgun Platform Help

Help the user with Mailgun (Sinch) platform questions — from sending transactional email via the REST API and SMTP relay through Inbound Email Routing, Templates, Mailing Lists, Domains, Routes, Webhooks, Metrics, and Mailgun Optimize. Mailgun is a developer-first transactional email API service founded in 2010 by Ev Kontsevoy and Taylor Wakefield, acquired by Rackspace (2012), Thoma Bravo (2019), and Sinch (2021). Josh Odom is President of the Sinch Developer & Email unit.

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated knowledge.

Ask the user:

1. What area of Mailgun do you need help with?

   • A) Email API — sending transactional email via REST API (POST /v3/{domain}/messages) or SMTP relay
   • B) SMTP relay — traditional SMTP integration (ports 25/465/587)
   • C) Inbound Email Routing — receiving and parsing incoming email with custom rules (regex/JSONPath), webhook delivery with attachments
   • D) Templates — account-level and domain-level stored templates with Handlebars-like variables
   • E) Mailing Lists — programmatic list management, member CRUD
   • F) Domains API — domain management, DNS verification, DKIM/SPF setup
   • G) Routes — forwarding inbound email to HTTP endpoints or email addresses, or storing for 3 days
   • H) Webhooks — event notifications (accepted, delivered, opened, clicked, permanent_fail, temporary_fail, complained, unsubscribed)
   • I) Metrics API — analytics on deliverability, engagement, and sending health
   • J) Mailgun Optimize — inbox placement seed testing, email validation (single + bulk CSV), sender reputation monitoring, blocklist alerts
   • K) Tags — categorizing and tracking sends
   • L) Account / Billing — plans, pricing, API keys, custom message limits
   • M) Something else — describe it

2. What's your role?

   • A) Developer / engineer
   • B) DevOps / infrastructure
   • C) Admin / account owner
   • D) Founder / solo operator
   • E) Agency / freelancer
   • F) Other

3. What are you trying to accomplish? (describe your specific goal or question)

If the user's request already provides most of this context, skip directly to the relevant step. Lead with your best-effort answer using reasonable assumptions (stated explicitly), then ask only the most critical 1-2 clarifying questions at the end — don't gate your response behind gathering complete context.

Note: If the user needs a specialized skill, route them there with a brief explanation of why that skill is a better fit.

Step 2 — Route or answer directly

If the request maps to a specialized skill, route:

• General email deliverability strategy / best practices -> /sales-deliverability
• Cross-platform email marketing strategy -> /sales-email-marketing
• Email open/click tracking strategy -> /sales-email-tracking
• SendGrid-specific questions -> /sales-sendgrid
• Postmark-specific questions -> /sales-postmark
• Connecting Mailgun to other tools via Zapier or middleware -> /sales-integration
• Funnel strategy / conversion optimization -> /sales-funnel

Otherwise, answer directly from platform knowledge using the reference below.

Step 3 — Mailgun platform reference

Read references/platform-guide.md for detailed module documentation, pricing, integrations, and data model.

You no longer need the platform guide details — focus on the user's specific situation.

Step 4 — Actionable guidance

Based on the user's specific question:

1. Sending transactional email via the API:

   1. Sign up for a Mailgun account and copy your API key from the dashboard
   2. Add and verify a sending domain — add the required DNS records (MX, SPF TXT with include:mailgun.org, DKIM CNAME/TXT)
   3. Wait for DNS propagation and verify the domain in the Mailgun UI or via GET /v3/domains/{domain}
   4. Send your first email: POST /v3/{domain}/messages with Basic Auth (api:YOUR_API_KEY), passing from, to, subject, and text/html fields
   5. Optionally create a Domain Sending Key for production — restricts the key to /messages endpoints only for security
   6. Add tags (o:tag) and custom variables (v:my-var) for tracking and analytics
   7. Monitor delivery via the Events API (GET /v3/{domain}/events) or set up webhooks for real-time notifications

2. Setting up inbound email routing:

   1. Add an MX record for your receiving domain pointing to Mailgun's inbound servers
   2. Verify the domain in the Mailgun UI
   3. Create a route via the API (POST /v3/routes) or UI — define a match expression and action
   4. Match expression examples: match_recipient("[email protected]"), match_header("subject", ".*order.*"), catch_all()
   5. Action examples: forward("https://yourapp.com/webhook"), forward("[email protected]"), store(notify="https://yourapp.com/notify")
   6. Implement your webhook endpoint to receive the parsed email as multipart/form-data (sender, subject, body, attachments)
   7. Use custom parsing rules with regex or JSONPath for advanced routing logic

3. Setting up domain-level templates:

   1. Create a template: POST /v3/{domain}/templates with name, description, and initial version content
   2. Use Handlebars-like variables in the template: {{first_name}}, {{order_number}}, {{items}}
   3. Create additional versions for A/B testing or iteration
   4. Send using the template: include template parameter with the template name and h:X-Mailgun-Variables with the JSON data object
   5. Manage templates programmatically — list, update, delete via the Templates API

4. Configuring webhooks for delivery tracking:

   1. Create a webhook: POST /v3/domains/{domain}/webhooks with the event type (e.g., delivered, opened, permanent_fail) and your endpoint URL
   2. Implement your webhook endpoint to receive JSON payloads
   3. Verify webhook signatures using your API key — Mailgun signs every webhook for security
   4. Handle batch delivery — your endpoint may receive multiple events in a single POST
   5. Return a 200 status code quickly — move heavy processing to a background queue
   6. Set up webhooks for all 8 event types for complete visibility: accepted, delivered, opened, clicked, permanent_fail, temporary_fail, complained, unsubscribed

5. Using Mailgun Optimize for deliverability:

   1. Subscribe to an Optimize add-on plan (Pilot at $49/mo or Starter at $99/mo) — this is separate from your Send plan
   2. Run inbox placement tests: send test emails to Mailgun's seed list and see provider-by-provider inbox vs spam results
   3. Validate email addresses before sending: GET /v4/address/[email protected] — returns risk level (deliverable, undeliverable, risky, unknown)
   4. Bulk validate via CSV upload for list cleaning
   5. Monitor sender reputation and blocklist status in the Optimize dashboard
   6. Set up blocklist alerts to get notified immediately when your IP or domain is listed

Gotchas

Best-effort from research — review these, especially items about plan-gated features and integration gotchas that may be outdated.

1. US vs EU regions require the correct base URL, and you cannot switch after domain creation. US domains use https://api.mailgun.net/v3/, EU domains use https://api.eu.mailgun.net/v3/. Once a domain is created in a region, it cannot be moved to the other. If you need EU data residency for GDPR compliance, create the domain in the EU region from the start. Using the wrong base URL will return authentication errors that can be confusing to debug.
2. Mailgun Optimize is a SEPARATE paid add-on ($49+/mo), not included in any Send plan. Inbox placement seed testing, email validation, sender reputation monitoring, and blocklist alerts all require an Optimize subscription on top of your Send plan. Do not assume these features come with Foundation or Scale plans — they do not.
3. Domain Sending Keys can ONLY send messages — they cannot manage domains, routes, or webhooks. If your application needs to create routes, manage domains, or configure webhooks, you must use your main API key. Domain Sending Keys are restricted to /messages endpoints for security isolation. Using a Domain Sending Key for other API calls will return 401 errors.
4. Dedicated IPs cost $59/mo each and need warmup — do not assume they are included. Dedicated IPs are an add-on available on Scale and Enterprise plans. New dedicated IPs start with no reputation and must be warmed up gradually (start with low volume and increase over 2-4 weeks). Sending high volume on a cold dedicated IP will result in poor deliverability. For lower volumes, Mailgun's shared IP pools often deliver better results.
5. The Free plan is 100 emails per DAY (not month) — very limited for testing. This is significantly more restrictive than it sounds for development and testing workflows. If you need to test bulk sending, webhook handling, or template rendering at any meaningful scale, you will need at least the Foundation plan ($35/mo for 50,000/mo). The daily limit resets at midnight UTC.

• Self-improving: If you discover something not covered here, append it to references/learnings.md with today's date.

Step 5 — Related skills

• /sales-deliverability — Cross-platform email deliverability — SPF/DKIM/DMARC, warmup, inbox placement
• /sales-email-marketing — Opt-in email marketing strategy across tools
• /sales-email-tracking — Email engagement tracking strategy
• /sales-integration — Connect Mailgun to CRM, Slack, or other tools via webhooks/Zapier
• /sales-sendgrid — SendGrid platform help — primary Mailgun competitor
• /sales-postmark — Postmark platform help — primary Mailgun competitor
• /sales-customerio — Customer.io platform help — uses Mailgun-like APIs for transactional
• /sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do

Examples

Example 1: Sending transactional email via the REST API in a Node.js app

User says: "I need to send password reset and order confirmation emails from my Node.js app using Mailgun." Skill does:

1. Guides creating a Mailgun account and copying the API key from the dashboard
2. Walks through adding and verifying a sending domain — adding MX, SPF (include:mailgun.org), and DKIM DNS records
3. Shows how to use the mailgun.js SDK: initialize with API key and domain, then call mg.messages.create() with from, to, subject, html/text
4. Creates two domain-level templates with Handlebars variables — one for password reset ({{reset_url}}, {{expiry_minutes}}) and one for order confirmation ({{order_number}}, {{items}}, {{total}})
5. Recommends creating a Domain Sending Key for production to limit the key's scope to sending only
6. Sets up webhooks for delivered, permanent_fail, and complained events to monitor delivery health and trigger alerts Result: User has production-ready transactional email with templates, scoped API keys, proper DNS authentication, and delivery monitoring

Example 2: Setting up inbound email routing for a support system

User says: "We want to receive customer reply emails at [email protected] and forward them to our ticketing webhook." Skill does:

1. Guides adding an MX record for ourdomain.com pointing to Mailgun's inbound servers
2. Verifies the domain in the Mailgun UI
3. Creates a route via the API: match_recipient("[email protected]") with action forward("https://app.ourdomain.com/api/tickets/inbound")
4. Explains the webhook payload format — sender, subject, stripped-text (clean body without quoted reply), attachments as file uploads
5. Recommends a fallback route with catch_all() to store unmatched inbound email for 3 days (store(notify="https://app.ourdomain.com/api/catchall")) so nothing is silently dropped
6. Shows how to use custom parsing rules with regex to extract ticket IDs from subject lines for routing to existing tickets Result: User has inbound email routing that forwards customer replies to their ticketing system with a catch-all safety net

Example 3: Improving deliverability with Mailgun Optimize

User says: "Our Mailgun emails are landing in spam at Gmail. How do we diagnose and fix this?" Skill does:

1. Checks if the user has Mailgun Optimize — if not, recommends the Pilot plan ($49/mo) for inbox placement testing
2. Runs an inbox placement seed test to confirm where emails land across Gmail, Outlook, Yahoo, and other providers
3. Reviews domain DNS authentication — verifies SPF, DKIM, and DMARC records are properly configured via the Domains API
4. Checks sender reputation in the Optimize dashboard for blocklist appearances and reputation scores
5. Validates the sending list via bulk CSV upload to remove invalid, disposable, and risky addresses (reducing bounce rates by up to 21%)
6. Reviews the complained webhook events to identify content or recipients generating spam complaints Result: User identifies the root cause of spam placement (e.g., missing DMARC, blocklisted IP, high bounce rate) and has a concrete remediation plan with ongoing monitoring

Troubleshooting

Emails rejected with 401 Unauthorized when using Domain Sending Key

Symptom: API calls return 401 Unauthorized for endpoints like GET /v3/domains or POST /v3/routes, but sending email works fine Cause: Domain Sending Keys are restricted to /messages endpoints only. They cannot be used to manage domains, routes, webhooks, mailing lists, or any other Mailgun resource. This is by design for security isolation. Solution: Use your main API key (found in the Mailgun dashboard under API Security) for non-sending operations. Reserve Domain Sending Keys for production sending code only. If you need to manage resources programmatically, store the main API key securely in environment variables and use it for admin operations in a separate service or deployment pipeline.

Webhook events not arriving at endpoint

Symptom: You configured webhooks in Mailgun but your endpoint is not receiving any events — no requests appear in your server logs Cause: Common causes include: (1) the webhook URL is not publicly accessible (localhost or behind a firewall), (2) the endpoint is returning non-2xx status codes causing Mailgun to back off after retries, (3) the webhook was configured for the wrong domain, or (4) the events are not being generated (e.g., open/click tracking is not enabled). Solution: Verify your endpoint is publicly accessible — use a tool like ngrok for local development. Check the Mailgun dashboard under Sending > Webhooks for delivery status and recent attempts. Ensure your endpoint returns a 200 status code quickly (within a few seconds). Confirm the webhook is configured for the correct domain. For open/click events, verify tracking is enabled in domain settings. Test with a simple endpoint (e.g., webhook.site) to isolate whether the issue is with Mailgun's delivery or your endpoint's handling.

Emails sending from US region but domain is in EU (or vice versa)

Symptom: API calls return 404 or authentication errors when trying to send email, even though the domain is verified and the API key is correct Cause: The domain was created in one region (US or EU) but the API calls are being made to the other region's base URL. US domains must use https://api.mailgun.net/v3/, EU domains must use https://api.eu.mailgun.net/v3/. Domains cannot be moved between regions after creation. Solution: Check which region your domain is in via the Mailgun dashboard (look for the region indicator on the domain page). Update your API base URL to match the domain's region. If you need to switch regions (e.g., for GDPR compliance), you must delete the domain and recreate it in the correct region — then re-verify DNS records. Update all application configuration, environment variables, and SDK initialization to use the correct regional URL.