# Mailtrap MCP

> Mailtrap connects your AI agent to a full email sandbox environment. It lets you send, test, and debug transactional emails in staging before they hit production. You can inspect captured emails, analyze spam scores, track bounces, and manage multiple projects without ever sending anything live. This is for developers who need proof that an email looks right everywhere.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** email-sandbox, smtp-testing, email-debugging, html-analysis, spam-scoring, transactional-email

## Description

This server connects your AI agent directly to Mailtrap's sandbox environment. You're outta guessing if your emails look right; you test 'em in a safe zone before they hit any real inbox. It lets your agent send, inspect, and debug transactional messages without ever touching live production channels.

**Getting Set Up and Listing Environments**

You start by letting your agent check what accounts are available using **`list_accessible_accounts`**, which shows every Mailtrap account linked to this API key. You can then see all the active projects and sandboxes you're managing with **`list_mailtrap_projects`**. If you need a quick overview of everything, **`list_sandboxes`** returns a list of every virtual testing sandbox you've set up.

Before sending anything, your agent can check which domains are good to go using **`list_verified_domains`**, giving you a rundown of all the sending domains that have been fully verified and are ready for use. You'll also get proof on your domain setup by calling **`get_domain_status`**; this function retrieves detailed status and verification information, confirming required details like SPF or DKIM records.

**Sending Test Messages vs. Live Mail**

When you need to test a message, your agent triggers **`send_test_email`**. This sends a non-live email that lands only in the controlled sandbox for inspection, keeping it safe from real people. If you're actually ready to send something live through verified channels, the agent uses **`send_production_email`** to fire the message out immediately.

**Inspecting and Debugging Captured Emails**

The heart of this server is debugging what got captured. First, your agent runs **`list_sandbox_messages`**, which provides a summary list showing all messages currently sitting in an inbox. Once you know there's a message there, you can pull the full metadata using **`get_message_details`**. This function fetches key details about that specific captured message, including its spam score and headers for immediate analysis. If you need to see exactly how the email was structured on the front end, you use **`get_message_html`** to retrieve the full, raw HTML body of any saved message; this is crucial for deep debugging. You can also get a clean list of all sandboxes using **`list_sandboxes`**, and if you need to check what's in a specific inbox, your agent can run **`list_mailtrap_projects`** to help navigate the captured messages.

**Managing and Cleaning Up Sandboxes**

When testing is done, you gotta clean up. If an entire sandbox inbox is cluttered with old test data, your agent uses **`clear_sandbox_inbox`** to delete every single captured email from that specific sandbox. If it's just one message that's garbage or needs removing, the agent can call **`delete_sandbox_message`**, which removes a single captured email from the sandbox history. This gives you complete control over your testing environment.

## Tools

### clear_sandbox_inbox
Deletes all captured emails from a specific sandbox inbox.

### delete_sandbox_message
Removes one captured email message from the sandbox history.

### get_domain_status
Retrieves detailed status and verification information for your sending domains.

### get_message_html
Retrieves the full, raw HTML body of any saved email message.

### get_message_details
Fetches metadata about a specific captured message, including spam score and headers.

### list_accessible_accounts
Lists all Mailtrap accounts connected to this API key.

### list_verified_domains
Shows a list of all sending domains that are currently verified and ready for use.

### list_sandboxes
Lists every virtual, accessible testing sandbox you have set up.

### list_sandbox_messages
Shows a summary list of all messages currently captured in an inbox.

### list_mailtrap_projects
Retrieves a list of active projects and sandboxes within your account.

### send_production_email
Sends an email immediately through your live, verified production channels.

### send_test_email
Sends a non-live test email that lands only in the sandbox for inspection.

## Prompt Examples

**Prompt:** 
```
Show testing inboxes and recent captured emails.
```

**Response:** 
```
Inboxes: 3 active. 'Staging Env' (45 messages), 'QA Pipeline' (12), 'Dev Local' (0). Staging Latest: 'Welcome User' (to: test@user.com). Received: 2 min ago. Spam Score: 0.1 (Excellent ✅). HTML size: 45 KB. B2B Client Support: 98% compatibility.
```

**Prompt:** 
```
Show transactional sending analytics for this week.
```

**Response:** 
```
Sending (7 days): 12,500 emails. Delivered: 12,250 (98% ✅). Bounces: 150 (1.2%). Hard: 45, Soft: 105. Open rate: 45%. Click rate: 12%. Spam complaints: 2 (0.01%). Top template: 'Password Reset' (3,400 sent, 100% delivered). Delivery speed: avg 1.2s.
```

**Prompt:** 
```
Analyze the spam score for the last captured email.
```

**Response:** 
```
Analysis for message 'Invoice #890': Overall Spam Score: 2.4 (Good ✅, threshold is 5.0). SpamAssassin checks: 0.0 HTML_MESSAGE, 0.1 MIME_HTML_ONLY. Blacklists: Not listed on 18/18 checks ✅. Authentication: SPF pass, DKIM pass. Recommendation: Improve text-to-image ratio.
```

