Mailtrap

官方

與 Mailtrap Email API 整合。

GitHub

你可以用 Mailtrap MCP 做什麼？

傳送交易型電子郵件 — 請助理傳送電子郵件，並提供主旨和文字或 HTML 內文，也可選擇使用範本和變數。
在 Email Sandbox 中測試 — 將郵件傳送至沙箱，並檢視其內容、標頭和附件，不會送達真實收件者。
透過記錄偵錯傳送問題 — 列出並篩選已傳送的電子郵件記錄，然後開啟特定郵件以檢視其事件歷程和傳送狀態。
分析寄送統計資料 — 取得指定日期範圍內的送達率、退信率、開啟率、點擊率和垃圾郵件率，並依網域、類別或日期細分。
管理範本 — 建立、列出、更新及刪除儲存在 Mailtrap 帳戶中的電子郵件範本。
管理網域和抑制清單 — 列出網域、取得 DNS 設定說明，並檢視或移除遭抑制的地址。

文件

Mailtrap 官方 MCP Server

Mailtrap 官方 MCP server——電子郵件傳遞平台。它可將您的 Mailtrap 帳戶連接至 Claude、Cursor、VS Code 及其他相容 MCP 的 AI 助理。

使用自然語言提示，即可傳送交易型與大量電子郵件、在 Email Sandbox 中安全測試訊息、管理範本、聯絡人、網域和 Webhook、檢視電子郵件記錄與傳遞統計資料、排解傳遞問題，以及管理帳戶資源。

功能

Email API 和 SMTP — 傳送交易型與大量電子郵件，包括批次訊息和範本訊息。
電子郵件測試 — 在 Email Sandbox 中測試訊息，並檢視內容、標頭、附件、垃圾郵件評分及 HTML 用戶端相容性。
傳遞監控 — 搜尋電子郵件記錄、檢視事件歷程記錄，並分析傳遞、退信、開啟、點擊和垃圾郵件率。
電子郵件基礎架構 — 管理網域、DNS 驗證、Webhook 和抑制清單。
聯絡人 — 管理聯絡人、清單、自訂欄位和事件，並可匯入及匯出。
帳戶管理 — 檢視帳單用量，並管理存取權、權限、API 權杖和子帳戶。

支援的 MCP 用戶端

適用於 Claude Desktop、Claude Code、Cursor、VS Code 及任何其他相容 MCP 的用戶端。下方提供各用戶端的設定說明。

先決條件

使用此 MCP server 前，您需要：

建立 Mailtrap 帳戶
驗證您的網域
從 Mailtrap API 設定取得 API 權杖
從 Mailtrap 帳戶管理取得帳戶 ID
安裝 Node.js 22 或更新版本，除非您使用 Docker 映像

必要的環境變數：

MAILTRAP_API_TOKEN - 所有功能皆必須設定
MAILTRAP_ACCOUNT_ID - 範本、get-sending-stats、電子郵件記錄、sandbox 清單/顯示、網域和抑制清單功能皆必須設定。僅下列工具可選擇不設定：傳送工具（send-email、send-sandbox-email 和 batch-send-* 工具）、電子郵件行銷活動工具、get-marketing-stats、公司資訊工具、追蹤退出工具，以及 list-accounts。

選用（也可作為工具參數傳入）：

DEFAULT_FROM_EMAIL - 當 send-email、send-sandbox-email 或 batch-send-* 工具未提供 from 時，作為預設寄件者電子郵件地址（填入 base.from）。可透過 from 參數在每次呼叫時切換寄件者。
MAILTRAP_SANDBOX_ID - 當工具未提供 sandbox_id 時，作為預設 sandbox ID（send/list/show sandbox message 工具仍接受舊版 test_inbox_id）。可透過參數在每次呼叫時切換 sandbox。
MAILTRAP_TEST_INBOX_ID - 已棄用的 MAILTRAP_SANDBOX_ID 別名；現有設定仍會將其作為備援讀取，使用時會在 stderr 記錄棄用警告。
MAILTRAP_ORGANIZATION_ID - 組織工具（list-sub-accounts、create-sub-account、delete-sub-account）必須設定。
MAILTRAP_ORGANIZATION_API_TOKEN - 組織範圍的 API 權杖。組織工具必須設定（與 MAILTRAP_API_TOKEN 分開）。

