Mailtrap

官方 Mailtrap MCP 伺服器

Mailtrap 的官方 MCP 伺服器 — 電子郵件投遞平台。它將您的 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 伺服器之前，您需要：

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 工具的預設 sandbox ID。可透過 sandbox_id 參數在每次呼叫時切換 sandbox。
• MAILTRAP_TEST_INBOX_ID - 當未提供 test_inbox_id 時，sandbox 工具的預設測試收件匣 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 是一個 MCP 伺服器的註冊表安裝程式和管理器，可與所有 AI 用戶端搭配使用。

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

使用方式

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

電子郵件發送操作：

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

電子郵件日誌（除錯投遞）：

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

發送統計：

• 「取得 2025 年 1 月的發送統計」
• 「顯示上個月按網域劃分的投遞率」
• 「從 2025-01-01 到 2025-01-31 我的電子郵件按類別的統計資料為何？」

Sandbox 操作：

• 「取得我 sandbox 收件匣中的所有訊息」
• 「顯示 sandbox 訊息的第一頁」
• 「在我的 sandbox 收件匣中搜尋包含『test』的訊息」
• 「顯示 ID 為 5159037506 的 sandbox 訊息詳細資料」

範本操作：

• 「列出我 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」

抑制清單：

• 「列出 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 中的聯絡人匯入我的 onboarding 清單」
• 「從我的電子報清單匯出所有聯絡人」
• 「為聯絡人 john.doe@example.com 記錄『trial_started』事件」

Webhook：

• 「列出我帳戶上設定的所有 Webhook」
• 「建立指向 https://example.com/hooks/mailtrap 的 Webhook，用於退信和垃圾郵件事件」
• 「更新 Webhook 4821，使其也發送投遞事件」
• 「刪除 Webhook 4821」

帳戶和帳單：

• 「我這個月的目前帳單使用量是多少？」
• 「我的方案還剩下多少封電子郵件？」
• 「列出有權存取此 Mailtrap 帳戶的所有人」
• 「顯示我帳戶上可用的權限資源」

API 權杖：

• 「列出我帳戶上的所有 API 權杖」
• 「為 staging 環境建立新的 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 的 bulk-stream API 傳送一批大量電子郵件。與 base + requests[] 相同的結構、驗證規則，以及內嵌與範本模式的規則皆與 batch-send-transactional-email 相同——唯一的差異是此工具會將呼叫路由至 bulk 端點，而非 transactional 端點。請參閱上方參數。

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 測試收件匣，而不會投遞給真實收件人。與 base + requests[] 相同的結構、驗證規則，以及內嵌與範本模式的規則皆與 batch-send-transactional-email 相同——差異在於此工具會將呼叫路由至 sandbox 端點，以用於單一測試收件匣。

參數：

• sandbox_id (選用)：Mailtrap sandbox（測試收件匣）ID。除非已設定 MAILTRAP_SANDBOX_ID，否則此為必填；每次呼叫時傳入以指定特定 sandbox。
• base (選用)、requests (必填)：請參閱上方 batch-send-transactional-email。

[!NOTE] 對於 sandbox 工具，請在工具呼叫中提供 test_inbox_id，或設定 MAILTRAP_TEST_INBOX_ID 環境變數。您可以透過傳入 test_inbox_id 在每次呼叫時切換收件匣。接受 sandbox_id 的工具會優先使用 MAILTRAP_SANDBOX_ID。

get-sandbox-messages

從您的 Mailtrap 測試收件匣擷取訊息清單。可用於檢查測試期間 sandbox 中收到了哪些電子郵件。

參數：

• page (選用)：分頁的頁碼（最小值：1）
• last_id (選用)：使用最後一則訊息 ID 進行分頁。傳回指定訊息 ID 之後的訊息（最小值：1）
• search (選用)：用於篩選訊息的搜尋查詢

[!NOTE] 所有參數皆為選用。若未提供任何參數，則會傳回收件匣中的第一頁訊息。使用 page 進行傳統分頁、last_id 進行游標式分頁，或使用 search 依內容篩選訊息。

show-sandbox-email-message

顯示來自您 Mailtrap 測試收件匣之特定電子郵件訊息的詳細資訊與內容，包括 HTML 與文字內文內容。

參數：

• message_id (必填)：要擷取的 sandbox 電子郵件訊息 ID

[!NOTE] 請先使用 get-sandbox-messages 取得訊息清單及其 ID，然後使用此工具檢視特定訊息的完整內容。

get-sandbox-project

依 ID 取得 sandbox 專案，包括其收件匣與電子郵件計數。

參數：

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

update-sandbox-project

重新命名現有的 sandbox 專案。

參數：

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

list-sandboxes

列出 API 權杖在所有專案中可存取的每個 sandbox。

參數：

• 無需任何參數

mark-sandbox-as-read

將 sandbox 中的所有訊息標記為已讀。

參數：

• sandbox_id (必填)：要操作的 sandbox 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 垃圾郵件報告（分數、規則、完整報告）。為 include_spam_report: true 於 show-sandbox-email-message 上的獨立替代方案。

參數：

• sandbox_id（選填）：沙箱 ID。若未提供，則回退至 MAILTRAP_SANDBOX_ID。
• message_id（必填）：沙箱郵件 ID

get-sandbox-message-html-analysis

取得沙箱郵件的 HTML 分析報告（用戶端相容性分數、問題元素）。為 include_html_analysis: true 於 show-sandbox-email-message 上的獨立替代方案。

參數：

• 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

取得聯絡人匯入工作（已建立/已開始/已完成/已失敗）的狀態，以及已建立/已更新/超過限制的計數。

參數：

