Mailtrap

Mailtrap 官方 MCP 服务

Mailtrap 官方 MCP 服务，是 Mailtrap 电子邮件投递平台的配套服务。它可将你的 Mailtrap 账户连接到 Claude、Cursor、VS Code 及其他兼容 MCP 的 AI 助手。

只需使用自然语言提示词，即可发送事务性和群发邮件，在 Email Sandbox 中安全测试邮件，管理模板、联系人、发件域和 Webhook，查看邮件日志和投递统计信息，排查投递问题，并管理账户资源。

功能

• 邮件 API 和 SMTP — 发送事务性和群发邮件，包括批量邮件和基于模板的邮件。
• 邮件测试 — 在 Email Sandbox 中测试邮件，并查看内容、标头、附件、垃圾邮件评分以及与 HTML 客户端的兼容性。
• 投递监控 — 搜索邮件日志、查看事件历史记录，并分析投递、退信、打开、点击和垃圾邮件率。
• 邮件基础设施 — 管理发件域、DNS 验证、Webhook 和抑制列表。
• 联系人 — 管理联系人、列表、自定义字段和事件，并支持导入和导出。
• 账户管理 — 查看账单用量，并管理访问权限、权限设置、API 令牌和子账户。

支持的 MCP 客户端

适用于 Claude Desktop、Claude Code、Cursor、VS Code 和其他所有兼容 MCP 的客户端。下方提供各客户端的设置说明。

前提条件

使用此 MCP 服务前，你需要：

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

必需的环境变量：

• MAILTRAP_API_TOKEN - 所有功能均需设置
• MAILTRAP_ACCOUNT_ID - 模板、统计信息、邮件日志、Sandbox 列表/详情、发件域和抑制列表功能均需设置。仅发送工具（send-email、send-sandbox-email 和 batch-send-* 工具）、邮件营销活动工具、公司信息工具和跟踪退订工具不需要设置。

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

• DEFAULT_FROM_EMAIL - 调用 send-email、send-sandbox-email 或 batch-send-* 工具时，如果未提供 from，则使用此默认发件人邮箱（在此处填充 base.from）。可通过每次调用时传入 from 参数来切换发件人。
• MAILTRAP_SANDBOX_ID - 未提供工具的 sandbox_id 时使用的默认 Sandbox（测试收件箱）ID（发送/列出/查看 Sandbox 邮件工具仍接受旧版 test_inbox_id）。可通过每次调用的参数切换收件箱。
• MAILTRAP_TEST_INBOX_ID - MAILTRAP_SANDBOX_ID 的旧版别名；仍会作为回退值读取，以兼容现有配置。
• MAILTRAP_ORGANIZATION_ID - 组织工具（list-sub-accounts、create-sub-account）必需。
• MAILTRAP_ORGANIZATION_API_TOKEN - 组织级 API 令牌。组织工具必需（需与 MAILTRAP_API_TOKEN 分开设置）。

快速安装

Docker

使用 Docker MCP Catalog 镜像，通过 stdio 运行服务：

docker run --rm -i \
  -e MAILTRAP_API_TOKEN="${MAILTRAP_API_TOKEN}" \
  -e MAILTRAP_ACCOUNT_ID="${MAILTRAP_ACCOUNT_ID}" \
  -e DEFAULT_FROM_EMAIL="${DEFAULT_FROM_EMAIL}" \
  -e MAILTRAP_SANDBOX_ID="${MAILTRAP_SANDBOX_ID}" \
  -e MAILTRAP_ORGANIZATION_ID="${MAILTRAP_ORGANIZATION_ID}" \
  -e MAILTRAP_ORGANIZATION_API_TOKEN="${MAILTRAP_ORGANIZATION_API_TOKEN}" \
  mcp/mailtrap

所需和可选环境变量请参阅前置条件。

要从此仓库构建：docker build -t mcp/mailtrap .

Smithery CLI

Smithery 是 MCP 服务的注册表和安装程序，可与 AI 客户端配合使用。

将已发布的服务（mailtrap/mailtrap-mcp）安装到本地客户端（根据需要替换客户端名称）：