快速安裝

Docker

使用 Docker MCP Catalog 映像透過 stdio 執行 server：

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 server 的登錄檔和安裝程式，可搭配 AI 用戶端使用。

將已發布的 server（mailtrap/mailtrap-mcp）安裝至本機用戶端（視需要替換用戶端名稱）：

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

其他用戶端（cursor、windsurf 等）的設定方式，以及如何發布更新，請參閱 Smithery CLI 文件。

設定

Claude Desktop

使用 MCPB 安裝 Mailtrap server。您可以在 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_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": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "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": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

[!TIP] 變更「env」區段後，別忘了重新啟動 MCP server。

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

這會建立 mailtrap-mcp.mcpb。指令碼會將 dist/、manifest.json、icon.png 和授權檔複製到 mcpb-build/，在該目錄安裝正式環境相依套件，並只封裝該目錄。請勿從儲存庫根目錄執行 mcpb pack .。

使用方式

完成設定後，您可以要求代理程式傳送電子郵件和管理範本，例如：

電子郵件傳送操作：

「傳送電子郵件給 john.doe@example.com，主旨為『明天開會』，並親切提醒對方我們即將舉行的會議。」
「寄信給 sarah@example.com，告知專案最新進度，並副本給 team@example.com」
「將歡迎範本（uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96）傳送給 new@example.com，並使用變數 { name: 'Alex' }」
「傳送 sandbox 電子郵件給 test@example.com，主旨為『範本測試』，預覽我們的歡迎郵件外觀」

電子郵件記錄（偵錯傳遞）：

「列出我最近傳送的電子郵件記錄」
「顯示寄給 user@example.com 的電子郵件記錄」
「取得 ID 為 abc-123-uuid 的電子郵件記錄訊息，以檢查傳遞狀態」

統計資料：

「取得 2025 年 1 月的傳送統計資料」
「顯示上個月依網域分類的傳遞率」
「2025-01-01 至 2025-01-31 期間，我依類別劃分的電子郵件統計資料為何？」
「我的電子郵件行銷上個月成效如何？比較行銷活動與自動化流程」

Sandbox 操作：

「取得我 sandbox 中的所有訊息」
「顯示 sandbox 訊息的第一頁」
「搜尋我 sandbox 中包含『test』的訊息」
「在專案 42 中建立名為『QA』的 sandbox，並提供其 SMTP 認證資料」
「刪除 sandbox 1234 中的所有訊息」
「顯示 ID 為 5159037506 的 sandbox 訊息詳細資料」

範本操作：

「列出我 Mailtrap 帳戶中的所有電子郵件範本」
「建立名為『歡迎郵件』、主旨為『歡迎使用我們的平台！』的新電子郵件範本」
「更新 ID 為 12345 的範本，將主旨改為『更新後的歡迎訊息』」
「刪除 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」

抑制清單：

「列出 bounced@example.com 的抑制項目」
「在網域 3938 的交易型郵件串流中抑制 bounced@example.com」
「顯示所有遭抑制的電子郵件地址」
「為什麼 user@example.com 收不到我的電子郵件？」
「將 user@example.com 從抑制清單中移除」

追蹤退出：

「停止追蹤 privacy@example.com 在網域 3938 上的開啟和點擊」
「列出所有已退出追蹤的人」

聯絡人和清單：

「將 john.doe@example.com 新增至我的電子報聯絡人清單」
「顯示我的所有聯絡人清單」
「建立名為『signup_source』的聯絡人欄位，以追蹤聯絡人的來源」
「更新聯絡人 john.doe@example.com，將其方案設為『pro』」
「將此 CSV 中的聯絡人匯入我的新手引導清單」
「從我的電子報清單匯出所有聯絡人」
「為聯絡人 john.doe@example.com 記錄『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』建立新的子帳戶」

更名的工具

Mailtrap 現在將測試收件匣稱為 sandboxes，將寄件網域稱為 domains，工具名稱也隨之調整。工具清單中不再顯示舊名稱，但仍可呼叫這些名稱，並會在 stderr 記錄棄用警告。這些名稱將在未來的主要版本中移除。

MCP 用戶端和代理程式架構會依據公開的工具名稱比對允許、拒絕和篩選清單，因此請將任何個別工具項目改為新名稱：拒絕清單中的 delete-sending-domain 將不再封鎖 delete-domain。

