Connect Mailtrap to ChatGPT: Manage Domains and Analyze Sending Stats

If you need to connect Mailtrap to ChatGPT to automate domain management, analyze sending stats, or orchestrate email suppression lists, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's JSON-RPC tool calls and Mailtrap's REST APIs. If your team uses Claude instead, check out our guide on connecting Mailtrap to Claude 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 email infrastructure is a high-stakes engineering challenge. You have to handle API authentication, map nested JSON schemas to MCP tool definitions, and deal with deliverability-specific data models. Every time Mailtrap updates a webhook format or introduces a new compliance endpoint, 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 ChatGPT, 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 vendor APIs is painful. If you decide to build a custom MCP server for Mailtrap, you own the entire API lifecycle.

Here are the specific integration challenges that break standard CRUD assumptions when working with Mailtrap:

Compliance Verification Chains Creating a sending domain in Mailtrap is not a single API call. Mailtrap requires strict domain authentication (SPF, DKIM, DMARC) and account compliance verification before lifting sending limits. To fully onboard a domain, an LLM must call the domain creation endpoint, extract the DNS records, and then separately submit company information via a distinct compliance endpoint. If your MCP server doesn't expose these as distinct, linked tools, the LLM will hallucinate that a domain is ready to send when it is still in a sandbox state.

Cursor-Based Pagination for Suppressions Mailtrap does not use standard offset pagination for list endpoints. When fetching suppressed email addresses (bounces, complaints, unsubscribes), the API returns up to 1000 records per request and requires a last_id cursor to fetch the next page. You must explicitly build instructions into your tool schemas telling the LLM to pass this exact cursor value back unchanged. Without this, the LLM will attempt to guess page numbers, resulting in malformed requests and incomplete data ingestion.

Stats Aggregation vs Raw Logs The Mailtrap API heavily restricts raw message log retrieval. Email logs are only retained for a short window and require specific message IDs for deep inspection. Conversely, the /stats endpoints require precise start_date and end_date parameters and accept complex optional filters (by domain, sending stream, category, or ESP). LLMs frequently conflate "show me recent emails" with "show me sending stats". Your tool descriptions must strictly differentiate between fetching aggregate metrics and querying individual delivery logs.

A Factual Note on Rate Limits Mailtrap enforces strict rate limits (e.g., 10 requests per minute for suppression endpoints). It is important to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Mailtrap API returns an HTTP 429 Too Many Requests error, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The ChatGPT client or custom agent framework is responsible for handling the retry and backoff logic. Do not assume the integration layer absorbs these rejections.

How to Generate a Mailtrap MCP Server

Instead of writing and hosting custom API wrappers, you can use Truto to dynamically generate an MCP server for your Mailtrap account. Truto reads the underlying Mailtrap API resources and documentation, then translates them into an MCP-compliant JSON-RPC endpoint.

You can create this server in two ways: via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For internal tooling and ad-hoc agent setups, the UI is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Mailtrap account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., name the server "Mailtrap Admin", select allowed methods, or set an expiration date).
5. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4e5f6....

Method 2: Via the Truto API

If you are provisioning AI agents programmatically, you can generate MCP servers via a REST call. Truto validates the integration, generates a cryptographically hashed token, stores it in Cloudflare KV, and returns the URL.

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"]
    }
  }'

The API returns a ready-to-use URL that contains the required token. This URL is completely self-contained - it holds the context of your specific Mailtrap tenant and the tools it is permitted to execute.

How to Connect the MCP Server to ChatGPT

Once you have your Truto MCP URL, connecting it to ChatGPT takes seconds. You do not need to deal with OAuth flows, refresh tokens, or API keys in the ChatGPT interface. The cryptographic token in the URL handles authentication back to Truto, which maintains the Mailtrap connection lifecycle.

Method A: Via the ChatGPT UI

1. Open ChatGPT and navigate to Settings.
2. Click on Apps, then Advanced settings.
3. Ensure Developer mode is enabled (MCP support is behind this flag for Pro, Plus, Enterprise, and Edu accounts).
4. Under MCP servers / Custom connectors, click to add a new server.
5. Provide a name (e.g., "Mailtrap Server").
6. Paste the Truto MCP URL into the Server URL field and click Save.

ChatGPT will immediately connect, perform the MCP initialization handshake, and list the available Mailtrap tools.

Method B: Via Manual Config File

If you are using Claude Desktop, Cursor, or configuring a custom agent that relies on a local configuration file, you can connect the Truto URL using the official Server-Sent Events (SSE) transport wrapper.

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

Hero Tools for Mailtrap

Truto automatically generates descriptive, snake_case tools from the Mailtrap API documentation. Here are the highest-leverage operations your AI agent will use to manage email infrastructure.

list_all_mailtrap_domains

This tool retrieves all sending domains configured in your account, exposing their verification statuses (SPF, DKIM, DMARC), tracking settings, and permissions. It provides the LLM with a complete topology of your sending infrastructure.

"Audit our Mailtrap account and list all domains that currently have failing DNS verification checks."

create_a_mailtrap_domain

Creates a new domain for email authentication. The API returns the exact DNS records required to verify the domain. The LLM can use this to generate infrastructure-as-code configurations (like Terraform) for the new domain.

"Create a new Mailtrap sending domain for 'notifications.ourstartup.com' and format the returned SPF and DKIM records into a markdown table for the DevOps team."

create_a_mailtrap_domain_company_info