npx -y smithery mcp add mailtrap/mailtrap-mcp --client claude

其他客户端（cursor、windsurf 等）以及如何发布更新，请参阅 Smithery CLI 文档。

设置

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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_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": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

提示

更改“env”部分后，别忘了重启 MCP 服务。

MCP Bundle (MCPB)

如需在支持 MCP Bundles 的宿主中轻松安装，可以分发 .mcpb Bundle 文件。

# 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。

用法

配置完成后，你可以让 Agent 发送邮件和管理模板，例如：

邮件发送操作：

• “发送邮件给 [email protected]，主题为 ‘Meeting Tomorrow’，并友好地提醒对方我们即将举行的会议。”
• “给 [email protected] 发送有关项目更新的邮件，并抄送 [email protected]”
• “将欢迎模板（uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96）发送给 [email protected]，并使用变量 { name: 'Alex' }”
• “向 [email protected] 发送一封沙盒邮件，主题为 ‘Test Template’，以预览欢迎邮件的效果”

邮件日志（调试投递）：

• “列出我最近发送的邮件日志”
• “显示发送给 [email protected] 的邮件日志”
• “获取 ID 为 abc-123-uuid 的邮件日志消息，以检查投递状态”

发送统计：

• “获取 2025 年 1 月的发送统计”
• “显示上个月按域名细分的投递率”
• “2025-01-01 至 2025-01-31 期间，我的邮件统计按类别如何划分？”

沙盒操作：

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

模板操作：

• “列出我的 Mailtrap 账户中的所有邮件模板”
• “创建一个名为 ‘Welcome Email’、主题为 ‘Welcome to our platform!’ 的邮件模板”
• “更新 ID 为 12345 的模板，将主题改为 ‘Updated Welcome Message’”
• “删除 ID 为 67890 的模板”

发送域名：

• “列出我的发送域名”
• “获取 ID 为 3938 的发送域名”
• “为 example.com 创建发送域名”
• “为发送域名 3938 启用点击跟踪”
• “删除发送域名 3938”
• “获取发送域名 3938 的 DNS 设置说明”
• “显示发送域名 3938 的公司信息”
• “将域名 3938 的公司信息设为 Acme Inc，123 Main St，San Francisco，US，94105，https://acme.com”
• “将域名 3938 的公司信息中的城市改为 New York”

抑制列表：

• “列出 [email protected] 的抑制记录”
• “在域名 3938 的事务邮件流中抑制 [email protected]”
• “显示所有被抑制的邮箱地址”
• “为什么 [email protected] 收不到我的邮件？”
• “将 [email protected] 从抑制列表中移除”

跟踪退出：

• “停止跟踪 [email protected] 在域名 3938 上的打开和点击行为”
• “列出所有选择退出跟踪的用户”

联系人和列表：

• “将 [email protected] 添加到我的新闻邮件联系人列表”
• “显示我的所有联系人列表”
• “创建名为 ‘signup_source’ 的联系人字段，用于跟踪联系人的来源”
• “更新联系人 [email protected]，将其套餐设为 ‘pro’”
• “将此 CSV 中的联系人导入我的入门引导列表”
• “导出我的新闻邮件列表中的所有联系人”
• “为联系人 [email protected] 记录 ‘trial_started’ 事件”

Webhook：

• “列出我账户中配置的所有 Webhook”
• “创建指向 https://example.com/hooks/mailtrap 的 Webhook，用于接收退信和垃圾邮件事件”
• “更新 Webhook 4821，使其也发送投递事件”
• “删除 Webhook 4821”

账户和账单：

• “我本月当前的账单用量是多少？”
• “我的套餐还剩多少封邮件？”
• “列出所有有权访问此 Mailtrap 账户的用户”
• “显示我账户中可用的权限资源”

API 令牌：

• “列出我账户中的所有 API 令牌”
• “为预发布环境创建新的 API 令牌”
• “重置 ID 为 1234 的 API 令牌”
• “删除未使用的 API 令牌 1234”

组织和子账户：

