Mailtrap

MCP Mailtrap 服务器

一个通过 Mailtrap 提供沙盒发送和测试工具的 MCP 服务器。

先决条件

在使用此 MCP 服务器之前，您需要：

1. 创建 Mailtrap 账户
2. 验证您的域名
3. 从 Mailtrap API 设置 获取您的 API 令牌
4. 从 Mailtrap 账户管理 获取您的账户 ID

必需的环境变量：

• MAILTRAP_API_TOKEN - 所有功能都需要
• MAILTRAP_ACCOUNT_ID - 模板、统计、邮件日志、沙盒列表/详情以及发送域需要。仅对发送工具（send-email、send-sandbox-email 和 batch-send-* 工具）为可选。

可选（也可以作为工具参数传递）：

• DEFAULT_FROM_EMAIL - 当 from 未提供给 send-email、send-sandbox-email 或 batch-send-* 工具（用于填充 base.from）时，使用的默认发件人。可通过 from 参数在每次调用时切换发件人。
• MAILTRAP_SANDBOX_ID - 当 sandbox_id 未提供时，沙盒工具的默认沙盒 ID。可通过 sandbox_id 参数在每次调用时切换沙盒。
• MAILTRAP_TEST_INBOX_ID - 当 test_inbox_id 未提供时，沙盒工具的默认测试收件箱 ID。可通过 test_inbox_id 参数在每次调用时切换收件箱。MAILTRAP_SANDBOX_ID 的旧别名，仍作为回退支持。
• MAILTRAP_ORGANIZATION_ID - 组织工具（list-sub-accounts、create-sub-account）所需。
• MAILTRAP_ORGANIZATION_API_TOKEN - 组织范围的 API 令牌。组织工具所需（与 MAILTRAP_API_TOKEN 分开）。

快速安装

Smithery CLI

Smithery 是一个适用于所有 AI 客户端的 MCP 服务器注册表安装程序和管理器。

npx @smithery/cli install mailtrap

Smithery 自动处理客户端配置并提供交互式安装过程。这是在本地开始使用 MCP 服务器的最简单方式。

设置

Claude Desktop

使用 MCPB 安装 Mailtrap 服务器。您可以在 Releases 中找到那些文件。
下载 .MCPB 文件并打开它。如果您有 Claude Desktop，它会打开并提示您进行配置。

Claude Desktop 或 Cursor

添加以下配置：

{
  "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"
      }
    }
  }
}

如果您使用 asdf 管理 Node.js，则必须使用可执行文件的绝对路径（Mac 示例）

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.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 配置文件位置

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

Windows：%APPDATA%\Claude\claude_desktop_config.json

Cursor 配置文件位置

Mac：~/.cursor/mcp.json

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

VS Code

手动更改配置

在命令面板中运行：Preferences: Open User Settings (JSON)

然后，在设置文件中添加以下配置：