舊名稱	新名稱
`create-sandbox-inbox`	`create-sandbox`
`get-sandbox-inbox`	`get-sandbox`
`update-sandbox-inbox`	`update-sandbox`
`delete-sandbox-inbox`	`delete-sandbox`
`clean-sandbox-inbox`	`clean-sandbox`
`list-sending-domains`	`list-domains`
`get-sending-domain`	`get-domain`
`create-sending-domain`	`create-domain`
`update-sending-domain`	`update-domain`
`delete-sending-domain`	`delete-domain`
`send-sending-domain-setup-instructions`	`send-domain-setup-instructions`
`sending_domain_id` 網域和公司資訊工具的參數	`domain_id`
`MAILTRAP_TEST_INBOX_ID` 環境變數	`MAILTRAP_SANDBOX_ID`

與 API 欄位對應的篩選條件會保留原名稱：sending_domain_id（用於 list-email-logs）以及 sending_domain_ids（用於統計工具）。

可用工具

send-email

透過 Mailtrap 傳送交易型電子郵件。支援兩種互斥模式——內嵌內容（subject + text/html）或範本模式（template_uuid）。

參數：

from（選填）：寄件者，格式為 { email, name? }（執行時也接受純電子郵件字串）。若未提供，則使用 DEFAULT_FROM_EMAIL。
to（選填）：收件者陣列，格式為 { email, name? } 物件（執行時也接受純電子郵件字串或單一非陣列地址）。若提供了 cc 或 bcc，則此欄位為選填；to / cc / bcc 至少一項必須包含收件者。
cc（選填）：CC 收件者陣列，格式為 { email, name? } 物件（執行時也接受純電子郵件字串）。
bcc（選填）：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 批次傳送大量電子郵件。其結構、驗證方式及內嵌內容與範本規則，皆與 batch-send-transactional-email 相同，使用 base + requests[]；唯一差異是此工具會透過大量郵件端點，而非交易型郵件端點，來路由呼叫。請參閱上方參數。

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（字串陣列）

get-marketing-stats

取得指定日期範圍內，跨行銷活動與自動化流程彙總的 Email Marketing 統計資料：傳送、傳送成功、退信、開啟、點擊、垃圾郵件及取消訂閱的次數與比率。delivery_rate 和 bounce_rate 是 sent_count 的占比；其他比率則是 delivery_count 的占比。

參數：

start_date（必填）：日期範圍的開始日期（含），YYYY-MM-DD
end_date（必填）：日期範圍的結束日期（含），YYYY-MM-DD
sending_domain_ids（選填）：僅限這些網域 ID（整數陣列）
sources（選填）：campaigns 或 automations 可將統計資料限縮至該來源；省略此項或同時傳入兩者，即可取得所有 Email Marketing 流量（字串陣列）
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（選填）：範本的新類別

[!NOTE] 呼叫 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 (選填)：CC 收件者陣列，格式為 { email, name? } 物件（執行時也接受純電子郵件字串）。
bcc (選填)：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[] — 差異在於此工具會透過沙箱端點，將呼叫路由至單一沙箱。

參數：

sandbox_id (選填)：Mailtrap 沙箱 ID。除非已設定 MAILTRAP_SANDBOX_ID，否則為必填；可在每次呼叫時傳入，以指定目標沙箱。
base (選填)、requests (必填)：請參閱上方的 batch-send-transactional-email。

[!NOTE] 大多數沙箱工具會使用 sandbox_id（或改用 MAILTRAP_SANDBOX_ID；已棄用的環境變數 MAILTRAP_TEST_INBOX_ID 仍可使用）。send-sandbox-email、get-sandbox-messages 和 show-sandbox-email-message 也接受舊版 test_inbox_id。get-sandbox、update-sandbox、delete-sandbox 和 clean-sandbox 使用 sandbox_id，並接受舊版 inbox_id（相同 ID；訊息工具不使用 inbox_id）。收件郵件工具使用 inbox_id，代表不同產品（收到的郵件），而非沙箱。

get-sandbox-messages

取得 Mailtrap 沙箱中的訊息清單。可用於檢查測試期間沙箱收到的電子郵件。

參數：