Fulfills the mandatory compliance requirement for Mailtrap domains. Without this step, domains remain restricted. This tool accepts the company name, address, website, and policy URLs.

"Update the compliance company info for the domain ID you just created using our standard HQ address and our privacy policy URL."

list_all_mailtrap_suppressions

Retrieves the suppression list (bounces, spam complaints, unsubscribes) for a specific domain. The LLM automatically handles the last_id cursor to pull down lists of problematic addresses.

"Fetch the latest suppressions for our primary sending stream and identify any internal '@ourstartup.com' email addresses that accidentally got suppressed."

list_all_mailtrap_stats

Fetches aggregated sending metrics (deliveries, bounces, opens, clicks, spam complaints) over a specific time window. The LLM handles formatting the dates required by the Mailtrap API.

"Pull the overall sending stats for the last 7 days and calculate our average open rate and bounce rate across all domains."

create_a_mailtrap_webhook

Configures event routing. Useful for dynamically spinning up webhook endpoints to track specific events like hard bounces or spam complaints during a deliverability investigation.

"Create a new Mailtrap webhook that sends 'bounce' and 'spam_complaint' events to our incident response endpoint at https://api.ourstartup.com/webhooks/mailtrap."

For the complete tool inventory, including contact management, email log fetching, and detailed schema definitions, review the Mailtrap integration page.

Workflows in Action

Giving ChatGPT access to Mailtrap via MCP transforms manual infrastructure tasks into conversational workflows. Here are two concrete examples.

Scenario 1: Domain Setup and Compliance Triage

DevOps engineers frequently handle requests to provision new subdomains for marketing or transactional streams. Instead of clicking through the Mailtrap UI, the engineer can instruct the AI to handle the provisioning and compliance chain.

"Provision a new Mailtrap domain for 'marketing.example.com'. Once created, associate our company profile (Example Corp, 123 Tech Lane, SF) with it for compliance. Finally, generate the Terraform DNS records needed to verify the SPF and DKIM."

Execution Steps:

1. The agent calls create_a_mailtrap_domain with the domain payload.
2. The API returns the domain ID and the required DNS records.
3. The agent calls create_a_mailtrap_domain_company_info using the newly acquired domain ID to satisfy compliance limits.
4. The agent parses the DNS records returned in step 1 and formats them into HCL (Terraform) blocks.

The engineer receives a fully compliant domain registration and copy-paste ready Terraform code for Route53 or Cloudflare.

sequenceDiagram
    participant User as User (DevOps)
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP
    participant Mailtrap as Mailtrap API

    User->>ChatGPT: Provision marketing.example.com
    ChatGPT->>Truto: Call create_a_mailtrap_domain
    Truto->>Mailtrap: POST /api/v2/accounts/{id}/domains
    Mailtrap-->>Truto: Returns Domain ID & DNS Records
    Truto-->>ChatGPT: Tool response
    ChatGPT->>Truto: Call create_a_mailtrap_domain_company_info
    Truto->>Mailtrap: POST /api/v2/accounts/{id}/domains/{id}/company_info
    Mailtrap-->>Truto: Compliance Verified
    Truto-->>ChatGPT: Tool response
    ChatGPT-->>User: Returns formatted Terraform blocks

Scenario 2: Deliverability Auditing

When support tickets spike regarding missing emails, email administrators need to correlate sending stats with suppression lists to identify deliverability drops.

"Pull the sending stats for the last 3 days. If the bounce rate is above 2%, fetch the latest suppressions and list the top 10 email domains that are bouncing."

Execution Steps:

1. The agent calculates the ISO dates for the last 3 days and calls list_all_mailtrap_stats.
2. The agent analyzes the returned metrics, calculating (bounces / deliveries) * 100.
3. Detecting a spike, the agent calls list_all_mailtrap_suppressions.
4. The agent parses the returned email addresses, extracts the domains (e.g., gmail.com, yahoo.com), tallies them, and presents the findings.

The admin receives an immediate diagnostic report without writing scripts or manually exporting CSVs from the Mailtrap dashboard.

Security and Access Control

Exposing transactional email infrastructure to an LLM requires strict boundary controls. Truto provides multiple mechanisms to secure your Mailtrap MCP server at generation time:

• Method Filtering: Use the methods array (e.g., ["read"]) to restrict the server to GET/LIST operations. This ensures an AI agent can read sending stats and audit domains but cannot delete suppression entries or create webhooks.
• Tag Filtering: Limit the exposed tools by specifying resource tags. For example, a tags: ["analytics"] filter will only expose the stats endpoints, completely hiding domain and suppression management from the LLM.
• API Token Authentication: Set require_api_token_auth: true. This forces the ChatGPT client to provide a valid Truto API token in the headers alongside the connection URL, ensuring that leaked URLs cannot be abused by unauthorized parties.
• Ephemeral Access: Pass an ISO datetime to the expires_at field. Cloudflare KV TTLs and Durable Object alarms will automatically destroy the MCP server at that exact time, ideal for temporary debugging sessions.

Moving Beyond Point-to-Point Scripts

Writing custom scripts to interact with the Mailtrap API is tedious. Maintaining a custom MCP server to map LLM tool calls to Mailtrap endpoints is a massive waste of engineering resources.

By leveraging a managed infrastructure layer, you eliminate the boilerplate. Truto handles the dynamic tool generation, token management, and JSON-RPC protocol translation. Your engineers can focus on building advanced AI workflows - like automated deliverability monitoring and zero-touch domain provisioning - rather than parsing pagination cursors and updating YAML schemas.