{
  "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] 更改“env”部分后，别忘了重启您的 MCP 服务器。

MCP Bundle (MCPB)

为了在支持 MCP Bundle 的主机中轻松安装，您可以分发一个 .mcpb 捆绑包文件。

# 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

这将使用存储库 manifest.json 和 dist/ 中的构建产物创建 mailtrap-mcp.mcpb。

用法

配置完成后，您可以要求代理发送电子邮件和管理模板，例如：

电子邮件发送操作：

• “向 john.doe@example.com 发送一封主题为‘明天会议’的电子邮件，并附上关于我们即将举行的会议的友好提醒。”
• “向 sarah@example.com 发送关于项目更新的邮件，并抄送团队到 team@example.com”
• “将欢迎模板（uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96）发送到 new@example.com，并使用变量 { name: 'Alex' }”
• “向 test@example.com 发送主题为‘测试模板’的沙盒邮件，以预览我们的欢迎邮件的样式”

电子邮件日志（调试投递）：

• “列出我最近发送的电子邮件日志”
• “显示发送到 user@example.com 的电子邮件日志”
• “获取 ID 为 abc-123-uuid 的电子邮件日志消息，以检查投递状态”

发送统计：

• “获取 2025 年 1 月的发送统计”
• “按域名显示上个月的投递率”
• “从 2025-01-01 到 2025-01-31 按类别显示我的电子邮件统计？”

沙盒操作：

• “从我的沙盒收件箱获取所有消息”
• “显示沙盒消息的第一页”
• “在我的沙盒收件箱中搜索包含‘test’的消息”
• “显示 ID 为 5159037506 的沙盒消息的详细信息”

模板操作：

• “列出我的 Mailtrap 账户中的所有电子邮件模板”
• “创建一个名为‘欢迎邮件’的新电子邮件模板，主题为‘欢迎来到我们的平台！’”
• “更新 ID 为 12345 的模板，将主题改为‘更新的欢迎消息’”
• “删除 ID 为 67890 的模板”

发送域：

• “列出我的发送域”
• “获取 ID 为 3938 的发送域”
• “为 example.com 创建发送域”
• “删除发送域 3938”
• “获取发送域 3938 以及 DNS 设置说明”

可用工具

send-email

通过 Mailtrap 发送事务性电子邮件。支持两种互斥模式——内联内容（subject + text/html）或基于模板（template_uuid）。

参数：

• from（可选）：发件人，格式为 { email, name? }（运行时也接受裸电子邮件字符串）。如果未提供，则使用 DEFAULT_FROM_EMAIL。
• to（可选）：收件人数组，格式为 { email, name? } 对象（运行时也接受裸电子邮件字符串或单个非数组地址）。如果提供了 cc 或 bcc，则为可选；to / cc / bcc 中至少一个必须包含收件人。
• cc（可选）：抄送收件人数组，格式为 { email, name? } 对象（运行时也接受裸电子邮件字符串）。
• bcc（可选）：密送收件人数组，格式为 { email, name? } 对象（运行时也接受裸电子邮件字符串）。
• subject（条件）：电子邮件主题行。内联发送时需要；当设置了 template_uuid 时必须省略。
• text（条件）：电子邮件正文文本。内联发送时需要（与 html 一起或代替它）；当设置了 template_uuid 时必须省略。
• html（条件）：电子邮件正文的 HTML 版本。内联发送时需要（与 text 一起或代替它）；当设置了 template_uuid 时必须省略。
• category（可选）：用于跟踪和分析的电子邮件类别。当设置了 template_uuid 时必须省略。
• template_uuid（可选）：使用 Mailtrap 电子邮件模板而不是内联内容。设置后，subject / text / html / category 必须省略（根据 Mailtrap API）。
• template_variables（可选）：替换到 template_uuid 引用的模板中的变量对象。仅允许与 template_uuid 一起使用。

batch-send-transactional-email

在一次 Mailtrap API 调用中发送一批事务性电子邮件（默认发送流）。共享字段放在 base 上；每个收件人的覆盖项放在 requests[] 中。每个请求必须通过 to、cc 或 bcc 至少包含一个收件人。与 send-email 相同的内联与模板互斥规则——在合并基础字段和每个请求后进行检查。

参数：

• base（可选）：包含批处理共享字段的对象。
  • from（可选）：发件人，格式为 { email, name? }（运行时也接受裸电子邮件字符串）。回退到 DEFAULT_FROM_EMAIL。
  • reply_to（可选）：回复地址。
  • subject / text / html / category（可选，内联模式）：每个请求的默认内容。
  • template_uuid / template_variables（可选，模板模式）：默认模板和变量。与内联字段互斥。
  • custom_variables（可选）：默认自定义变量（字符串值）。
  • headers（可选）：默认自定义标头。
• requests（必需）：非空的每个收件人消息数组。每个条目包含：
  • to（可选）：收件人数组，格式为 { email, name? } 对象（运行时也接受裸电子邮件字符串或单个非数组地址）。如果提供了 cc 或 bcc，则为可选；to / cc / bcc 中至少一个必须包含收件人。
  • cc、bcc、reply_to（可选）。
  • 内联（subject/text/html/category）或模板（template_uuid/template_variables）覆盖项；任何省略的字段将回退到匹配的 base 值。
  • custom_variables、headers（可选）。

batch-send-bulk-email

通过 Mailtrap 的批量流 API 发送一批批量电子邮件。与 base 相同的 requests[] + batch-send-transactional-email 结构、验证和内联与模板规则——唯一区别是该工具通过批量端点而不是事务端点路由调用。请参阅上面的参数。

list-email-logs

列出已发送的电子邮件日志（投递历史），带有可选的分页和过滤器。用于从 IDE 调试投递问题。

参数：

• search_after（可选）：来自上一个响应 next_page_cursor 的分页游标
• sent_after（可选）：ISO 8601 日期/时间；仅显示在此时间之后发送的日志
• sent_before（可选）：ISO 8601 日期/时间；仅显示在此时间之前发送的日志
• from_email（可选）：按发件人电子邮件过滤；与 from_operator 一起使用（默认：ci_equal）
• to_email（可选）：按收件人电子邮件过滤；与 to_operator 一起使用（默认：ci_equal）
• status（可选）：按投递状态过滤：delivered、not_delivered、enqueued、opted_out；与 status_operator 一起使用（默认：equal）
• subject（可选）：按电子邮件主题过滤；与 subject_operator 一起使用（默认：ci_contain）。使用 subject_operator：empty/not_empty 按主题是否存在过滤。
• sending_domain_id（可选）：按发送域 ID（数字）过滤；与 sending_domain_id_operator 一起使用（默认：equal）
• sending_stream（可选）：按流过滤：transactional 或 bulk；与 sending_stream_operator 一起使用（默认：equal）
• events（可选）：按事件类型过滤：delivery、open、click、bounce、spam、unsubscribe、soft_bounce、reject、suspension；与 events_operator 一起使用（include_event / not_include_event）
• clicks_count / opens_count（可选）：按点击/打开次数过滤；与 *_operator 一起使用：equal、greater_than、less_than
• client_ip / sending_ip（可选）：按 IP 过滤；与 *_operator 一起使用：equal、not_equal、contain、not_contain
• email_service_provider_response（可选）：按提供商响应文本过滤；与 *_operator 一起使用（ci_contain 等）
• email_service_provider（可选）：按提供商（精确）过滤；与 *_operator 一起使用：equal、not_equal
• recipient_mx（可选）：按收件人 MX 过滤；与 recipient_mx_operator 一起使用（ci_contain 等）
• category（可选）：按电子邮件类别过滤；与 category_operator 一起使用：equal、not_equal

所有参数都是可选的。

get-email-log-message

按 ID（UUID）获取单个电子邮件日志消息：一个可读的摘要（发件人、收件人、主题、发送时间、状态、类别、流、参与度、投递上下文），然后是详细的事件历史记录。可选地，使用 include_content: true，您还可以在 Mailtrap 暴露原始消息 URL 时加载并显示消息正文（HTML 和纯文本）。

参数：

• message_id (必需)：电子邮件日志消息的 UUID（来自发送响应或 list-email-logs）。使用 list-email-logs 查找消息 ID。
• include_content (可选)：当 true 时，获取原始 EML（如果 raw_message_url 可用）并附加解析后的 HTML 和纯文本正文部分，类似于 show-sandbox-email-message。

get-sending-stats

获取指定日期范围内的电子邮件发送统计（投递率、退信率、打开率、点击率、垃圾邮件率）。可选按域名、类别、电子邮件服务提供商或日期细分。无需离开编辑器即可查看投递率。

参数：

• start_date (必需)：统计范围的起始日期（YYYY-MM-DD）
• end_date (必需)：统计范围的结束日期（YYYY-MM-DD）
• breakdown (可选)：统计的细分方式：aggregated（默认）、by_domain、by_category、by_email_service_provider 或 by_date
• sending_domain_ids (可选)：将结果限制为这些发送域名 ID（整数数组）
• sending_streams (可选)：限制为 transactional 和/或 bulk（字符串数组）
• categories (可选)：限制为这些电子邮件类别（字符串数组）
• email_service_providers (可选)：限制为这些提供商，例如 Google、Yahoo、Outlook（字符串数组）

create-template

在您的 Mailtrap 账户中创建新的电子邮件模板。

参数：

• name (必需)：模板名称
• subject (必需)：电子邮件主题行
• html（或 text 为必填）：模板的 HTML 内容
• text（或 html 为必填）：模板的纯文本版本
• category (可选)：模板类别（默认为“General”）

list-templates

列出您的 Mailtrap 账户中的所有电子邮件模板。

参数：

• 无需参数

get-template

按 ID 获取单个电子邮件模板，包括主题、类别和 HTML/文本正文。

参数：

• template_id (必需)：要获取的模板 ID

update-template

更新现有的电子邮件模板。

参数：

• template_id (必需)：要更新的模板 ID
• name (可选)：模板的新名称
• subject (可选)：新的电子邮件主题行
• html (可选)：模板的新 HTML 内容
• text (可选)：模板的新纯文本版本
• category (可选)：模板的新类别

[!NOTE]
调用 update-template 进行更新时，必须至少提供一个可更新字段（名称、主题、html、文本或类别）。

delete-template

删除现有的电子邮件模板。

参数：

• template_id (必需)：要删除的模板 ID

send-sandbox-email

向您的 Mailtrap 测试收件箱发送电子邮件，用于开发和测试目的。这非常适合在不向真实收件人发送电子邮件的情况下测试电子邮件模板。支持与 send-email 相同的两种模式 — 内联内容 或 基于模板（template_uuid）。

参数：

• test_inbox_id (可选)：Mailtrap 测试收件箱 ID。除非设置了 MAILTRAP_TEST_INBOX_ID，否则为必填；每次调用时传入以指定特定收件箱。
• from (可选)：发件人作为 { email, name? }（运行时也接受裸电子邮件字符串）。如果未提供，则使用 DEFAULT_FROM_EMAIL。
• to (可选)：收件人数组，作为 { email, name? } 对象（数组中的裸电子邮件字符串，或逗号分隔的纯电子邮件字符串，在运行时也接受）。如果提供了 cc 或 bcc，则为可选；to / cc / bcc 中至少一个必须包含收件人。
• cc (可选)：抄送收件人数组，作为 { email, name? } 对象（运行时也接受裸电子邮件字符串）。
• bcc (可选)：密送收件人数组，作为 { email, name? } 对象（运行时也接受裸电子邮件字符串）。
• subject (条件)：电子邮件主题行。内联发送时必需；当设置 template_uuid 时必须省略。
• text (条件)：电子邮件正文文本。内联发送时需要（与 html 一起或代替）；当设置 template_uuid 时必须省略。
• html (条件)：电子邮件正文的 HTML 版本。内联发送时需要（与 text 一起或代替）；当设置 template_uuid 时必须省略。
• category (可选)：用于跟踪的电子邮件类别。当设置 template_uuid 时必须省略。
• template_uuid (可选)：使用 Mailtrap 电子邮件模板而不是内联内容。设置后，subject / text / html / category 必须省略。
• template_variables (可选)：替换到 template_uuid 引用的模板中的变量对象。仅允许与 template_uuid 一起使用。

batch-send-sandbox-email

通过一次 API 调用向您的 Mailtrap 测试收件箱发送一批电子邮件，不会投递给真实收件人。与 batch-send-transactional-email 具有相同的 base + requests[] 结构、验证和内联 vs 模板规则 — 区别在于此工具通过沙箱端点将调用路由到单个测试收件箱。

参数：

• sandbox_id (可选)：Mailtrap 沙箱（测试收件箱）ID。除非设置了 MAILTRAP_SANDBOX_ID，否则为必填；每次调用时传入以指定特定沙箱。
• base (可选)、requests (必需)：参见上面的 batch-send-transactional-email。

[!NOTE]
对于沙箱工具，请在工具调用中提供 test_inbox_id，或设置 MAILTRAP_TEST_INBOX_ID 环境变量。您可以通过传递 test_inbox_id 在每次调用之间切换收件箱。接受 sandbox_id 的工具会优先使用 MAILTRAP_SANDBOX_ID。

get-sandbox-messages

从您的 Mailtrap 测试收件箱中检索消息列表。用于检查测试期间沙箱中收到的电子邮件。

参数：

• page (可选)：分页的页码（最小：1）
• last_id (可选)：使用最后一条消息 ID 进行分页。返回指定消息 ID 之后的消息（最小：1）
• search (可选)：用于筛选消息的搜索查询

[!NOTE]
所有参数均为可选。如果未提供任何参数，将返回收件箱中的第一页消息。使用 page 进行传统分页，使用 last_id 进行基于游标的分页，或使用 search 按内容筛选消息。

show-sandbox-email-message

显示您的 Mailtrap 测试收件箱中特定电子邮件消息的详细信息和内容，包括 HTML 和文本正文内容。

参数：

• message_id (必需)：要检索的沙箱电子邮件消息的 ID

[!NOTE]
首先使用 get-sandbox-messages 获取消息列表及其 ID，然后使用此工具查看特定消息的完整内容。

get-sandbox-project

按 ID 获取沙箱项目，包括其收件箱和电子邮件计数。

参数：

• project_id (必需)：要获取的项目 ID

update-sandbox-project

重命名现有的沙箱项目。

参数：

• project_id (必需)：要更新的项目 ID
• name (必需)：项目的新名称（2–100 个字符）

list-sandboxes

列出 API 令牌在所有项目中可访问的每个沙箱。

参数：

• 无需参数

mark-sandbox-as-read

将沙箱中的所有消息标记为已读。

参数：

• sandbox_id (必需)：要操作的沙箱 ID

reset-sandbox-credentials

重置沙箱的 SMTP 凭据。返回新的用户名/密码。

参数：

• sandbox_id (必需)：要操作的沙箱 ID

enable-sandbox-email-address

启用沙箱的通过电子邮件接收地址（开启通过 SMTP 将消息投递到沙箱的 Mailtrap 地址）。

参数：

• sandbox_id (必需)：要操作的沙箱 ID

reset-sandbox-email-address

为沙箱生成新的通过电子邮件接收地址。

参数：

• sandbox_id (必需)：要操作的沙箱 ID

forward-sandbox-message

将沙箱消息转发到外部电子邮件地址。计入您每月的转发配额。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：要转发的沙箱消息的 ID
• email (必需)：要将消息转发到的电子邮件地址

update-sandbox-message

将沙箱消息标记为已读或未读。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：要更新的沙箱消息的 ID
• is_read (必需)：true 标记为已读，false 标记为未读

delete-sandbox-message

删除单个沙箱消息。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：要删除的沙箱消息的 ID

get-sandbox-message-spam-score

获取沙箱消息的 SpamAssassin 垃圾邮件报告（分数、规则、完整报告）。作为 show-sandbox-email-message 上 include_spam_report: true 的独立替代方案。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

get-sandbox-message-html-analysis

获取沙箱消息的 HTML 分析报告（客户端兼容性分数、问题元素）。作为 show-sandbox-email-message 上 include_html_analysis: true 的独立替代方案。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

get-sandbox-message-headers

获取沙箱消息的解析后的邮件头。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

get-sandbox-message-html

获取沙箱消息的渲染后 HTML 正文。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

get-sandbox-message-text

获取沙箱消息的纯文本正文。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

get-sandbox-message-raw

获取沙箱消息的原始 MIME 格式消息（头 + 正文）。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

get-sandbox-message-eml

获取渲染为 EML 文件负载的消息（适合附加到工单或导入到其他邮件客户端）。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

get-sandbox-message-html-source

获取沙箱消息的未渲染 HTML 源代码（在任何 Mailtrap 端转换（如 CID 链接重写）之前的 HTML）。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

list-sandbox-attachments

列出沙箱消息上的所有附件（文件名、内容类型、大小、下载路径）。

参数：

• sandbox_id (可选)：沙箱 ID。回退到 MAILTRAP_SANDBOX_ID。
• message_id (必需)：沙箱消息的 ID

get-sandbox-attachment

获取单个附件的元数据和下载 URL。

参数：

• sandbox_id（可选）：沙盒 ID。未提供时回退到 MAILTRAP_SANDBOX_ID。
• message_id（必填）：包含附件的沙盒消息的 ID
• attachment_id（必填）：要获取的附件的 ID

list-sending-domains

列出发送域名及其 DNS 验证状态。

参数：

• 无需参数

get-sending-domain

按 ID 获取发送域名及其验证状态（包括 DNS 记录）。可选地，通过将 include_setup_instructions 设置为 true 来包含 DNS 设置说明。

参数：

• sending_domain_id（必填）：发送域名 ID
• include_setup_instructions（可选）：如果为 true，则将 DNS 设置说明附加到响应中。默认值：false

create-sending-domain

创建新的发送域名。创建后，添加 DNS 记录以验证域名（使用带 include_setup_instructions: true 的 get-sending-domain 查看记录）。

参数：

• domain_name（必填）：域名（例如 example.com）

delete-sending-domain

删除发送域名。

参数：

• sending_domain_id（必填）：要删除的发送域名 ID

send-sending-domain-setup-instructions

将通过电子邮件将发送域名的 DNS 设置说明发送到指定地址。适用于将 DNS 记录转发给 DevOps 同事。

参数：

• sending_domain_id（必填）：发送域名 ID
• email（必填）：接收 DNS 设置说明的电子邮件地址

list-suppressions

列出或搜索抑制记录（硬退回、垃圾邮件投诉、退订、手动导入）。每次调用最多返回 1000 条结果。

参数：

• email（可选）：电子邮件过滤器。仅返回与此地址匹配的抑制记录。

delete-suppression

按 ID 删除抑制记录。除非该电子邮件再次被抑制，否则 Mailtrap 将恢复向其投递。

参数：

• suppression_id（必填）：要删除的抑制记录 ID

list-webhooks

列出为账户配置的所有 Webhook。以 JSON 形式返回完整的 Webhook 记录。

参数：

• 无需参数

get-webhook

按 ID 获取单个 Webhook。以 JSON 形式返回完整的 Webhook 记录。注意：signing_secret 不会在此返回——它仅在 create-webhook 的响应中可用。

参数：

• webhook_id（必填）：要获取的 Webhook 的 ID

create-webhook

创建 Webhook。响应中包含用于验证 Webhook 负载签名的 signing_secret——此密钥仅在创建时返回，请立即保存。如果丢失，请重新创建 Webhook。

参数：

• url（必填）：Mailtrap 将向其 POST Webhook 事件的 URL
• webhook_type（必填）："email_sending"、"audit_log" 或 "inbound_receiving"
• active（可选，布尔值）：默认为 true
• payload_format（可选）："json" 或 "jsonlines"。默认为 "json"
• sending_stream（可选，仅 email_sending）："transactional" 或 "bulk"
• event_types（可选，仅 email_sending）：delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject 的数组
• domain_id（可选，仅 email_sending）：将此 Webhook 限定到指定发送域名 ID
• inbound_inbox_id（可选，仅 inbound_receiving）：Webhook 关联的入站收件箱 ID；省略则应用于账户中的所有收件箱

update-webhook

更新 Webhook 的可变字段。webhook_type、sending_stream 和 domain_id 在创建后无法更改——如果需要更改这些字段，请重新创建 Webhook。

参数：

• webhook_id（必填）：要更新的 Webhook 的 ID
• url（可选）：新的 Webhook URL
• active（可选，布尔值）：启用或禁用 Webhook
• payload_format（可选）："json" 或 "jsonlines"
• event_types（可选，仅 email_sending）：delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject 的数组
• inbound_inbox_id（可选，仅 inbound_receiving）：Webhook 关联的入站收件箱 ID

delete-webhook

按 ID 永久删除 Webhook。返回已删除的 Webhook 记录。

参数：

• webhook_id（必填）：要删除的 Webhook 的 ID

get-contact

按 ID 或电子邮件获取联系人。返回完整的联系人记录（列表成员资格、状态、自定义字段）。

参数：

• contact_identifier（必填）：联系人 ID 或电子邮件地址

create-contact

创建新联系人。

参数：

• email（必填）：电子邮件地址
• fields（可选）：按合并标签键控的自定义字段值（例如 first_name）。字符串、数字或布尔值
• list_ids（可选）：要将此联系人订阅到的联系人列表的 ID
• unsubscribed（可选，布尔值）：以 unsubscribed 状态创建联系人

update-contact

更新按 ID 或电子邮件标识的现有联系人。list_ids 替换联系人的完整成员资格集；list_ids_included/list_ids_excluded 在不影响其余部分的情况下添加/移除。

参数：

• contact_identifier（必填）：联系人 ID 或电子邮件
• email（可选）：新的电子邮件地址
• fields（可选）：按合并标签键控的自定义字段值
• list_ids（可选）：用此精确列表替换成员资格集
• list_ids_included（可选）：要添加的列表 ID（追加式）
• list_ids_excluded（可选）：要移除的列表 ID
• unsubscribed（可选，布尔值）：设置为 unsubscribed（true）或 subscribed（false）

delete-contact

按 ID 或电子邮件永久删除联系人。当 API 返回联系人记录时返回该记录；否则返回确认负载。

参数：

• contact_identifier（必填）：联系人 ID 或电子邮件

create-contact-event

针对联系人（按 ID 或电子邮件）记录联系人事件。用于触发联系人列表自动化。

参数：

• contact_identifier（必填）：联系人 ID 或电子邮件
• name（必填）：事件名称（与自动化触发器匹配）
• params（必填）：任意键/值对的对象。值可以是字符串、数字、布尔值或 null

list-contact-lists

列出账户的所有联系人列表。

参数：

• search（可选）：按名称过滤联系人列表（不区分大小写的匹配），例如 news

get-contact-list

按 ID 获取联系人列表。

参数：

• list_id（必填）：要获取的联系人列表的 ID

create-contact-list

创建新的联系人列表。

参数：

• name（必填）：新列表的名称

update-contact-list

重命名现有联系人列表。

参数：

• list_id（必填）：联系人列表的 ID
• name（必填）：列表的新名称

delete-contact-list

按 ID 永久删除联系人列表。

参数：

• list_id（必填）：要删除的联系人列表的 ID

list-contact-fields

列出账户的所有联系人字段定义。

参数：

• 无需参数

get-contact-field

按 ID 获取联系人字段定义。

参数：

• field_id（必填）：联系人字段的 ID

create-contact-field

创建新的联系人字段定义。merge_tag 在账户内必须唯一，并用作模板变量中的占位符名称。

参数：

• name（必填）：显示名称（例如"名字"）
• merge_tag（必填）：唯一的占位符名称（例如 first_name）
• data_type（必填）：text、number、boolean、date 之一

update-contact-field

更新联系人字段定义。name、merge_tag 和 data_type 的任意组合均可更改。

参数：

• field_id（必填）：联系人字段的 ID
• name（可选）：新的显示名称
• merge_tag（可选）：新的合并标签（必须保持唯一）
• data_type（可选）：text、number、boolean、date 之一

delete-contact-field

按 ID 永久删除联系人字段定义。

参数：

• field_id（必填）：要删除的联系人字段的 ID

create-contact-import

批量导入联系人。返回导入任务记录；使用 get-contact-import 轮询其状态。

参数：

• contacts（必填）：联系人条目数组。每个条目需要：
  • email（必填）：联系人电子邮件地址
  • fields（可选）：按合并标签键控的自定义字段值（字符串或数字值）
  • list_ids_included（可选）：要将联系人添加到的列表 ID
  • list_ids_excluded（可选）：要将联系人从中移除的列表 ID

get-contact-import

获取联系人导入任务的状态（created/started/finished/failed），以及已创建/已更新/超出限制的计数。

参数：

• import_id（必填）：联系人导入任务的 ID

create-contact-export

导出匹配一组 AND 组合筛选条件的联系人。返回导出任务记录；当 status 为 finished 时，使用 get-contact-export 轮询状态以获取下载 URL。

参数：

• filters（必填）：筛选条件对象数组。每个对象包含：
  • name（必填）：要筛选的字段（list_id、subscription_status、email 等）
  • operator（必填）：equal、not_equal、contains、not_contains、is_empty、is_not_empty 之一
  • value（必填）：比较值（字符串、数字、布尔值或数组）

get-contact-export

获取联系人导出任务的状态。当 status 为 finished 时，url 字段包含 CSV 下载链接。

参数：

• export_id（必填）：联系人导出任务的 ID

list-accounts

列出当前 API 令牌可以访问的 Mailtrap 账户，以及每个账户的访问级别。

参数：

• 无需参数

get-billing-usage

获取账户当前计费周期的使用情况：发送和测试计划、限额以及当前计数。

参数：

• 无需参数

list-account-accesses

列出账户的账户访问（用户、邀请、API 令牌）。可选筛选条件可将结果缩小到特定资源。需要账户管理员/所有者权限。

参数：

• domain_uuids（可选）：按发送域名 UUID 筛选（字符串数组）
• inbox_ids（可选）：按沙盒收件箱 ID 筛选（字符串数组）
• project_ids（可选）：按沙盒项目 ID 筛选（字符串数组）

remove-account-access

按 ID 移除账户访问。对于 User 说明符，将撤销其权限；对于 Invite 或 ApiToken 说明符，将完全移除该说明符。需要管理员/所有者权限。

参数：

• account_access_id（必填）：要移除的访问记录的 ID

get-permission-resources

获取 API 令牌具有管理员访问权限的所有资源（收件箱、项目、域名、计费、账户），按层级嵌套排列。

参数：

• 无需参数

bulk-update-permissions

为单个账户访问批量创建、更新或销毁权限。现有的 (resource_type, resource_id) 对会被更新；新的会被创建。在条目上设置 destroy: true 可将其移除。

参数：

• account_access_id（必填）：目标账户访问 ID
• permissions（必填）：权限条目数组。每个条目包含：
  • resource_id（必填）：资源 ID（数字或字符串）
  • resource_type（必填）：account、project、inbox、domain、billing 之一
  • access_level（可选）：admin/100 或 viewer/10
  • destroy（可选，布尔值）：为 true 时，删除此权限而不是创建/更新它

list-api-tokens

列出账户的所有 API 令牌。

参数：

• 无需参数

create-api-token

创建新的 API 令牌。响应中包含机密 token 值——这是唯一一次返回完整令牌，请立即保存。如果丢失，请重新创建令牌。

参数：

• name（必填）：令牌的显示名称
• resources（可选）：用于限定令牌范围的资源权限数组。每个条目包含：
  • resource_type（必填）：account、project、inbox、domain、billing 之一
  • resource_id（必填）：资源的 ID
  • access_level（必填）：100（管理员）或 10（查看者）

get-api-token

按 ID 获取 API 令牌。仅返回元数据——此处不返回机密令牌值（仅从 create-api-token / reset-api-token 返回）。

参数：

• api_token_id（必填）：API 令牌的 ID

reset-api-token

按 ID 重置（轮换）API 令牌。响应中包含新的机密 token 值——仅在此调用中返回，请立即保存。之前的令牌将失效。

参数：

• api_token_id（必填）：要重置的 API 令牌 ID

delete-api-token

按 ID 永久删除 API 令牌。删除后该令牌将无法再进行身份验证。

参数：

• api_token_id（必填）：要删除的 API 令牌 ID

list-sub-accounts

列出组织中的子账户。需要 MAILTRAP_ORGANIZATION_ID 环境变量和子账户管理权限。

参数：

• 无需参数

create-sub-account

在组织下创建新的子账户。需要 MAILTRAP_ORGANIZATION_ID 环境变量和子账户管理权限。

参数：

• name（必填）：新子账户的显示名称

list-inbound-folders

列出账户中的所有入站文件夹。返回格式化摘要。

参数：

• 无需参数

get-inbound-folder

按 ID 获取单个入站文件夹。以 JSON 形式返回完整文件夹记录。

参数：

• folder_id（必填）：入站文件夹的 ID

create-inbound-folder

创建新的入站文件夹。

参数：

• name（必填）：文件夹名称

update-inbound-folder

重命名入站文件夹。

参数：

• folder_id（必填）：入站文件夹的 ID
• name（必填）：新的文件夹名称

delete-inbound-folder

永久删除入站文件夹及其所有收件箱。

参数：

• folder_id（必填）：入站文件夹的 ID

list-inbound-inboxes

列出入站文件夹中的所有收件箱。返回格式化摘要。

参数：

• folder_id（必填）：入站文件夹的 ID

get-inbound-inbox

按 ID 获取单个入站收件箱。以 JSON 形式返回完整收件箱记录。

参数：

• folder_id（必填）：入站文件夹的 ID
• inbox_id（必填）：收件箱的 ID

create-inbound-inbox

在文件夹中创建新的入站收件箱。

参数：

• folder_id（必填）：入站文件夹的 ID
• name（必填）：收件箱名称
• domain_id（可选）：关联到自定义发送域名（catch-all 收件箱）。省略则使用 Mailtrap 托管的收件箱

update-inbound-inbox

重命名入站收件箱。

参数：

• folder_id（必填）：入站文件夹的 ID
• inbox_id（必填）：收件箱的 ID
• name（必填）：新的收件箱名称

delete-inbound-inbox

永久删除入站收件箱。

参数：

• folder_id（必填）：入站文件夹的 ID
• inbox_id（必填）：收件箱的 ID

list-inbound-messages

列出入站收件箱中收到的消息（游标分页）。当存在更多结果时，返回带下一页提示的格式化摘要。

参数：

• inbox_id（必填）：收件箱的 ID
• last_id（可选）：来自先前响应中 last_id 的分页游标

get-inbound-message

获取单个入站消息，包含完整正文和附件下载 URL。以 JSON 形式返回完整消息记录。

参数：

• inbox_id（必填）：收件箱的 ID
• message_id（必填）：消息的 ID

delete-inbound-message

永久删除入站消息。

参数：

• inbox_id（必填）：收件箱的 ID
• message_id（必填）：消息的 ID

reply-to-inbound-message

回复入站消息（发送给原始发件人）。发送真实邮件。地址接受裸电子邮件字符串或 { email, name? }。

参数：

• inbox_id（必填）：收件箱的 ID
• message_id（必填）：要回复的消息 ID
• text / html（至少推荐一个）：回复正文
• from（可选）：发件人。Mailtrap 托管的收件箱会拒绝；自定义域名收件箱为必填
• cc / bcc / reply_to（可选）：其他地址
• category（可选）：消息类别
• attachments（可选）：{ content (base64), filename, type?, disposition?, content_id? } 数组
• headers / custom_variables（可选）：字符串值对象

reply-all-to-inbound-message

回复入站消息并抄送原始消息的其他收件人。发送真实邮件。参数与 reply-to-inbound-message 相同。

参数：

• inbox_id（必填）：收件箱的 ID
• message_id（必填）：要回复的消息 ID
• 另加与 reply-to-inbound-message 相同的可选发送字段

forward-inbound-message

将入站消息转发给新收件人。发送真实邮件。

参数：

• inbox_id（必填）：收件箱的 ID
• message_id（必填）：要转发的消息 ID
• to（必填）：至少一个收件人（裸电子邮件字符串或 { email, name? }，或数组）
• 另加与 reply-to-inbound-message 相同的可选发送字段

list-inbound-threads

列出入站收件箱中的会话线程（游标分页）。当存在更多结果时，返回带下一页提示的格式化摘要。

参数：

• inbox_id（必填）：收件箱的 ID
• last_id（可选）：来自先前响应中 last_id 的分页游标

get-inbound-thread

获取单个入站线程，内嵌其消息（按时间从旧到新排列）。以 JSON 形式返回完整线程记录。

参数：

• inbox_id（必填）：收件箱的 ID
• thread_id（必填）：线程的 ID

delete-inbound-thread

永久删除入站线程。

参数：

• inbox_id（必填）：收件箱的 ID
• thread_id（必填）：线程的 ID

开发

1. 克隆仓库：

git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp

2. 安装依赖：

npm install

使用 Claude Desktop 或 Cursor 进行配置

[!TIP] 参见 Setup 部分中配置文件的位置。

添加以下配置：

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "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"
      }
    }
  }
}