sandbox_id (選填)：優先使用。除非已設定 MAILTRAP_SANDBOX_ID，否則為沙箱 ID。
test_inbox_id (選填)：sandbox_id 的舊版別名。
page (選填)：分頁頁碼（最小值：1）
last_id (選填)：使用最後一則訊息 ID 進行分頁。傳回指定訊息 ID 之後的訊息（最小值：1）
search (選填)：用於篩選訊息的搜尋查詢

[!NOTE] 設定 MAILTRAP_SANDBOX_ID 時，沙箱 ID 參數可省略。若未提供 sandbox_id、test_inbox_id 或環境變數，呼叫將會失敗。分頁：視需要使用 page、last_id 或 search。

show-sandbox-email-message

顯示 Mailtrap 沙箱中特定電子郵件訊息的詳細資訊與內容，包括 HTML 和文字內文。

參數：

sandbox_id (選填)：優先使用。除非已設定 MAILTRAP_SANDBOX_ID，否則為沙箱 ID。
test_inbox_id (選填)：sandbox_id 的舊版別名。
message_id (必填)：要取得的沙箱電子郵件訊息 ID

[!NOTE] 先使用 get-sandbox-messages 取得訊息 ID，再使用此工具取得完整內容。

list-sandbox-projects

列出所有沙箱專案及其沙箱。

參數：

不需要參數

create-sandbox-project

建立新的沙箱專案，以便將沙箱分組。

參數：

name (必填)：專案名稱（2–100 個字元）

get-sandbox-project

依 ID 取得沙箱專案，包括其沙箱和電子郵件數量。

參數：

project_id (必填)：要取得的專案 ID

update-sandbox-project

重新命名現有的沙箱專案。

參數：

project_id (必填)：要更新的專案 ID
name (必填)：專案的新名稱（2–100 個字元）

delete-sandbox-project

刪除沙箱專案及其所有沙箱。

參數：

project_id (必填)：要刪除的專案 ID

create-sandbox

在專案中建立新的沙箱。傳回新沙箱的 SMTP 認證資料。

參數：

project_id (必填)：要在其中建立沙箱的專案 ID
name (必填)：沙箱名稱

get-sandbox

取得沙箱詳細資訊，包括 SMTP 認證資料、電子郵件數量和狀態。

參數：

sandbox_id (選填)：沙箱 ID。除非已設定 MAILTRAP_SANDBOX_ID，否則為必填。
inbox_id (選填)：sandbox_id 的舊版別名。

update-sandbox

更新沙箱名稱或電子郵件使用者名稱。

參數：

sandbox_id (必填)：沙箱 ID（舊版別名：inbox_id）
name (選填)：沙箱的新名稱
email_username (選填)：沙箱的新電子郵件使用者名稱

必須提供 name 或 email_username 至少其中一項。

delete-sandbox

刪除沙箱及其所有訊息。

參數：

sandbox_id (必填)：沙箱 ID（舊版別名：inbox_id）

clean-sandbox

刪除沙箱中的所有訊息，但不刪除沙箱本身。

參數：

sandbox_id (必填)：沙箱 ID（舊版別名：inbox_id）

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 端進行任何轉換前的 HTML，例如 CID 連結改寫）。

參數：

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-domains

列出網域及其 DNS 驗證狀態。

參數：

不需要參數

get-domain

依 ID 取得網域及其驗證狀態（包括 DNS 記錄）。將 include_setup_instructions 設為 true，即可選擇在回應中加入 DNS 設定說明。

參數：

domain_id (必填)：網域 ID（舊版別名：sending_domain_id）
include_setup_instructions (選填)：若為 true，則在回應中附加 DNS 設定說明。預設值：false

create-domain

建立新網域。建立後，請新增 DNS 記錄以驗證網域（使用 get-domain 並傳入 include_setup_instructions: true 查看記錄）。

參數：

domain_name (必填)：網域名稱（例如 example.com）

update-domain

更新網域的追蹤與收件設定。

參數：

domain_id（必填）：網域 ID（舊版別名：sending_domain_id）
open_tracking_enabled（選填）：追蹤從此網域寄出的電子郵件是否開啟
click_tracking_enabled（選填）：追蹤從此網域寄出的電子郵件中的連結是否點擊
tracking_opt_out_enabled（選填）：在已追蹤的電子郵件中加入追蹤退出連結。需要啟用開啟或點擊追蹤
auto_unsubscribe_link_enabled（選填）：自動在電子郵件中加入取消訂閱連結
inbound_enabled（選填）：允許將此網域附加至收件匣，作為萬用收件網域

