Mailtrap

官方

與 Mailtrap Email API 整合。

GitHub

你可以用 Mailtrap MCP 做什麼？

發送交易電子郵件 — 要求通過 send-email 發送電子郵件，使用內聯內容或模板，包括副本/密件副本和自訂變數。
管理電子郵件模板 — 使用 list-templates、create-template、update-template 或 delete-template 來維護可重複使用的電子郵件設計。
檢查傳遞日誌 — 使用收件人、狀態或日期等篩選條件查詢 list-email-logs，然後使用 get-email-log-message 深入查看詳細資訊。
在沙盒中測試電子郵件 — 通過 send-sandbox-email 發送到測試收件匣，然後使用 get-sandbox-messages 和 show-sandbox-email-message 檢視訊息。
分析發送效能 — 通過 get-sending-stats 取得傳遞率、退信率和參與率，可選擇按網域或類別細分。
設定發送基礎架構 — 管理 list-sending-domains，建立或刪除網域，並取得 DNS 設定說明。

文件

MCP Mailtrap Server

一個透過 Mailtrap 提供寄送與沙盒測試工具的 MCP 伺服器。

前置需求

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

建立 Mailtrap 帳戶
驗證您的網域
從 Mailtrap API 設定取得您的 API 權杖
從 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 Bundles 的主機上輕鬆安裝，您可以散佈 .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。

使用方式

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

電子郵件寄送操作：

「寄送一封主旨為『Meeting Tomorrow』的電子郵件給 john.doe@example.com，並附上關於我們即將到來會議的友善提醒。」
「寄電子郵件給 sarah@example.com 告知專案更新，並副本給 team@example.com 的團隊」
「將歡迎範本（uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96）連同變數 { name: 'Alex' } 寄送給 new@example.com」
「寄送主旨為『Test Template』的沙盒電子郵件給 test@example.com，以預覽我們的歡迎電子郵件外觀」

電子郵件記錄（除錯投遞）：

「列出我最近寄送的電子郵件記錄」
「顯示寄送給 user@example.com 的電子郵件記錄」
「取得 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 及 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 的 bulk-stream 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（字串陣列）

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 執行更新時，至少必須提供一個可更新的欄位（name、subject、html、text 或 category）。

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 (選填)：副本 (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] 對於沙盒工具，請在工具呼叫中提供 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 token 在所有專案中可存取的每個沙盒。

參數：

無需任何參數

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 記錄以驗證網域（使用 get-sending-domain 並搭配 include_setup_instructions: true 來查看記錄）。

參數：

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 token 可存取的 Mailtrap 帳戶，以及每個帳戶的存取層級。

參數：

無需任何參數

get-billing-usage

取得帳戶目前的計費週期使用量：寄送與測試方案、限制及目前計數。

參數：

無需任何參數

list-account-accesses

列出帳戶的存取記錄（使用者、邀請、API token）。可選的篩選條件可將結果縮小至特定資源。需要帳戶管理員/擁有者權限。

參數：

domain_uuids (選用)：依寄送網域 UUID 篩選（字串陣列）
inbox_ids (選用)：依沙盒收件匣 ID 篩選（字串陣列）
project_ids (選用)：依沙盒專案 ID 篩選（字串陣列）

remove-account-access

依 ID 移除帳戶存取。對於 User 指定者，這會撤銷其權限；對於 Invite 或 ApiToken 指定者，則會完全移除該指定者。需要管理員/擁有者權限。

參數：

account_access_id (必填)：要移除的存取記錄 ID

get-permission-resources

取得 API token 具有管理員存取權的所有資源（收件匣、專案、網域、帳單、帳戶），依階層巢狀排列。

參數：

無需任何參數

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

開發

複製儲存庫：

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_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] 請參閱設定一節中設定檔的位置。

{
  "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 瀏覽器 UI 進行互動式探索，或使用其 CLI 模式從 shell 進行單次呼叫。

兩者都需要先建置 bundle：

npm run build

並在 shell 中匯出 MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID（mcp:cli 腳本會將兩者轉發給產生的伺服器）。

瀏覽器 UI

npm run dev

Inspector 會列印類似 http://localhost:6274 的 URL。開啟後切換到 Tools 標籤，選擇工具（例如 get-template），以 JSON 填寫參數，然後按 Run。Mailtrap 回應會顯示在下方面板中。

CLI

若要在不使用 UI 的情況下進行單次呼叫，請使用 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 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")'

疑難排解

常見問題：

缺少 API 權杖：請確認已設定 MAILTRAP_API_TOKEN
Sandbox 無法運作：在工具呼叫中提供 test_inbox_id，或設定 MAILTRAP_TEST_INBOX_ID 環境變數
逾時錯誤：檢查網路連線及 Mailtrap API 狀態
驗證錯誤：請確認已提供所有必填欄位

貢獻

歡迎在 GitHub 上提交錯誤回報及 pull request。本專案旨在成為安全、友善的協作空間，貢獻者應遵守行為準則。

授權

此套件以開放原始碼形式提供，採用 MIT 授權條款。

行為準則

所有在 Mailtrap 專案的程式碼庫、問題追蹤器、聊天室及郵件列表中互動的人，都應遵守行為準則。