# Mailgun MCP

> Mailgun (Transactional Email & Domains) lets your AI client manage complex email infrastructure. You can send high-priority transactional messages, audit domain health via DNS records (SPF/DKIM), and track delivery failures. It also monitors bounce lists and unsubscribes so you know exactly where your emails are going wrong.

## Overview
- **Category:** ship-it
- **Price:** Free
- **Tags:** transactional-email, email-infrastructure, delivery-logs, domain-health, suppression-management, smtp-api

## Description

Your agent uses **`send_email`**, which lets you send high-priority transactional or marketing emails using your configured domains and custom HTML templates. You'll never have to manually call the API again; just tell your AI client what you gotta send, and it handles the secure routing.

### Domain Setup and Verification

Before sending anything, you gotta make sure your setup is tight. Use **`list_domains`** to pull a complete rundown of every domain sitting on your Mailgun account. Need details on one specific domain? Run **`get_domain`**; that pulls the full DNS records—SPF, DKIM, and MX—so you can verify everything's configured right for top deliverability.

### Checking Addresses Before You Send a Dime

Don't waste credits sending to dead ends. The **`validate_email`** tool checks if an address is actually valid and technically deliverable through the dedicated Mailgun validation endpoint, letting you block hard bounces before they even happen.

### Crafting and Sending Messages

When it comes time to write, you'll first need templates. Use **`get_templates`** to list all stored HTML Handlebars templates attached to your domain so you know what content options are available for the send. Once you’ve got your template ready, you use **`send_email`**, which handles sending transactional or marketing messages using verified domains.

### Tracking What Happens After You Hit Send

Once the emails are out there, you need to watch 'em like a hawk. The **`list_logs`** tool gives you raw event logs for any domain over time; this tracks everything—deliveries, opens, drops, and bounces—giving you a chronological record of every single email's journey.

For performance metrics, run **`get_stats`**. This pulls key analytics data, specifically open rates and click-through rates, tied to your specified Mailgun domain. You can also use **`list_bounces`** and **`list_unsubscribes`** together to audit the suppression list for both bounced addresses and explicit unsubscribes across a given domain.

If you find an address that bounced but you gotta try sending it again, use **`delete_bounce`**. This tool permanently removes a specific bounced email address from your domain's suppression list. Finally, if you want to see exactly who quit receiving mail, run **`list_unsubscribes`**; this lists every single email that explicitly opted out of receiving messages for your domain.

## Tools

### delete_bounce
Permanently removes a bounced email address from your domain's suppression list.

### get_domain
Fetches the full DNS records and specific details for any configured Mailgun domain.

### get_stats
Retrieves key analytics data, including open rates and click-through rates, for a specified Mailgun domain.

### get_templates
Lists all stored HTML Handlebars templates associated with your domain, so you know what content is available to send.

### list_bounces
Checks the suppression list for bounced emails and unsubscribes across a specific domain.

### list_domains
Returns a complete list of every domain currently configured on your Mailgun account.

### list_logs
Gets raw event logs, tracking all deliveries, opens, drops, and bounces for a given domain over time.

### list_unsubscribes
Lists every email address that has explicitly unsubscribed from receiving mail for your domain.

### send_email
Sends a transactional or marketing email to a target recipient using the Mailgun API.

### validate_email
Checks whether a provided email address is valid and deliverable through the dedicated Mailgun validation endpoint.

## Prompt Examples

**Prompt:** 
```
Send a transactional email to 'user@example.com' from 'support@mg.domain.com' with subject 'Order Confirmed'
```

**Response:** 
```
Dispatching email… I've successfully sent the message to 'user@example.com' via the 'mg.domain.com' domain. The Message ID is '202603271234.abc@mg.domain.com'. Would you like me to monitor the event logs for delivery status?
```

**Prompt:** 
```
Check the DNS health for domain 'mg.mycompany.com'
```

**Response:** 
```
Retrieving domain details… For 'mg.mycompany.com', SPF and DKIM records are verified and active. However, the MX records are currently marked as 'Unverified'. You may need to update your DNS settings to receive replies. Would you like the exact MX values to add?
```

**Prompt:** 
```
List all bounced emails for 'mg.mycompany.com' from the last hour
```

**Response:** 
```
Retrieving bounce logs… I've identified 3 bounced addresses: 'old-user@gmail.com' (5.1.1 User unknown), 'invalid-addr@yahoo.com', and 'full-mailbox@outlook.com'. Would you like me to remove 'full-mailbox@outlook.com' from the suppression list so you can try again?
```

## Capabilities

### Audit Domain DNS Records
Retrieves the full set of DNS records (SPF, DKIM, MX) for a specified Mailgun domain to verify proper setup.

### Send Verified Transactional Emails
Sends emails using your configured domains and templates, ensuring high deliverability by routing through the secure sending mechanism.

### Track Delivery Failures and Open Rates
Queries raw event logs to provide a chronological record of deliveries, opens, bounces, or any other anomalous traffic spike.

### Manage Suppression Lists
Lists and audits bounced emails and unsubscribes. You can also delete specific suppressions to retry sending an address.

### Validate Email Addresses Before Sending
Uses the dedicated Mailgun API endpoint to check if a target email address is technically valid and deliverable, preventing hard bounces upfront.