如果你使用 asdf 管理 Node.js，应使用可执行文件的绝对路径：

（Mac 示例）

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.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"
      }
    }
  }
}

VS Code

[!TIP] 参见 Setup 部分中配置文件的位置。

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "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"
        }
      }
    }
  }
}

测试

针对真实 Mailtrap 运行工具

有两种方式可以针对真实 Mailtrap 账户端到端地运行工具：使用 MCP Inspector 浏览器界面进行交互式探索，或使用其 CLI 模式从 shell 进行一次性调用。

两者都需要先构建 bundle：

npm run build

并在你的 shell 中导出 MAILTRAP_API_TOKEN 和 MAILTRAP_ACCOUNT_ID（mcp:cli 脚本会将两者转发给已启动的服务器）。

浏览器界面

npm run dev

Inspector 会打印一个类似 http://localhost:6274 的 URL。打开它，切换到 Tools 选项卡，选择一个工具（例如 get-template），以 JSON 形式填写参数，然后点击 Run。Mailtrap 的响应会显示在下方面板中。

CLI

如需无需界面的单次调用，请使用 npm run mcp:cli。在 -- 之后传递 Inspector 的 CLI 标志，以便 npm 原样转发：

# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg email=devops@example.com

运行 MCPB 服务器

# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] 如需使用 MCP Inspector 进行开发：