必須提供至少一項除 domain_id 以外的設定。

delete-domain

刪除網域。

參數：

domain_id（必填）：要刪除的網域 ID（舊版別名：sending_domain_id）

send-domain-setup-instructions

將網域的 DNS 設定說明寄送至指定地址。適合將 DNS 記錄轉寄給 DevOps 團隊成員。

參數：

domain_id（必填）：網域 ID（舊版別名：sending_domain_id）
email（必填）：接收 DNS 設定說明的電子郵件地址

get-company-info

取得網域的公司資訊，用於網域合規性驗證。

參數：

domain_id（必填）：網域 ID（舊版別名：sending_domain_id）

create-company-info

設定網域的公司資訊，這是網域合規性驗證的必要項目。

參數：

domain_id（必填）：網域 ID（舊版別名：sending_domain_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

更新網域的公司資訊。

參數：

domain_id（必填）：網域 ID（舊版別名：sending_domain_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（必填）：顯示名稱（例如 "First 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 組合篩選條件的聯絡人。傳回匯出工作記錄；使用 get-contact-export 輪詢狀態，待 status 為 finished 後取得下載 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，由 list-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 帳戶，以及各帳戶的存取層級。無需 MAILTRAP_ACCOUNT_ID，可用此工具查找帳戶 ID。

參數：

不需要參數

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（必填）：權杖的顯示名稱
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（必填）：新子帳戶的顯示名稱

delete-sub-account

依 ID 永久刪除子帳戶及其所有資料。刪除最後一個子帳戶會一併刪除組織；重複呼叫會傳回 404。同時刪除同一個子帳戶時會傳回 409。需要 MAILTRAP_ORGANIZATION_ID 環境變數和組織管理員權限，且組織必須啟用 Organization & Sub-accounts 功能（否則傳回 403）。

參數：

sub_account_id（必填）：要刪除的子帳戶 ID

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

取得單封收件郵件及其完整內文和附件下載網址。以 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 (選填)：不區分大小寫的文字，會比對對話串主旨，以及其中郵件的寄件者／收件者／副本／密件副本地址。分頁時請傳入相同值

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（只有 header 可使用 empty/not_empty，且不接受任何 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

開發

複製儲存庫：

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

安裝相依套件：

npm install

使用 Claude Desktop 或 Cursor 設定

[!TIP] 請參閱設定一節，了解設定檔的位置。

新增以下設定：

{
  "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_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": "22.14.0",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

VS Code

[!TIP] 請參閱設定一節，了解設定檔的位置。

{
  "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_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

測試

使用真實的 Mailtrap 執行工具

有兩種方式可在真實的 Mailtrap 帳戶上端對端測試工具：使用 MCP Inspector 瀏覽器介面進行互動式探索，或使用其 CLI 模式從 shell 執行單次呼叫。

兩種方式都必須先建置套件：

npm run build

並在 shell 中匯出 MAILTRAP_API_TOKEN 和 MAILTRAP_ACCOUNT_ID（mcp:cli 指令碼會將兩者傳遞給啟動的伺服器）。

瀏覽器介面

npm run dev

Inspector 會輸出類似 http://localhost:6274 的網址。開啟網址，切換至 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-domain-setup-instructions \
  --tool-arg 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 結構描述驗證輸入
安全處理環境變數
操作逾時保護（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")'

疑難排解

常見問題：

缺少 API Token：確認已設定 MAILTRAP_API_TOKEN
Sandbox 無法運作：在工具呼叫中提供 sandbox_id（或在寄送／列出／顯示郵件工具中使用舊版 test_inbox_id），或設定 MAILTRAP_SANDBOX_ID 環境變數
逾時錯誤：檢查網路連線和 Mailtrap API 狀態
驗證錯誤：確認已提供所有必填欄位

貢獻

歡迎透過 GitHub 提交錯誤回報和提取要求。本專案旨在打造安全、友善的協作空間，並期望貢獻者遵守行為準則。

授權條款

此套件以開放原始碼形式提供，並遵循 MIT License 條款。

行為準則

所有參與 Mailtrap 專案程式碼庫、問題追蹤系統、聊天室和郵件清單的人員，都應遵守行為準則。