Mailtrap Mcp

[](https://github.com/mailtrap/mailtrap-mcp/actions/workflows/main.yml) [](https://www.npmjs.com/package/mcp-mailtrap)

MCP Mailtrap Server

An MCP server that provides tools for sending and testing in sandbox via Mailtrap.

Prerequisites

Before using this MCP server, you need to:

1. Create a Mailtrap account
2. Verify your domain
3. Get your API token from Mailtrap API settings
4. Get your Account ID from Mailtrap account management

Required Environment Variables:

• MAILTRAP_API_TOKEN - Required for all functionality
• MAILTRAP_ACCOUNT_ID - Required for templates, stats, email logs, sandbox list/show, and sending domains. Optional only for send-email and send-sandbox-email.

Optional (can be passed as tool parameters instead):

• DEFAULT_FROM_EMAIL - Default sender email when from is not provided to send-email or send-sandbox-email. Enables switching sender per call via the from parameter.
• MAILTRAP_TEST_INBOX_ID - Default test inbox ID for sandbox tools when test_inbox_id is not provided. Enables switching between inboxes per call via the test_inbox_id parameter.
• MAILTRAP_SANDBOX_ID - Default sandbox ID for sandbox tools when sandbox_id is not provided. Enables switching between sandboxes per call via the sandbox_id parameter.
• MAILTRAP_ORGANIZATION_ID - Required for organization tools (list-sub-accounts, create-sub-account).
• MAILTRAP_ORGANIZATION_API_TOKEN - Organization-scoped API token. Required for organization tools (separate from MAILTRAP_API_TOKEN).

Quick Install

[](https://cursor.com/en-US/install-mcp?name=mailtrap&config=eyJlbnYiOnsiTUFJTFRSQVBfQVBJX1RPS0VOIjoieW91cl9tYWlsdHJhcF9hcGlfdG9rZW4iLCJERUZBVUxUX0ZST01fRU1BSUwiOiJ5b3VyX3NlbmRlckBleGFtcGxlLmNvbSIsIk1BSUxUUkFQX0FDQ09VTlRfSUQiOiJ5b3VyX2FjY291bnRfaWQiLCJNQUlMVFJBUF9URVNUX0lOQk9YX0lEIjoieW91cl90ZXN0X2luYm94X2lkIn0sImNvbW1hbmQiOiJucHggLXkgbWNwLW1haWx0cmFwIn0%3D)

[](https://insiders.vscode.dev/redirect/mcp/install?name=mailtrap&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-mailtrap%22%5D%2C%22env%22%3A%7B%22MAILTRAPAPITOKEN%22%3A%22%24%7Binput%3AmailtrapApiToken%7D%22%2C%22DEFAULTFROMEMAIL%22%3A%22%24%7Binput%3AsenderEmail%7D%22%2C%22MAILTRAPACCOUNTID%22%3A%22%24%7Binput%3AmailtrapAccountId%7D%22%2C%22MAILTRAPTESTINBOX_ID%22%3A%22%24%7Binput%3AmailtrapTestInboxId%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapApiToken%22%2C%22description%22%3A%22Mailtrap+API+Token%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22senderEmail%22%2C%22description%22%3A%22Sender+Email+Address%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapAccountId%22%2C%22description%22%3A%22Mailtrap+Account+ID%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapTestInboxId%22%2C%22description%22%3A%22Mailtrap+Test+Inbox+ID+%28optional%29%22%7D%5D)

Smithery CLI

Smithery is a registry installer and manager for MCP servers that works with all AI clients.

npx @smithery/cli install mailtrap

> Smithery automatically handles client configuration and provides an interactive setup process. It's the easiest way to get started with MCP servers locally.

Setup

Claude Desktop

Use MCPB to install the Mailtrap server. You can find those files in Releases. Download .MCPB file and open it. If you have Claude Desktop - it will open it and suggest to configure.

Claude Desktop or Cursor

Add the following configuration:

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

If you are using asdf for managing Node.js you must use absolute path to executable (example for Mac)

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users//.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users//.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users//.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

Claude Desktop config file location

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor config file location

Mac: ~/.cursor/mcp.json

Windows: %USERPROFILE%\.cursor\mcp.json

VS Code

Manually changing config

Run in Command Palette: Preferences: Open User Settings (JSON)

Then, in the settings file, add the following configuration:

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

> [!TIP] > Don't forget to restart your MCP server after changing the "env" section.

MCP Bundle (MCPB)

For easy installation in hosts that support MCP Bundles, you can distribute an .mcpb bundle file.

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

This creates mailtrap-mcp.mcpb using the repository manifest.json and built artifacts in dist/.

Usage

Once configured, you can ask agent to send emails and manage templates, for example:

Email Sending Operations:

• "Send an email to john.doe@example.com with the subject 'Meeting Tomorrow' and a friendly reminder about our upcoming meeting."
• "Email sarah@example.com about the project update, and CC the team at team@example.com"
• "Send the welcome template (uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96) to new@example.com with variables { name: 'Alex' }"
• "Send a sandbox email to test@example.com with subject 'Test Template' to preview how our welcome email looks"

Email Logs (debug delivery):

• "List my recent sent email logs"
• "Show email logs for emails sent to user@example.com"
• "Get the email log message for ID abc-123-uuid to check delivery status"

Sending Statistics:

• "Get sending stats for January 2025"
• "Show delivery rates broken down by domain for last month"
• "What are my email stats by category from 2025-01-01 to 2025-01-31?"

Sandbox Operations:

• "Get all messages from my sandbox inbox"
• "Show me the first page of sandbox messages"
• "Search for messages containing 'test' in my sandbox inbox"
• "Show me the details of sandbox message with ID 5159037506"

Template Operations:

• "List all email templates in my Mailtrap account"
• "Create a new email template called 'Welcome Email' with subject 'Welcome to our platform!'"
• "Update the template with ID 12345 to change the subject to 'Updated Welcome Message'"
• "Delete the template with ID 67890"

Sending Domains:

• "List my sending domains"
• "Get sending domain with ID 3938"
• "Create a sending domain for example.com"
• "Delete sending domain 3938"
• "Get sending domain 3938 with DNS setup instructions"

Available Tools

send-email

Sends a transactional email through Mailtrap. Supports two mutually exclusive modes — inline content (subject + text/html) or template-based (template_uuid).

Parameters:

• from (optional): Sender as an email string or { email, name? }. If not provided, DEFAULT_FROM_EMAIL is used.
• to (optional): Recipient(s) — a single email/{ email, name? } or an array. Optional if cc or bcc is provided; at least one of to / cc / bcc must contain a recipient.
• cc (optional): Array of CC recipients (email strings or { email, name? } each).
• bcc (optional): Array of BCC recipients (email strings or { email, name? } each).
• subject (conditional): Email subject line. Required for inline sends; must be omitted when template_uuid is set.
• text (conditional): Email body text. Required (alongside or instead of html) for inline sends; must be omitted when template_uuid is set.
• html (conditional): HTML version of the email body. Required (alongside or instead of text) for inline sends; must be omitted when template_uuid is set.
• category (optional): Email category for tracking and analytics. Must be omitted when template_uuid is set.
• template_uuid (optional): Use a Mailtrap email template instead of inline content. When set, subject / text / html / category must be omitted (per Mailtrap API).
• template_variables (optional): Object of variables substituted into the template referenced by template_uuid. Only allowed together with template_uuid.

batch-send-transactional-email

Sends a batch of transactional emails in one Mailtrap API call (default sending stream). Shared fields go on base; per-recipient overrides go in requests[]. Each request must include at least one recipient via to, cc, or bcc. Same inline-vs-template mutual exclusion as send-email — checked after merging base with each request.

Parameters:

• base (optional): Object with fields shared across the batch.
• from (optional): Sender as an email string or { email, name? }. Falls back to DEFAULT_FROM_EMAIL.
• reply_to (optional): Reply-to address.
• subject / text / html / category (optional, inline mode): Default content for every request.
• template_uuid / template_variables (optional, template mode): Default template + variables. Mutually exclusive with the inline fields.
• custom_variables (optional): Default custom variables (string-valued).
• headers (optional): Default custom headers.
• requests (required): Non-empty array of per-recipient messages. Each entry has:
• to (optional): Recipient(s) — string, { email, name? }, or an array. Optional if cc or bcc is provided; at least one of to / cc / bcc must contain a recipient.
• cc, bcc, reply_to (optional).
• Inline (subject/text/html/category) or template (template_uuid/template_variables) overrides; any field omitted falls back to the matching base value.
• custom_variables, headers (optional).

batch-send-bulk-email

Sends a batch of bulk emails through Mailtrap's bulk-stream API. Same base + requests[] shape, validation, and inline-vs-template rules as batch-send-transactional-email — the only difference is that this tool routes the call through the bulk endpoint instead of the transactional one. See the parameters above.

list-email-logs

Lists sent email logs (delivery history) with optional pagination and filters. Use to debug delivery issues from the IDE.

Parameters:

• search_after (optional): Pagination cursor from the previous response's next_page_cursor
• sent_after (optional): ISO 8601 date/time; only logs sent after this time
• sent_before (optional): ISO 8601 date/time; only logs sent before this time
• from_email (optional): Filter by sender email; use with from_operator (default: ci_equal)
• to_email (optional): Filter by recipient email; use with to_operator (default: ci_equal)
• status (optional): Filter by delivery status: delivered, notdelivered, enqueued, optedout; use with status_operator (default: equal)
• subject (optional): Filter by email subject; use with subject_operator (default: cicontain). Use subject_operator: empty/notempty to filter by presence of subject.
• sending_domain_id (optional): Filter by sending domain ID (number); use with sending_domain_id_operator (default: equal)
• sending_stream (optional): Filter by stream: transactional or bulk; use with sending_stream_operator (default: equal)
• events (optional): Filter by event type(s): delivery, open, click, bounce, spam, unsubscribe, softbounce, reject, suspension; use with events_operator (includeevent / notincludeevent)
• clicks_count / opens_count (optional): Filter by click/open count; use with *_operator: equal, greaterthan, lessthan
• client_ip / sending_ip (optional): Filter by IP; use with *_operator: equal, notequal, contain, notcontain
• email_service_provider_response (optional): Filter by provider response text; use with *_operator (ci_contain, etc.)
• email_service_provider (optional): Filter by provider (exact); use with *_operator: equal, not_equal
• recipient_mx (optional): Filter by recipient MX; use with recipient_mx_operator (ci_contain, etc.)
• category (optional): Filter by email category; use with category_operator: equal, not_equal

All parameters are optional.

get-email-log-message

Gets a single email log message by ID (UUID): a readable summary (from, to, subject, sent time, status, category, stream, engagement, delivery context), then detailed event history. Optionally, with include_content: true, you can also load and show the message body (HTML and plain text) when Mailtrap exposes a raw message URL.

Parameters:

• message_id (required): UUID of the email log message (from send response or list-email-logs). Use list-email-logs to find message IDs.
• include_content (optional): When true, fetches the raw EML (if raw_message_url is available) and appends parsed HTML and plain-text body sections, similar to show-sandbox-email-message.

get-sending-stats

Get email sending statistics (delivery, bounce, open, click, spam rates) for a date range. Optionally break down by domain, category, email service provider, or date. Check delivery rates without leaving the editor.

Parameters:

• start_date (required): Start date for the stats range (YYYY-MM-DD)
• end_date (required): End date for the stats range (YYYY-MM-DD)
• breakdown (optional): How to break down the stats: aggregated (default), by_domain, by_category, by_email_service_provider, or by_date
• sending_domain_ids (optional): Limit results to these sending domain IDs (array of integers)
• sending_streams (optional): Limit to transactional and/or bulk (array of strings)
• categories (optional): Limit to these email categories (array of strings)
• email_service_providers (optional): Limit to these providers, e.g. Google, Yahoo, Outlook (array of strings)

create-template

Creates a new email template in your Mailtrap account.

Parameters:

• name (required): Name of the template
• subject (required): Email subject line
• html (or text is required): HTML content of the template
• text (or html is required): Plain text version of the template
• category (optional): Template category (defaults to "General")

list-templates

Lists all email templates in your Mailtrap account.

Parameters:

• No parameters required

get-template

Get a single email template by ID, including subject, category, and HTML/text body.

Parameters:

• template_id (required): ID of the template to fetch

update-template

Updates an existing email template.

Parameters:

• template_id (required): ID of the template to update
• name (optional): New name for the template
• subject (optional): New email subject line
• html (optional): New HTML content of the template

-

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mailtrap
• Source: mailtrap/mailtrap-mcp
• License: MIT
• Homepage: https://mailtrap.io

Install and usage instructions live in the source repository linked above.