npm run dev:mcpb

错误处理

此服务器使用与 MCP 约定一致的结构化错误处理：

• VALIDATION_ERROR：输入验证失败
• CONFIGURATION_ERROR：配置缺失或无效
• EXECUTION_ERROR：运行时执行错误
• TIMEOUT：操作超时（默认 30 秒）

错误包含可操作的提示信息，并以结构化形式记录日志。

安全

• 通过 Zod schemas 验证输入
• 环境变量得到安全处理
• 操作超时保护（30 秒）
• 错误输出中会清理敏感信息

日志

结构化 JSON 日志，级别包括：INFO、WARN、ERROR、DEBUG。

通过设置 DEBUG=true 启用调试日志。

# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js

重要提示：服务器将日志写入 stderr，因此 stdout 保留给 JSON-RPC 帧。这可以防止主机因日志交错而遇到 JSON 解析错误。

使用 jq 进行日志分析示例：

# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'

# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'

故障排查

常见问题：

1. 缺少 API 令牌：确保已设置 MAILTRAP_API_TOKEN
2. Sandbox 不工作：在工具调用中提供 test_inbox_id 或设置 MAILTRAP_TEST_INBOX_ID 环境变量
3. 超时错误：检查网络连接和 Mailtrap API 状态
4. 验证错误：确保提供了所有必填字段

贡献

欢迎在 GitHub 上提交 bug 报告和 pull request。本项目旨在成为一个安全、友好的协作空间，贡献者应遵守行为准则。

许可证

该包以 MIT License 条款作为开源软件提供。

行为准则

所有在 Mailtrap 项目的代码库、问题跟踪器、聊天室和邮件列表中互动的人员都应遵守行为准则。