• “列出我组织中的所有子账户”
• “为客户端项目 ‘Acme Corp’ 创建新的子账户”

可用工具

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 与每个请求后进行检查。

参数：

• 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 账户中的邮件模板。如果还有更多模板，结果会给出下一页的 token。各页是按最新优先列表中的偏移量划分的，因此删除模板后，应从 token 1 重新列出，而不是继续使用下一个令牌；如果某页为空，结果会给出仍包含模板的最后一页。

参数：

• token（可选）：要获取的页码（页码令牌分页）。默认为 1
• per_page（可选）：每页的模板数量。默认为 50，最大值为 100。每一页都传入相同的值

get-template

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

参数：

• template_id（必填）：要获取的模板 ID

update-template

更新现有邮件模板。

参数：

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

说明

调用 update-template 执行更新时，必须至少提供一个可更新字段（name、subject、html、text 或 category）。

delete-template

删除现有邮件模板。

参数：

• template_id（必填）：要删除的模板 ID

send-sandbox-email

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

参数：

• sandbox_id（可选）：首选。Mailtrap 沙盒（测试收件箱）ID。除非已设置 MAILTRAP_SANDBOX_ID，否则此项为必填。
• test_inbox_id（可选）：当省略 sandbox_id 时，作为 sandbox_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 测试收件箱批量发送邮件，不会投递给真实收件人。其 base + requests[] 结构、验证方式以及内联内容与模板规则均与 batch-send-transactional-email 相同，区别在于此工具通过沙盒端点将调用路由到单个测试收件箱。

参数：

• sandbox_id（可选）：Mailtrap 沙盒（测试收件箱）ID。除非已设置 MAILTRAP_SANDBOX_ID，否则必填；可在每次调用时传入，以指定目标沙盒。
• base（可选）、requests（必填）：参见上文的 batch-send-transactional-email。

说明

大多数沙盒工具使用 sandbox_id（或回退到 MAILTRAP_SANDBOX_ID；旧版环境变量 MAILTRAP_TEST_INBOX_ID 仍可使用）。send-sandbox-email、get-sandbox-messages 和 show-sandbox-email-message 也接受旧版参数 test_inbox_id。get-sandbox-inbox、update-sandbox-inbox、delete-sandbox-inbox 和 clean-sandbox-inbox 使用 sandbox_id，并支持旧版参数 inbox_id（ID 相同；消息工具不使用 inbox_id）。入站邮件工具使用 inbox_id 指代另一种产品（接收邮件），而不是沙盒。

get-sandbox-messages

从 Mailtrap 测试收件箱中获取消息列表。可用于检查测试期间沙盒收到了哪些邮件。

参数：

• sandbox_id（可选）：首选参数。沙盒（测试收件箱）ID，除非已设置 MAILTRAP_SANDBOX_ID。
• test_inbox_id（可选）：sandbox_id 的旧版别名。
• page（可选）：分页页码（最小值：1）
• last_id（可选）：使用最后一条消息 ID 进行分页。返回指定消息 ID 之后的消息（最小值：1）
• search（可选）：用于筛选消息的搜索查询

说明

设置了 MAILTRAP_SANDBOX_ID 时，收件箱 ID 参数可选。如果未提供 sandbox_id、test_inbox_id 或环境变量，调用将失败。分页时可按需使用 page、last_id 或 search。

show-sandbox-email-message

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

参数：

• sandbox_id（可选）：首选参数。沙盒（测试收件箱）ID，除非已设置 MAILTRAP_SANDBOX_ID。
• test_inbox_id（可选）：sandbox_id 的旧版别名。
• message_id（必填）：要获取的沙盒邮件消息 ID

说明

先使用 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

启用沙盒的通过邮件接收地址（开启 Mailtrap 地址，以便通过 SMTP 将邮件投递到沙盒）。

参数：

• 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）

update-sending-domain

更新发送域名的跟踪和入站设置。

参数：