## Use Cases

### The 'Did the Campaign Actually Send?' Check
A growth engineer needs to know why a batch email failed. Instead of jumping between three different dashboards, they prompt their agent: 'List all logs for domain X last night.' The agent runs `list_logs`, identifies 50 bounces, and tells them the specific error code (e.g., invalid recipient). They then use this data to update their CRM.

### Validating a New Client Domain
A developer is setting up a new client domain for testing. They don't want to risk sending test emails until the DNS is perfect. They prompt: 'Check the DNS records for mg.newclient.com.' The agent runs `get_domain` and immediately reports if SPF/DKIM are missing, blocking them from proceeding until the issue is fixed.

### Responding to a Blocked Sender
The ops team gets an alert that their sending reputation dropped. They prompt: 'List all bounces and unsubscribes for our main domain.' The agent runs `list_bounces` and finds 50 old, inactive addresses. The manager uses this list to manually remove the worst offenders using `delete_bounce`, improving overall sender hygiene.

### Quickly Sending a Confirmation Email
A user signs up for service and needs an immediate welcome email. They prompt: 'Send a welcome email to john@example.com.' Before the agent calls `send_email`, it first runs `validate_email` on the address. If the validation fails, the agent tells them immediately instead of sending an error report.

## Benefits

- **Pinpoint Delivery Failures:** Instead of guessing why an email failed, use `list_logs` to extract raw chronological data. You'll see the exact event—was it a bounce? A drop? This level of detail is impossible through standard dashboards.
- **Pre-flight Checks are Mandatory:** Never send an email without checking first. Use `validate_email` before calling `send_email`. It prevents hard bounces and saves you time cleaning up failed campaigns.
- **Confirm Domain Setup Instantly:** Before your next big campaign, run `get_domain`. You immediately verify if critical records like SPF and DKIM are active, eliminating the risk of being blocked by receiving servers.
- **Control Your Suppression List:** Bounce lists get messy. With `list_bounces`, you can see exactly which addresses bounced and, if necessary, use `delete_bounce` to manually re-add them for a retry send.
- **Know Your Full Footprint:** Use `list_domains` first. It gives you an inventory of every active domain on your account, ensuring no critical sending source gets forgotten or mismanaged.

## How It Works

The bottom line is: You manage critical email infrastructure by talking to it, without ever having to write a single API request yourself.

1. First, subscribe to the server and provide your Mailgun Private API Key. This gives your AI client the necessary access credentials.
2. Next, tell your agent what you need—for example, 'Check the DNS health for my main domain' or 'Send a welcome email.'
3. The agent executes the required tool call against your live Mailgun account and presents the raw data (DNS records, logs, etc.) to you.

## Frequently Asked Questions

**How do I check if my domain is set up correctly using get_domain?**
Run `get_domain` and check the output for SPF, DKIM, and MX records. If these records are missing or marked as 'Unverified', your emails might fail to deliver properly.

**What's the difference between list_logs and list_bounces?**
`list_logs` gives you a raw history of every event (open, drop, bounce) that happened over time. `list_bounces`, however, is specifically for auditing addresses that failed delivery and managing them in the suppression list.

**Can I send an email without first using validate_email?**
Yes, you can call `send_email` directly. But it's a bad idea. Always run `validate_email` first to confirm the address is active and deliverable. This stops hard bounces before they happen.

**How do I list all my domains configured on Mailgun?**
You just need to call `list_domains`. It gives you a complete inventory of every domain attached to your account, which is useful for auditing and ensuring coverage.

**When should I use the irreversible action of `delete_bounce`?**
You can only delete a bounced email if you confirm it was an incorrect entry or spam bounce. Remember, this action is permanent and removes the record entirely; don't run it unless you are certain about the data integrity issue.

**Using `get_templates`, what information can I find to ensure consistent messaging?**
The tool lists all HTML Handlebars templates stored for your domain. This helps you audit your existing professional message formats, ensuring that every email sent via the agent uses approved and brand-consistent code.

**How does `list_unsubscribes` help me maintain compliance?**
`list_unsubscribes` gives you a clean list of addresses that opted out. You must respect these records; never attempt to send any messages to an email listed here, regardless of how long ago they unsubscribed.

**Beyond basic DNS checks, what metrics does `get_stats` provide?**
`get_stats` pulls domain-level analytics beyond connectivity. It tracks actual performance data like open rates and click-through rates, letting you measure the real success of your campaigns.

**Can I check if my domain's DNS records are correctly configured?**
Yes. Use the `get_domain` tool by providing your verified domain name. Your agent will retrieve the status of SPF, DKIM, and MX records, helping you identify if any DNS dependencies are missing or misconfigured.

**How do I see which emails have recently bounced from my domain?**
The `list_bounces` tool allows your agent to extract the suppression logs for a specific domain. You'll see the email addresses that failed to deliver, providing insights into audience health or sending boundaries.

**Can my agent validate an email address before I send a message?**
Absolutely. Use the `validate_email` tool to check if an address is valid, deliverable, and doesn't belong to a disposable service. This is perfect for ensuring high-quality data before triggering outbound sends.