Connect Mailtrap to Claude: Handle contacts, lists, and delivery data

If you need to connect Mailtrap to Claude to automate deliverability audits, manage suppression lists, dynamically route webhooks, or sync contact directories, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's function calling capabilities and Mailtrap's REST APIs. You can either build and maintain this infrastructure yourself - mapping schemas, handling authentication lifecycles, and managing error passthrough - or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL in seconds.

If your team uses ChatGPT, check out our guide on connecting Mailtrap to ChatGPT or explore our broader architectural overview on connecting Mailtrap to AI Agents.

Giving a Large Language Model (LLM) read and write access to your transactional and marketing email infrastructure is a massive engineering challenge. You have to handle domain compliance requirements, asynchronous contact imports, and strict API rate limits. Every time Mailtrap updates an endpoint or deprecates a field, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Mailtrap, connect it natively to Claude Desktop, and execute complex deliverability workflows using natural language.

The Engineering Reality of the Mailtrap API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Mailtrap's specific API surface is painful. You are not just integrating a generic API - you are dealing with email deliverability infrastructure, which comes with unique compliance and architectural constraints.

If you decide to build a custom MCP server for Mailtrap, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous Bulk Operations Mailtrap's contact management is designed for scale. When you import contacts, you do not receive a synchronous success response. The create_a_mailtrap_contacts_import endpoint accepts up to 50,000 contacts in a single payload and returns a job ID. If you expose this raw behavior to Claude without context, the LLM will assume the import failed or hallucinate a success state. Your MCP server must explicitly guide the model to use the job ID to poll the get_single_mailtrap_contacts_import_by_id endpoint until the status changes to completed. Truto handles the schema descriptions that explicitly instruct the LLM on how to navigate these asynchronous states.

Strict Rate Limits and Error Passthrough Mailtrap enforces strict rate limits, particularly on administrative endpoints. For example, adding an email to a suppression list is capped at 10 requests per minute per account. A common mistake engineers make when building custom MCP servers is attempting to absorb these rate limits silently via middleware retries. This causes the LLM to hang, eventually timing out the tool call entirely.

Truto takes a deterministic approach: Truto does not retry, throttle, or apply backoff on rate limit errors. When Mailtrap returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller. Crucially, Truto normalizes the upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This means your Claude agent receives immediate, structured feedback that it has hit a limit, allowing the model (or your underlying agent framework) to decide how long to wait before retrying.

Multi-Step Domain Compliance Creating a sending domain in Mailtrap is not a single API call. It requires creating the domain, extracting the generated DNS records (SPF, DKIM, DMARC), and associating company information via create_a_mailtrap_domain_company_info to meet compliance verification standards. A custom MCP server requires you to write complex tool descriptions so the LLM understands this dependency chain. Truto dynamically maps these dependencies from integration documentation, ensuring Claude knows exactly which sequence of tools to call to successfully provision a verified domain.

How to Generate a Mailtrap MCP Server with Truto

Truto dynamic MCP servers derive their tool definitions directly from the integration's documented API schema. There is no code to write. You authenticate the Mailtrap account once, and Truto generates a standardized JSON-RPC 2.0 endpoint that serves the tools.

There are two ways to generate this server: via the Truto UI for one-off tasks, or via the API for programmatic provisioning.

Method 1: Via the Truto UI

If you are an IT admin or developer setting up Claude Desktop for personal or internal team use, the UI is the fastest path.

1. Log into your Truto dashboard and navigate to your Integrated Accounts.
2. Click on your connected Mailtrap account.
3. Navigate to the MCP Servers tab.
4. Click Create MCP Server.
5. Configure your server settings (e.g., assign a name, filter to specific tags, or set an expiration date).
6. Click Generate and copy the resulting URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

If you are embedding AI agents into your own B2B product and need to generate MCP servers dynamically for your customers, you will use the REST API.

Make a POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mailtrap Deliverability Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["deliverability", "contacts"]
    }
  }'

The API provisions the server, validates that Mailtrap tools are available, stores a cryptographically hashed token in Cloudflare KV for sub-millisecond authentication, and returns a ready-to-use URL:

{
  "id": "mcp_8f7d6c5b",
  "name": "Mailtrap Deliverability Agent",
  "config": { "methods": ["read", "write"], "tags": ["deliverability", "contacts"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
}

How to Connect the Mailtrap MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude takes seconds. Because the URL contains a cryptographic token mapped to your specific Mailtrap integrated account, no further authentication or header configuration is required on the client side (unless you explicitly enabled extra API token validation).

Method 1: Via the Claude UI

(Note: Anthropic is continually updating the Claude UI to expose native connector management. If you are using ChatGPT, you can navigate to Settings → Connectors → Add, paste the URL, and click Add. For Claude Web, look under Settings → Integrations → Add MCP Server).

1. Open your Claude settings.
2. Navigate to the Integrations or Connectors section.
3. Click Add Server.
4. Paste your Truto MCP URL and save. Claude will instantly handshake with the server, request the tools/list, and surface the Mailtrap capabilities.

Method 2: Via Manual Configuration File (Claude Desktop)

If you are using Claude Desktop and prefer managing your configurations via JSON, you can add the server using the standard Server-Sent Events (SSE) transport adapter provided by the MCP community.

Open your Claude Desktop config file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "mailtrap_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
      ]
    }
  }
}

Save the file and restart Claude Desktop. The application will initialize the MCP protocol, pulling in the schemas for your Mailtrap integration.

Hero Tools for Mailtrap

Truto exposes dozens of Mailtrap endpoints as discrete tools. Instead of overwhelming the LLM with generic CRUD operations, we highly recommend filtering your MCP server to expose only the highest-leverage operations. Here are the hero tools you should prioritize for deliverability and contact management workflows.

List All Mailtrap Stats

Tool name: list_all_mailtrap_stats

This tool retrieves high-level account sending aggregates, mirroring the data shown in the Mailtrap Stats dashboard. It returns delivery counts, bounce rates, open rates, click tracking, and spam reports. It requires a start_date and end_date, making it perfect for generating weekly deliverability health briefs.

"Claude, pull my Mailtrap sending stats for the last 7 days. Calculate the bounce-to-delivery ratio, and if it exceeds 2%, warn me and suggest potential deliverability issues we might be facing."

Create a Mailtrap Suppression

Tool name: create_a_mailtrap_suppression

This tool allows the agent to add an email address directly to the Mailtrap suppression list, preventing any future emails from being sent to that recipient from the associated account. This is critical for automated bounce handling and GDPR compliance workflows. Note: this endpoint enforces a strict 10 request/minute rate limit.

"A customer at user@example.com just filed a hard complaint via our support desk. Please add their email to the Mailtrap suppression list immediately for our primary sending stream to prevent further automated outreach."

List All Mailtrap Email Logs

Tool name: list_all_mailtrap_email_logs

When troubleshooting why a specific email never arrived, developers historically had to dig through the Mailtrap UI. This tool gives Claude read access to your email message logs, returning the message ID, send status, and timestamp.

"We have a report that John Doe never received his password reset email yesterday. Check the Mailtrap email logs for any messages sent to his email address in the last 24 hours and tell me if they bounced or were successfully delivered."

Create a Mailtrap Domain

Tool name: create_a_mailtrap_domain

This infrastructure tool provisions a new sending domain for email authentication. When called, Mailtrap generates and returns the required DNS records (SPF, DKIM, DMARC) that must be added to the domain's registrar to verify ownership and ensure high deliverability.

"We are launching a new marketing campaign from 'updates.ourbrand.com'. Create this new sending domain in Mailtrap, then output a formatted markdown table containing the exact DNS records our IT team needs to add to Route53 to verify it."

Create a Mailtrap Contacts Import

Tool name: create_a_mailtrap_contacts_import

This tool initiates a bulk, asynchronous contact import. It handles automatic updates for matching emails and supports custom fields. Because it runs asynchronously, Claude will receive an import job ID that it can use to poll for completion.

"I am pasting a CSV of 50 new webinar attendees. Parse this data, map it to the correct fields, and initiate a Mailtrap contact import. Give me the import ID and let me know when you are ready to poll for the final status."

Manage Webhooks

Tool name: create_a_mailtrap_webhook

Webhooks are how Mailtrap notifies external systems of delivery events (bounces, clicks, spam complaints). This tool allows Claude to dynamically configure routing rules, returning the active webhook configuration and signing secret.

"We just spun up a new Slack notification service for hard bounces at https://api.ourdomain.com/webhooks/bounces. Create a new Mailtrap webhook for our primary domain that fires exclusively on 'bounce' and 'spam_complaint' event types."

To view the complete schema definitions and the full list of available Mailtrap tools - including custom field management, detailed contact exports, and category-level statistical breakdowns - visit the Mailtrap integration page in the Truto documentation.

Workflows in Action

Connecting tools is only half the battle. The true power of an MCP server is enabling the LLM to execute multi-step logic across disparate endpoints. Here are two concrete examples of Mailtrap workflows executed autonomously by Claude.

Scenario 1: Automated Domain Verification and Compliance Setup