• sending_domain_id（必填）：发送域名 ID
• open_tracking_enabled（可选）：跟踪从此域名发送的邮件的打开情况
• click_tracking_enabled（可选）：跟踪从此域名发送的邮件中的链接点击情况
• tracking_opt_out_enabled（可选）：在已启用跟踪的邮件中添加退出跟踪链接。需要启用打开或点击跟踪
• auto_unsubscribe_link_enabled（可选）：自动在邮件中添加退订链接
• inbound_enabled（可选）：允许将此域名关联到入站收件箱，作为全收件 catch-all

除 sending_domain_id 外，至少还需提供一项设置。

delete-sending-domain

删除发送域名。

参数：

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

send-sending-domain-setup-instructions

将发送域名的 DNS 设置说明发送到指定地址。适合将 DNS 记录转发给 DevOps 团队成员。

参数：

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

get-company-info

获取发送域名的公司信息，该信息用于域名合规验证。

参数：

• sending_domain_id（必填）：发送域名 ID

create-company-info

设置发送域名的公司信息，这是域名合规验证所必需的。

参数：

• sending_domain_id（必填）：发送域名 ID
• name（必填）：公司或个人名称
• address（必填）：街道地址
• city（必填）：城市
• country（必填）：国家/地区
• zip_code（必填）：邮政编码
• website_url（必填）：公司网站 URL
• phone（可选）：电话号码
• privacy_policy_url（可选）：隐私政策页面的 URL
• terms_of_service_url（可选）：服务条款页面的 URL
• info_level（可选）：business 或 individual

update-company-info

更新发送域名的公司信息。

参数：

• sending_domain_id（必填）：发送域名 ID
• create-company-info 中的所有字段均为可选。至少需提供一项；未提供的字段保持不变。

list-suppressions

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

参数：

• email（可选）：邮箱筛选条件。仅返回与此地址匹配的抑制记录。

create-suppression

将邮箱地址添加到账户的抑制列表中，使 Mailtrap 停止向其发送邮件。

参数：

• email（必填）：要抑制的邮箱地址
• domain_id（必填）：此抑制记录适用的发送域名 ID
• sending_stream（必填）：transactional 或 bulk
• type（可选）：hard bounce、spam complaint、unsubscription 或 manual import。默认值为 manual import

delete-suppression

按 ID 删除抑制记录。除非该邮箱再次被抑制，否则 Mailtrap 会恢复向其发送邮件。

参数：

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

list-tracking-opt-outs

列出不参与打开和点击追踪的电子邮件地址。每次调用最多返回 1000 条记录。

参数：

• email（可选）：电子邮件筛选条件。仅返回与此地址匹配的退订记录
• start_time（可选）：仅返回在此时间（含）之后创建的退订记录（ISO 8601）
• end_time（可选）：仅返回在此时间（含）之前创建的退订记录（ISO 8601）
• last_id（可选）：分页游标，即上一条响应中的 last_id

create-tracking-opt-out

将某个电子邮件地址加入某个发送域名的打开和点击追踪排除名单。

参数：

• email（必填）：选择退出追踪的电子邮件地址
• domain_id（必填）：此排除项适用的发送域名 ID

delete-tracking-opt-out

从追踪排除名单中移除某个电子邮件地址，使其重新参与打开和点击追踪。

参数：

• tracking_opt_out_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-email-campaigns

按创建时间从新到旧列出账户的电子邮件营销活动，并使用页面令牌进行分页。可选按名称使用 search 筛选。

参数：

• token（可选）：要获取的页码（使用页面令牌分页）。默认为 1
• per_page（可选）：每页的营销活动数量。默认为 50，最大值为 100
• search（可选）：按名称筛选营销活动（不区分大小写的部分匹配）

get-email-campaign

按 ID 获取电子邮件营销活动。

参数：

• email_campaign_id（必填）：电子邮件营销活动的 ID

create-email-campaign

创建新的电子邮件营销活动。营销活动始终以 draft 状态创建；安排发送和启动需使用单独的工具（schedule-email-campaign、start-email-campaign）。

参数：