• 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，由寄件網域端點傳回
• 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 即可移除該權限。

參數：

• 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（選填）：附加至自訂寄送網域（catch-all 收件匣）。省略時使用 Mailtrap 託管的收件匣

update-inbound-inbox

重新命名入站收件匣。

參數：

• folder_id（必填）：入站資料夾的 ID
• inbox_id（必填）：收件匣的 ID
• name（必填）：新的收件匣名稱

delete-inbound-inbox

永久刪除入站收件匣。

參數：

• folder_id（必填）：入站資料夾的 ID
• inbox_id（必填）：收件匣的 ID

list-inbound-messages

列出入站收件匣中收到的訊息（游標分頁）。當有更多結果時，回傳格式化摘要並附帶下一頁提示。

參數：

• inbox_id（必填）：收件匣的 ID
• last_id（選填）：來自先前回應 last_id 的分頁游標

get-inbound-message

取得單一入站訊息及其完整內文與附件下載 URL。以 JSON 回傳完整的訊息記錄。

參數：

• inbox_id（必填）：收件匣的 ID
• message_id（必填）：訊息的 ID

delete-inbound-message

永久刪除入站訊息。

參數：

• inbox_id（必填）：收件匣的 ID
• message_id（必填）：訊息的 ID

reply-to-inbound-message

回覆入站訊息（寄送至原始寄件者）。會寄送真實電子郵件。地址可接受純電子郵件字串或 { email, name? }。

參數：

• inbox_id（必填）：收件匣的 ID
• message_id（必填）：要回覆的訊息 ID
• text / html（至少建議一個）：回覆內文
• from（選填）：寄件者。Mailtrap 託管收件匣會拒絕；自訂網域收件匣為必填
• cc / bcc / reply_to（選填）：其他地址
• category（選填）：訊息類別
• attachments（選填）：{ content (base64), filename, type?, disposition?, content_id? } 的陣列
• headers / custom_variables（選填）：字串值物件

reply-all-to-inbound-message

回覆入站訊息並副本給原始的其他收件者。會寄送真實電子郵件。參數與 reply-to-inbound-message 相同。

參數：

• inbox_id（必填）：收件匣的 ID
• message_id（必填）：要回覆的訊息 ID
• 加上與 reply-to-inbound-message 相同的選填寄送欄位

forward-inbound-message

將入站訊息轉寄給新的收件者。會寄送真實電子郵件。

參數：

• inbox_id（必填）：收件匣的 ID
• message_id（必填）：要轉寄的訊息 ID
• to（必填）：至少一位收件者（純電子郵件字串或 { email, name? }，或陣列）
• 加上與 reply-to-inbound-message 相同的選填寄送欄位

list-inbound-threads

列出入站收件匣中的對話串（游標分頁）。當有更多結果時，回傳格式化摘要並附帶下一頁提示。

參數：

• inbox_id（必填）：收件匣的 ID
• last_id（選填）：來自先前回應 last_id 的分頁游標

get-inbound-thread

取得單一入站對話串及其嵌入的訊息（由舊到新）。以 JSON 回傳完整的對話串記錄。

參數：

• inbox_id（必填）：收件匣的 ID
• thread_id（必填）：對話串的 ID

delete-inbound-thread

永久刪除入站對話串。

參數：

• inbox_id（必填）：收件匣的 ID
• thread_id（必填）：對話串的 ID

開發

1. 複製儲存庫：

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

2. 安裝相依套件：

npm install

使用 Claude Desktop 或 Cursor 進行設定

[!TIP] 請參閱 Setup 章節中的設定檔位置。

新增以下設定：

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

如果您使用 asdf 管理 Node.js，應使用可執行檔的絕對路徑：

（Mac 範例）

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}

VS Code

[!TIP] 請參閱 Setup 章節中的設定檔位置。

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "your_sender@example.com",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
        }
      }
    }
  }
}

測試

對真實 Mailtrap 執行工具

有兩種方式可以對真實 Mailtrap 帳戶進行端對端的工具測試：MCP Inspector 瀏覽器介面（適合互動式探索），或其 CLI 模式（適合從 shell 進行一次性呼叫）。

兩者都需要先建置 bundle：

npm run build

並在您的 shell 中匯出 MAILTRAP_API_TOKEN 和 MAILTRAP_ACCOUNT_ID（mcp:cli 腳本會將兩者轉發給啟動的伺服器）。

瀏覽器介面

npm run dev

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

CLI

若要進行無需介面的一次性呼叫，請使用 npm run mcp:cli。在 -- 之後傳入 Inspector 的 CLI 旗標，以便 npm 原樣轉發：

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

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

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

執行 MCPB 伺服器

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

# Or use the provided binary
mailtrap-mcpb-server

[!TIP] 若要搭配 MCP Inspector 進行開發：

npm run dev:mcpb

錯誤處理

此伺服器使用符合 MCP 慣例的結構化錯誤處理：

• VALIDATION_ERROR：輸入驗證失敗
• CONFIGURATION_ERROR：缺少或無效的設定
• EXECUTION_ERROR：執行時期錯誤
• TIMEOUT：操作逾時（預設 30 秒）

錯誤訊息包含可操作的說明，並以結構化形式記錄。

安全性

• 透過 Zod 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 權杖：請確認已設定 MAILTRAP_API_TOKEN
2. Sandbox 無法運作：在工具呼叫中提供 test_inbox_id，或設定 MAILTRAP_TEST_INBOX_ID 環境變數
3. 逾時錯誤：檢查網路連線及 Mailtrap API 狀態
4. 驗證錯誤：請確認已提供所有必填欄位

貢獻

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

授權

此套件以 MIT License 條款作為開放原始碼提供。

行為準則

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