sales-mailgun

What this skill does

# 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