• name（必填）：营销活动名称
• domain_id（必填）：用于该营销活动的已验证发送域名 ID，由 Sending Domains 端点返回
• from_local_part（必填）：发件人地址中 @ 前面的本地部分
• template_attributes（必填）：内嵌电子邮件模板。包含：
  • subject（必填）：电子邮件主题行（最多 255 个字符）。支持合并标签，例如 Hi {{first_name}}
  • body_html（可选）：HTML 正文（设计内容）。安排发送或启动营销活动之前必须提供。请通过 href 包含 __unsubscribe_url__ 占位符的锚点加入退订链接
  • body_text（可选）：电子邮件正文的纯文本版本
  • merge_tags（可选）：主题或正文中引用的合并标签名称（不带其他内容），例如 ["first_name"]
• from_display_name（可选）：发件人标头中显示的名称
• reply_to（可选）：回复地址各部分（display_name、local_part、domain）
• delivery_mode（可选）：rapid（尽可能快速发送）或 gradual（按 delivery_options.emails_per_hour 限速）
• delivery_options（可选）：发送限速选项（emails_per_hour）
• contact_list_ids（可选）：要发送到的联系人列表 ID（视为包含列表的完整集合）
• contact_segment_ids（可选）：要发送到的联系人分群 ID（视为包含分群的完整集合）

update-email-campaign

更新处于 draft 状态的电子邮件营销活动。仅更改已提供的字段；模板将就地编辑。其他任何状态的营销活动均无法更新。

参数：

• email_campaign_id（必填）：要更新的电子邮件营销活动 ID
• 所有其他参数均为可选，且与 create-email-campaign 相同（name、domain_id、from_local_part、from_display_name、reply_to、template_attributes、delivery_mode、delivery_options、contact_list_ids、contact_segment_ids）

delete-email-campaign

按 ID 删除电子邮件营销活动。只有处于 draft 状态的营销活动才能删除。

参数：

• email_campaign_id（必填）：要删除的电子邮件营销活动 ID

start-email-campaign

立即开始发送处于 draft 状态的电子邮件营销活动。只有 draft 状态的营销活动才能启动；模板必须包含 body_html 设计，并且必须设置受众和已验证的发送域名。

参数：

• email_campaign_id（必填）：要启动的电子邮件营销活动 ID

schedule-email-campaign

将 draft 邮件营销活动安排在未来时间开始发送。只有 draft 状态的营销活动才能安排发送。

参数：

• email_campaign_id（必需）：要安排发送的邮件营销活动 ID
• datetime（必需）：营销活动的发送时间（ISO 8601）。必须晚于当前时间，且不超过 1 个月

cancel-email-campaign

取消 scheduled 状态的邮件营销活动，并将其恢复为 draft。只有 scheduled 状态的营销活动才能取消。

参数：

• email_campaign_id（必需）：要取消的邮件营销活动 ID

terminate-email-campaign

终止当前正在发送的邮件营销活动（状态为 started、queued 或 paused），中止正在进行的发送。

参数：

• email_campaign_id（必需）：要终止的邮件营销活动 ID

reset-email-campaign

将 scheduled 状态的邮件营销活动重置为 draft。只有 scheduled 状态的营销活动才能重置。

参数：

• email_campaign_id（必需）：要重置的邮件营销活动 ID

get-email-campaign-stats

获取邮件营销活动的汇总绩效统计数据（投递、打开、点击、退信、垃圾邮件投诉和取消订阅的数量与比率）。

参数：

• email_campaign_id（必需）：邮件营销活动 ID
• start_date（可选）：统计时间范围的开始日期（含），格式为 YYYY-MM-DD。默认为营销活动上次启动的日期
• end_date（可选）：统计时间范围的结束日期（含），格式为 YYYY-MM-DD。默认为当前日期

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 设为 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（必填）：令牌的显示名称
• expires_at（可选）：令牌过期时间，采用 ISO 8601 日期时间格式。省略时使用服务端默认值（1 年）；显式传入 null 表示令牌永不过期。过去的时间或超过 5 年后的时间将被拒绝
• 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
• expires_at（可选）：新令牌的过期时间，采用 ISO 8601 日期时间格式。省略时使用服务端默认值（1 年）；显式传入 null 表示令牌永不过期。过去的时间或超过 5 年后的时间将被拒绝

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（可选）：关联到自定义发送域（全收邮件收件箱）。省略时使用 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