When launching a new localized brand, marketing needs an authenticated sending domain immediately. An IT administrator can use Claude to provision the domain and fulfill all compliance prerequisites in a single prompt.

"We are spinning up 'eu-sales.example.com'. Create this domain in Mailtrap. Once created, associate our corporate address (123 Tech Lane, London, UK) with the domain to clear compliance requirements. Finally, generate the DNS setup instructions and format them as an email draft I can send to the network engineering team."

How the agent executes this:

1. Calls create_a_mailtrap_domain passing eu-sales.example.com as the domain_name. Captures the returned id and dns_records array.
2. Calls create_a_mailtrap_domain_company_info using the captured domain ID, passing the provided physical address payload to satisfy Mailtrap's compliance check.
3. Formats the dns_records into a clean markdown block, separating the TXT and CNAME records, and outputs the final email draft to the user.

sequenceDiagram
    participant User as IT Admin
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Mailtrap as Mailtrap API
    
    User->>Claude: Prompt: Create domain and setup compliance
    Claude->>Truto: call create_a_mailtrap_domain
    Truto->>Mailtrap: POST /api/v2/domains
    Mailtrap-->>Truto: Return domain ID and DNS records
    Truto-->>Claude: Tool result
    Claude->>Truto: call create_a_mailtrap_domain_company_info
    Truto->>Mailtrap: POST /api/v2/domains/{id}/company_info
    Mailtrap-->>Truto: Return 200 OK
    Truto-->>Claude: Tool result
    Claude-->>User: Present formatted DNS instructions

Scenario 2: Troubleshooting Delivery and Managing Suppressions

A support engineer is investigating a ticket where a high-value customer is not receiving their invoices. They need to check the logs, identify the failure, and unblock the address if necessary.

"Customer finance@bigcorp.com claims they aren't getting our emails. Check the email logs for their address. If they bounced, see if they are on the suppression list. If they are on the suppression list, remove them so they can receive mail again."

How the agent executes this:

1. Calls list_all_mailtrap_email_logs applying a filter for finance@bigcorp.com. Identifies that recent attempts have a rejected status.
2. Calls list_all_mailtrap_suppressions to search for the specific email address. Finds a match and extracts the suppression UUID (last_id).
3. Calls delete_a_mailtrap_suppression_by_id passing the UUID to remove the block.
4. Returns a summary to the user explaining that the user was suppressed due to a previous hard bounce, but the block has now been lifted.

Security and Access Control

Exposing your core email infrastructure to an AI model requires strict governance. If an agent hallucinates a destructive action on your domain settings, the operational impact is severe. Truto provides several architectural layers to lock down Mailtrap MCP servers:

• Granular Method Filtering: You can restrict a Mailtrap MCP server strictly to read operations. By passing config.methods: ["read"] during server creation, Truto will only expose GET and LIST endpoints (like list_all_mailtrap_stats). Write operations like delete_a_mailtrap_domain_by_id are physically stripped from the schema.
• Resource Tag Filtering: If you only want an agent to manage contacts and suppressions, you can pass config.tags: ["contacts", "suppressions"]. Tools related to webhooks, domains, or global stats will not be generated for that specific server.
• Dual-Layer Authentication (require_api_token_auth): By default, possessing the MCP URL is enough to invoke the tools. For enterprise deployments where URLs might be logged in CI/CD pipelines, you can enable require_api_token_auth: true. This forces the MCP client to also pass a valid Truto API bearer token to execute commands.
• Built-in Server Expiration (expires_at): You can generate ephemeral MCP servers for temporary workflows. By setting an expires_at timestamp, Truto will automatically destroy the token in Cloudflare KV and delete the configuration when the time elapses, terminating the agent's access immediately.
• Isolated Proxy Execution: All tool calls execute through Truto's proxy API infrastructure, meaning the agent never sees or possesses the underlying Mailtrap OAuth tokens or API keys.

Stop Hardcoding Mailtrap Schemas for AI Agents

Building an AI integration for Mailtrap is not just about making a successful HTTP request. It requires handling complex asynchronous polling, respecting rigid rate limits without timing out the model, and orchestrating multi-step compliance dependencies just to provision a domain.

Every hour your engineering team spends writing custom JSON-RPC schemas, updating descriptions, and writing exponential backoff middleware for rate limits is an hour they are not spending building your core product.

Truto eliminates this integration debt. By deriving MCP tool definitions directly from the integration's documented resources, Truto ensures your AI agents always have access to the latest Mailtrap capabilities. When you hit a rate limit, Truto provides the standardized headers your agent needs to react intelligently. When you need temporary access, Truto provides ephemeral servers.