## Capabilities

### Send a test email to the sandbox
Your agent sends an email using `send_test_email`, which routes the message only to your controlled testing inboxes.

### Get raw HTML of any captured email
You use `get_message_html` to retrieve the full, unparsed HTML source code from a specific sandbox message for deep inspection.

### Analyze domain status and headers
The agent calls `get_domain_status` to verify if your sending domains are set up correctly, checking required details like SPF/DKIM records.

### List all active testing inboxes
You use `list_sandboxes` to see a summary of every virtual inbox or project you manage within Mailtrap.

### Send an email to production
The agent triggers `send_production_email`, which sends the message out through your verified sending domains, simulating live delivery.

## Use Cases

### Verifying a new signup email template.
The marketing team changes the newsletter design. Instead of sending it to 10,000 people and dealing with complaints, they use their agent to run `send_test_email`. They then ask the agent to call `get_message_html` on the resulting message in the sandbox. This confirms the new CSS structure works before any code hits production.

### Debugging a failed password reset link.
A user reports the 'Forgot Password' email is broken. The agent first uses `list_accessible_accounts` to select the correct environment, then triggers `send_test_email`. They check `get_message_details` on the captured message and see a low spam score or missing headers, pinpointing the exact failure point.

### Auditing domain readiness for a migration.
The ops team is moving to a new sender domain. They don't want failed sends. The agent first runs `list_verified_domains` and then calls `get_domain_status`. If the status shows any gaps, they fix them before attempting to use `send_production_email`.

### Analyzing a batch of captured emails.
A QA engineer needs to check 50 messages from last night's test run. Instead of manually clicking into each one, they tell their agent to use `list_sandbox_messages` for an overview, then loop through the IDs using `get_message_details` to quickly compare spam scores and headers.

## Benefits

- Stop guessing if your emails look right. Use `get_message_html` to inspect the raw source code of captured messages, guaranteeing consistency across clients.
- Manage complexity with `list_sandboxes`. You can keep dedicated testing inboxes for different features (e.g., 'Signup Flow' vs. 'Password Reset') without mixing data.
- Catch failure before sending. Before using `send_production_email`, check the domain health first by calling `get_domain_status` to verify your credentials are solid.
- Deep dive into bounces and opens. The system tracks crucial delivery metrics, allowing you to analyze open rates and click paths from historical data.
- Control your environment completely. Use `list_sandbox_messages` to see a quick list of what's captured, or `delete_sandbox_message` if the record is stale.

## How It Works

The bottom line is: you treat email testing like debugging code—you inspect the input (the HTML), check the environment (domain status), and verify the output (message data) before deployment.

1. First, give your AI client the Mailtrap API Key and Account ID. This connects it to your sandbox.
2. Next, run a discovery tool like `list_sandboxes` to see what testing environments are available for this project.
3. Finally, use tools such as `get_message_details` on a specific message ID. The agent pulls the metadata (spam score, headers) and presents it right in your chat.

## Frequently Asked Questions

**How do I check if my domains are set up correctly with Mailtrap MCP Server?**
You call the `get_domain_status` tool. This function checks your domain's current status, verifying things like SPF and DKIM records against best practices.

**What is the difference between send_test_email and send_production_email?**
`send_test_email` sends a non-live message that only appears in your secure sandbox. `send_production_email` uses your live, verified credentials to deliver mail out into the real world.

**Can I see the raw source code of an email using Mailtrap MCP Server?**
Yes, use `get_message_html`. This tool pulls the complete, unparsed HTML body of a captured message, which is essential for QA checks.

**How do I find all my available testing environments with Mailtrap MCP Server?**
You run `list_sandboxes`. This command gives you an immediate list of every virtual inbox or project you can target for sending tests and inspection.

**How do I use the `clear_sandbox_inbox` tool with Mailtrap MCP Server?**
It immediately deletes all emails from your current sandbox inbox. This is useful when you need a clean slate before running a new test flow, ensuring old messages don't confuse your debugging process.

**What kind of metadata does `get_message_details` provide via Mailtrap MCP Server?**
It gives you core message metadata like headers, bounce status, and detailed spam scores. This lets you debug *why* an email might fail delivery before it reaches a real user.

**How does the Mailtrap MCP Server manage multiple client accounts?**
The server allows you to list available accounts and switch between them within your agent. You don't have to reconfigure your AI client when testing different development environments or domains.

**Can I verify my sending domain setup using Mailtrap MCP Server?**
You use the domain status tools to check for authentication issues. This confirms that your external sending domain is properly set up and ready for both test and production email sends.

**Can I both test and send emails with Mailtrap?**
Yes. Mailtrap supports both Email Testing (capturing emails in staging) and Email Sending (transactional delivery in production).

**Does Mailtrap require an Account ID?**
Yes. You need both an **API Key** and **Account ID** to authenticate via Bearer token against `mailtrap.io/api`.

**Can I analyze spam scores and HTML rendering?**
Yes. Mailtrap analyzes captured emails for spam score (SpamAssassin), blacklists, HTML errors, and client support.