列出收件箱中的会话线程（使用游标分页），可按 search 进行筛选。返回格式化摘要；如果还有更多结果，会提供下一页提示。

参数：

• inbox_id（必填）：收件箱 ID
• last_id（可选）：上一次响应中 last_id 的分页游标
• search（可选）：不区分大小写的文本，用于匹配线程主题及其消息的 from/to/cc/bcc 地址。分页时请传入相同的值

get-inbound-thread

获取单条收到的会话线程及其中嵌入的消息（按时间从早到晚排列）。以 JSON 格式返回完整的线程记录。

参数：

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

delete-inbound-thread

永久删除一条收到的会话线程。

参数：

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

list-inbound-forward-rules

列出收件箱的转发规则。返回格式化摘要。

参数：

• inbox_id（必填）：收件箱 ID

get-inbound-forward-rule

按 ID 获取单条收件箱转发规则。以 JSON 格式返回完整的规则记录，包括其条件和目标地址。

参数：

• inbox_id（必填）：收件箱 ID
• forward_rule_id（必填）：转发规则 ID

create-inbound-forward-rule

在入站收件箱中创建转发规则。符合所有条件的收到消息会转发到规则指定的目的地。

参数：

• inbox_id（必填）：收件箱 ID
• name（必填）：规则名称，在收件箱内必须唯一
• conditions（可选）：{ match_type, operator, value?, header_key? } 数组。match_type 为 sender、recipient 或 header；operator 为 equal、not_equal、contains、starts_with、ends_with、empty 或 not_empty（empty/not_empty 仅适用于 header，且不需要 value）；header 类型必须提供 header_key。省略该参数或传入 []，则匹配所有消息
• destinations（可选）：{ email } 数组，用于指定要转发匹配消息的邮箱

update-inbound-forward-rule

更新入站转发规则。只有提供的字段会发生变化；提供的 conditions 或 destinations 数组会替换整个集合。

参数：

• inbox_id（必填）：收件箱 ID
• forward_rule_id（必填）：转发规则 ID
• name（可选）：新规则名称
• conditions（可选）：替换条件集（格式与创建时相同）；[] 会移除所有条件，因此该规则将匹配所有消息
• destinations（可选）：替换目的地集合；[] 会移除所有目的地

delete-inbound-forward-rule

永久删除入站转发规则。

参数：

• inbox_id（必填）：收件箱 ID
• forward_rule_id（必填）：转发规则 ID

开发

1. 克隆仓库：

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

2. 安装依赖：

npm install

使用 Claude Desktop 或 Cursor 配置

提示

请参阅设置部分，了解配置文件的位置。

添加以下配置：

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_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": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

VS Code

提示

请参阅设置部分，了解配置文件的位置。

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_SANDBOX_ID": "your_sandbox_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。打开该 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 protected]

运行 MCPB 服务

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

# Or use the provided binary
mailtrap-mcpb-server

提示

使用 MCP Inspector 进行开发：

npm run dev:mcpb

错误处理

此服务采用符合 MCP 规范的结构化错误处理：

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

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

安全

• 使用 Zod schema 验证输入
• 安全处理环境变量
• 对操作进行超时保护（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 Token：确保已设置 MAILTRAP_API_TOKEN
2. 沙箱无法正常工作：在工具调用中提供 sandbox_id（或在发送/列出/显示消息的工具中使用旧版 test_inbox_id），或设置环境变量 MAILTRAP_SANDBOX_ID
3. 超时错误：检查网络连接和 Mailtrap API 状态
4. 验证错误：确保提供了所有必填字段

贡献

欢迎通过 GitHub 提交错误报告和拉取请求。本项目旨在营造安全、友好的协作环境，贡献者应遵守行为准则。

许可证

本软件包以开源形式提供，遵循 MIT 许可证的条款。

行为准则

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