MCP Mailtrap Server

公式 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 - テンプレート、統計情報、メールログ、サンドボックスの一覧表示／表示、送信ドメイン、抑制リストで必須です。送信ツール（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 が指定されていない場合のデフォルトのサンドボックス（テスト受信トレイ）IDです（サンドボックスメッセージの送信／一覧表示／表示ツールでは、旧形式の test_inbox_id も引き続き使用できます）。パラメーターを使って、呼び出しごとに受信トレイを切り替えられます。
• MAILTRAP_TEST_INBOX_ID - MAILTRAP_SANDBOX_ID の旧形式の別名です。既存の設定との互換性のため、引き続きフォールバック値として読み込まれます。
• MAILTRAP_ORGANIZATION_ID - 組織ツール（list-sub-accounts、create-sub-account）で必須です。
• MAILTRAP_ORGANIZATION_API_TOKEN - 組織スコープの API トークンです。組織ツールで必須です（MAILTRAP_API_TOKEN とは別のトークンです）。

クイックインストール

Docker

Docker MCP Catalog のイメージを使って、stdio 経由でサーバーを実行します。

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

必須および任意の環境変数については、前提条件を参照してください。

このリポジトリからビルドするには、docker build -t mcp/mailtrap . を実行します。

Smithery CLI

Smithery は、AI クライアントで利用できる MCP サーバーのレジストリ兼インストーラーです。

公開済みサーバー（mailtrap/mailtrap-mcp）をローカルクライアントにインストールします（必要に応じてクライアント名を置き換えてください）。

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

他のクライアント（cursor、windsurf など）や更新の公開については、Smithery CLI のドキュメントを参照してください。

セットアップ

Claude Desktop

MCPB を使用して Mailtrap サーバーをインストールします。ファイルはリリースから入手できます。
.MCPB ファイルをダウンロードして開いてください。Claude Desktop を使用している場合は、ファイルが開き、設定するよう案内されます。

Claude Desktop または Cursor

以下の設定を追加します。

{
  "mcpServers": {
    "mailtrap": {
      "command": "npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Node.js の管理に asdf を使用している場合は、実行ファイルの絶対パスを指定する必要があります（Mac の例）。

{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/npx",
      "args": ["-y", "mcp-mailtrap"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Claude Desktop の設定ファイルの場所

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

Windows：%APPDATA%\Claude\claude_desktop_config.json

Cursor の設定ファイルの場所

Mac：~/.cursor/mcp.json

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

VS Code

設定を手動で変更する

コマンドパレットで Preferences: Open User Settings (JSON) を実行します。

次に、設定ファイルに以下の設定を追加します。

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "npx",
        "args": ["-y", "mcp-mailtrap"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

ヒント

「env」セクションを変更した後は、MCP サーバーを再起動してください。

MCP Bundle（MCPB）

MCP Bundle に対応するホストに簡単にインストールできるよう、.mcpb バンドルファイルを配布できます。

# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign

これにより、リポジトリの manifest.json と dist/ 内のビルド済み成果物を使用して mailtrap-mcp.mcpb が作成されます。

使用方法

設定が完了したら、エージェントにメールの送信やテンプレートの管理を依頼できます。たとえば、次のように指示できます。

メール送信の操作：

• 「[email protected] に、件名を『Meeting Tomorrow』として、次回の会議について親しみやすいリマインダーを添えたメールを送信してください。」
• 「プロジェクトの更新について [email protected] にメールを送信し、[email protected] のチームを CC に追加してください。」
• 「ウェルカムテンプレート（uuid b81aabcd-1a1e-41cf-91b6-eca0254b3d96）を、変数 { name: 'Alex' } とともに [email protected] に送信してください。」
• 「[email protected] に、件名を『Test Template』としたサンドボックスメールを送信して、ウェルカムメールの見た目をプレビューしてください。」

メールログ（配信のデバッグ）：

• 「最近送信したメールのログを一覧表示してください。」
• 「[email protected] 宛てに送信したメールのログを表示してください。」
• 「配信状況を確認するために、ID が abc-123-uuid のメールログメッセージを取得してください。」

送信統計：

• 「2025年1月の送信統計を取得してください。」
• 「先月のドメイン別の配信率を表示してください。」
• 「2025-01-01 から 2025-01-31 までのカテゴリー別メール統計を教えてください。」

サンドボックスの操作：

• 「サンドボックスの受信トレイからすべてのメッセージを取得してください。」
• 「サンドボックスメッセージの最初のページを表示してください。」
• 「サンドボックスの受信トレイで、『test』を含むメッセージを検索してください。」
• 「ID が 5159037506 のサンドボックスメッセージの詳細を表示してください。」

テンプレートの操作：

• 「Mailtrap アカウントにあるすべてのメールテンプレートを一覧表示してください。」
• 「件名を『Welcome to our platform!』とした、『Welcome Email』という新しいメールテンプレートを作成してください。」
• 「ID が 12345 のテンプレートの件名を『Updated Welcome Message』に変更してください。」
• 「ID が 67890 のテンプレートを削除してください。」

送信ドメイン：

• 「送信ドメインを一覧表示してください。」
• 「ID が 3938 の送信ドメインを取得してください。」
• 「example.com の送信ドメインを作成してください。」
• 「送信ドメイン 3938 のクリックトラッキングを有効にしてください。」
• 「送信ドメイン 3938 を削除してください。」
• 「DNS の設定手順とともに、送信ドメイン 3938 を取得してください。」
• 「送信ドメイン 3938 の会社情報を表示してください。」
• 「ドメイン 3938 の会社情報を、Acme Inc、123 Main St、San Francisco、US、94105、https://acme.com に設定してください。」
• 「ドメイン 3938 の会社情報の都市を New York に変更してください。」

抑制：

• 「[email protected] の抑制情報を一覧表示してください。」
• 「ドメイン 3938 のトランザクションストリームで [email protected] を抑制してください。」
• 「抑制されているすべてのメールアドレスを表示してください。」
• 「[email protected] がメールを受信できないのはなぜですか？」
• 「[email protected] を抑制リストから削除してください。」

トラッキングのオプトアウト：

• 「ドメイン 3938 で [email protected] の開封とクリックのトラッキングを停止してください。」
• 「トラッキングをオプトアウトしたユーザーを一覧表示してください。」

連絡先とリスト：

• 「[email protected] をニュースレターの連絡先リストに追加してください。」
• 「すべての連絡先リストを表示してください。」
• 「連絡先の流入元を追跡するために、'signup_source' という連絡先フィールドを作成してください。」
• 「連絡先 [email protected] のプランを 'pro' に更新してください。」
• 「この CSV からオンボーディングリストに連絡先をインポートしてください。」
• 「ニュースレターリストのすべての連絡先をエクスポートしてください。」
• 「連絡先 [email protected] の 'trial_started' イベントを記録してください。」

Webhook：

• 「アカウントに設定されているすべての Webhook を一覧表示してください。」
• 「バウンスとスパムのイベントを https://example.com/hooks/mailtrap に送信する Webhook を作成してください。」
• 「Webhook 4821 を更新して、配信イベントも送信するようにしてください。」
• 「Webhook 4821 を削除してください。」

アカウントと請求：

• 「今月の請求対象の使用量を教えてください。」
• 「プランであと何通メールを送信できますか？」
• 「この Mailtrap アカウントにアクセスできるユーザーを一覧表示してください。」
• 「アカウントで利用できる権限リソースを表示してください。」

API トークン：

• 「アカウントのすべての API トークンを一覧表示してください。」
• 「ステージング環境用の新しい API トークンを作成してください。」
• 「ID が 1234 の API トークンをリセットしてください。」
• 「未使用の API トークン 1234 を削除してください。」

組織とサブアカウント：

• 「組織内のすべてのサブアカウントを一覧表示してください。」
• 「クライアントプロジェクト『Acme Corp』用の新しいサブアカウントを作成してください。」

利用可能なツール

send-email

Mailtrap を通じてトランザクションメールを送信します。相互排他的な 2 つのモード（インラインコンテンツ（subject + text／html）またはテンプレートベース（template_uuid））に対応しています。

パラメーター：

• from（任意）：{ email, name? } 形式の送信者（実行時にはメールアドレスのみの文字列も受け付けます）。指定しない場合は、DEFAULT_FROM_EMAIL が使用されます。
• to（任意）：{ email, name? } オブジェクト形式の受信者の配列（実行時にはメールアドレスのみの文字列、または配列ではない単一のアドレスも受け付けます）。cc または bcc を指定する場合は省略できます。to／cc／bcc のうち、少なくとも 1 つに受信者を含める必要があります。
• cc（任意）：{ email, name? } オブジェクト形式の CC 受信者の配列（実行時にはメールアドレスのみの文字列も受け付けます）。
• bcc（任意）：{ email, name? } オブジェクト形式の BCC 受信者の配列（実行時にはメールアドレスのみの文字列も受け付けます）。
• subject（条件付き）：メールの件名。インライン送信では必須です。template_uuid が設定されている場合は省略する必要があります。
• text（条件付き）：メール本文のテキスト。インライン送信では必須です（html と併せて、または html の代わりに指定します）。template_uuid が設定されている場合は省略する必要があります。
• html（条件付き）：メール本文の HTML 版。インライン送信では必須です（text と併せて、または 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

1 回の Mailtrap API 呼び出し（デフォルトの送信ストリーム）で、トランザクションメールを一括送信します。共通フィールドは base に、受信者ごとの上書き値は requests[] に指定します。各リクエストには、to、cc、bcc のいずれかを使って少なくとも 1 人の受信者を含める必要があります。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 のうち、少なくとも 1 つに受信者を含める必要があります。
  • 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 が raw message URL を公開している場合に、メッセージ本文（HTML とプレーンテキスト）も読み込んで表示できます。

パラメーター：

• message_id（必須）：メールログメッセージの UUID（送信レスポンスまたは list-email-logs から取得）。メッセージ ID を探すには list-email-logs を使用します。
• include_content（任意）：true の場合、raw_message_url が利用可能であれば raw EML を取得し、解析した HTML とプレーンテキストの本文セクションを追加します。show-sandbox-email-message と同様です。

get-sending-stats

指定した日付範囲のメール送信統計（配信率、バウンス率、開封率、クリック率、迷惑メール率）を取得します。ドメイン、カテゴリ、メールサービスプロバイダー、日付ごとに分類することもできます。エディターを離れずに配信率を確認できます。

パラメーター：

• start_date（必須）：統計の対象期間の開始日（YYYY-MM-DD）
• end_date（必須）：統計の対象期間の終了日（YYYY-MM-DD）
• breakdown（任意）：統計の分類方法。aggregated（デフォルト）、by_domain、by_category、by_email_service_provider、by_date を指定します
• sending_domain_ids（任意）：結果を指定した送信ドメイン ID に限定します（整数の配列）
• sending_streams（任意）：対象を transactional および／または bulk に限定します（文字列の配列）
• categories（任意）：対象を指定したメールカテゴリに限定します（文字列の配列）
• email_service_providers（任意）：対象を指定したプロバイダー（例：Google、Yahoo、Outlook）に限定します（文字列の配列）

create-template

Mailtrap アカウントに新しいメールテンプレートを作成します。

パラメーター：

• name（必須）：テンプレート名
• subject（必須）：メールの件名
• html（または text が必須）：テンプレートの HTML コンテンツ
• text（または html が必須）：テンプレートのプレーンテキスト版
• category（任意）：テンプレートのカテゴリ（既定値は "General"）

list-templates

ページトークン方式のページネーションを使用して、Mailtrap アカウントのメールテンプレート一覧を取得します。テンプレートがほかにもある場合、結果には次のページの token が示されます。各ページは新しい順の一覧に対するオフセットです。そのため、テンプレートを削除した後は次のトークンを続けて使用するのではなく、token 1 から再度一覧を取得してください。空のページには、テンプレートが残っている最後のページが示されます。

パラメーター：

• token（任意）：取得するページ番号（ページトークン方式のページネーション）。既定値は 1
• per_page（任意）：1ページあたりのテンプレート数。既定値は 50、最大値は 100 です。すべてのページで同じ値を指定してください

get-template

ID を指定して単一のメールテンプレートを取得します。件名、カテゴリ、HTML／テキスト本文も含まれます。

パラメーター：

• template_id（必須）：取得するテンプレートの ID

update-template

既存のメールテンプレートを更新します。

パラメーター：

• template_id（必須）：更新するテンプレートの ID
• name（任意）：テンプレートの新しい名前
• subject（任意）：メールの新しい件名
• html（任意）：テンプレートの新しい HTML コンテンツ
• text（任意）：テンプレートの新しいプレーンテキスト版
• category（任意）：テンプレートの新しいカテゴリ

メモ

update-template を呼び出して更新するには、更新可能なフィールド（name、subject、html、text、category）のうち少なくとも 1 つを指定する必要があります。

delete-template

既存のメールテンプレートを削除します。

パラメーター：

• template_id（必須）：削除するテンプレートの ID

send-sandbox-email

開発やテストの目的で、Mailtrap のテスト受信トレイにメールを送信します。実際の受信者にメールを送らずにメールテンプレートをテストするのに最適です。send-email と同じ 2 つのモード（インラインコンテンツまたはテンプレートベース（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 の少なくとも 1 つに受信者を指定する必要があります。
• cc（任意）：{ email, name? } オブジェクト形式の CC 受信者の配列（実行時にはメールアドレスのみの文字列も受け付けます）。
• bcc（任意）：{ email, name? } オブジェクト形式の BCC 受信者の配列（実行時にはメールアドレスのみの文字列も受け付けます）。
• 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

実際の受信者には配信せず、1 回の API 呼び出しで Mailtrap のテスト用受信トレイにメールをまとめて送信します。batch-send-transactional-email と同じ base + requests[] の形式、検証ルール、インラインとテンプレートのルールを使用します。異なるのは、このツールがサンドボックスエンドポイント経由で単一のテスト用受信トレイに送信する点です。

パラメーター：

• sandbox_id（任意）：Mailtrap のサンドボックス（テスト用受信トレイ）IDです。MAILTRAP_SANDBOX_ID が設定されていない場合は必須です。特定のサンドボックスを指定するには、呼び出しごとに渡してください。
• base（任意）、requests（必須）：上記の batch-send-transactional-email を参照してください。

メモ

ほとんどのサンドボックスツールでは sandbox_id を指定します（または MAILTRAP_SANDBOX_ID にフォールバックします。旧環境変数 MAILTRAP_TEST_INBOX_ID も引き続き使用できます）。send-sandbox-email、get-sandbox-messages、show-sandbox-email-message では旧パラメーター test_inbox_id も指定できます。get-sandbox-inbox、update-sandbox-inbox、delete-sandbox-inbox、clean-sandbox-inbox では、旧パラメーター inbox_id を使用して sandbox_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（任意）：メッセージを絞り込む検索クエリです

メモ

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 です

メモ

まず get-sandbox-messages を使ってメッセージ ID を取得し、その後このツールで全内容を取得してください。

get-sandbox-project

サンドボックスプロジェクトを ID で取得します。受信トレイとメール件数も含まれます。

パラメーター：

• project_id（必須）：取得するプロジェクトの ID です

update-sandbox-project

既存のサンドボックスプロジェクトの名前を変更します。

パラメーター：

• project_id（必須）：更新するプロジェクトの ID です
• name（必須）：プロジェクトの新しい名前です（2～100 文字）

list-sandboxes

API トークンからアクセスできるすべてのプロジェクトのサンドボックスを一覧表示します。

パラメーター：

• パラメーターは不要です

mark-sandbox-as-read

サンドボックス内のすべてのメッセージを既読にします。

パラメーター：

• sandbox_id（必須）：操作対象のサンドボックスの ID です

reset-sandbox-credentials

サンドボックスの SMTP 認証情報をリセットします。新しいユーザー名とパスワードを返します。

パラメーター：

• sandbox_id（必須）：操作対象のサンドボックスの ID です

enable-sandbox-email-address

サンドボックスのメール受信用アドレスを有効にします（SMTP 経由でメッセージをサンドボックスに配信する Mailtrap アドレスを有効にします）。

パラメーター：

• sandbox_id（必須）：操作対象のサンドボックスの ID です

reset-sandbox-email-address

サンドボックスの新しいメール受信用アドレスを生成します。

パラメーター：

• sandbox_id（必須）：操作対象のサンドボックスの ID です

forward-sandbox-message

サンドボックスのメッセージを外部のメールアドレスに転送します。月ごとの転送上限にカウントされます。

パラメーター：

• sandbox_id（省略可）：サンドボックス ID。設定されていない場合は MAILTRAP_SANDBOX_ID を使用します。
• message_id（必須）：転送するサンドボックスメッセージの ID
• email（必須）：メッセージの転送先メールアドレス

update-sandbox-message

サンドボックスのメッセージを既読または未読にします。

パラメーター：

• sandbox_id（省略可）：サンドボックス ID。設定されていない場合は MAILTRAP_SANDBOX_ID を使用します。
• message_id（必須）：更新するサンドボックスメッセージの ID
• is_read（必須）：true は既読、false は未読にします

delete-sandbox-message

サンドボックスのメッセージを 1 件削除します。

パラメーター：

• 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 ソース（CID リンクの書き換えなど、Mailtrap 側の変換が行われる前の 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（任意）：このドメインを受信インボックスのキャッチオールとして設定できるようにします

sending_domain_id以外に、少なくとも1つの設定を指定する必要があります。

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のすべてのフィールド（すべて任意）。少なくとも1つ指定する必要があります。省略したフィールドは変更されません。

list-suppressions

抑制リスト（ハードバウンス、スパムの苦情、配信停止、手動インポート）を一覧表示または検索します。1回の呼び出しにつき最大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

開封およびクリックのトラッキング対象から除外されたメールアドレスを一覧表示します。1 回の呼び出しで最大 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

アカウントに設定されているすべてのウェブフックを一覧表示します。ウェブフックの全レコードを JSON 形式で返します。

パラメーター：

• パラメーターは不要です

get-webhook

ID を指定して単一のウェブフックを取得します。ウェブフックの全レコードを JSON 形式で返します。注：signing_secret はここでは返されず、create-webhook のレスポンスでのみ取得できます。

パラメーター：

• webhook_id（必須）：取得するウェブフックの ID

create-webhook

ウェブフックを作成します。レスポンスには、ウェブフックのペイロード署名を検証するための signing_secret が含まれます。このシークレットが返されるのは作成時のみなので、今すぐ保存してください。紛失した場合は、ウェブフックを再作成してください。

パラメーター：

• url（必須）：Mailtrap がウェブフックイベントを POST する 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 のみ）：このウェブフックの対象とする送信ドメイン ID
• inbound_inbox_id（任意、inbound_receiving のみ）：ウェブフックに関連付ける受信インボックスの ID。省略すると、アカウント内のすべてのインボックスに適用されます

update-webhook

ウェブフックの変更可能なフィールドを更新します。webhook_type、sending_stream、domain_id は作成後に変更できません。これらを変更する必要がある場合は、ウェブフックを再作成してください。

パラメーター：

• webhook_id（必須）：更新するウェブフックの ID
• url（任意）：新しいウェブフック URL
• active（任意、ブール値）：ウェブフックを有効または無効にします
• payload_format（任意）："json" または "jsonlines"
• event_types（任意、email_sending のみ）：delivery、soft_bounce、bounce、suspension、unsubscribe、open、spam_complaint、click、reject の配列
• inbound_inbox_id（任意、inbound_receiving のみ）：ウェブフックに関連付ける受信インボックスの ID

delete-webhook

ID を指定してウェブフックを完全に削除します。削除したウェブフックのレコードを返します。

パラメーター：

• webhook_id（必須）：削除するウェブフックの ID

get-contact

ID またはメールアドレスを指定して連絡先を取得します。連絡先の全レコード（リストへの登録状況、ステータス、カスタムフィールド）を返します。

パラメーター：

• contact_identifier（必須）：連絡先 ID またはメールアドレス

create-contact

新しい連絡先を作成します。

パラメーター：

• email（必須）：メールアドレス
• fields（任意）：マージタグ（例：first_name）をキーとするカスタムフィールドの値。文字列、数値、またはブール値を指定します
• list_ids（任意）：この連絡先を登録する連絡先リストの ID
• unsubscribed（任意、ブール値）：unsubscribed ステータスで連絡先を作成します

update-contact

ID またはメールアドレスで識別される既存の連絡先を更新します。list_ids は連絡先の所属リストをすべて置き換えます。list_ids_included／list_ids_excluded は、ほかのリストへの所属を維持したまま、リストを追加／削除します。

パラメーター：

• contact_identifier（必須）：連絡先 ID またはメールアドレス
• email（任意）：新しいメールアドレス
• fields（任意）：マージタグをキーとするカスタムフィールド値
• list_ids（任意）：所属リストをこのリストで完全に置き換えます
• list_ids_included（任意）：追加するリスト ID（追加のみ）
• list_ids_excluded（任意）：削除するリスト ID
• unsubscribed（任意、ブール値）：unsubscribed（true）または subscribed（false）に設定します

delete-contact

ID またはメールアドレスで連絡先を完全に削除します。API が削除済みの連絡先レコードを返した場合はそのレコードを返し、返さない場合は確認用のペイロードを返します。

パラメーター：

• contact_identifier（必須）：連絡先 ID またはメールアドレス

create-contact-event

ID またはメールアドレスで指定した連絡先にイベントを記録します。連絡先リストのオートメーションを起動するために使用します。

パラメーター：

• contact_identifier（必須）：連絡先 ID またはメールアドレス
• name（必須）：イベント名（オートメーションのトリガーと一致します）
• params（必須）：任意のキーと値のペアを含むオブジェクト。値は文字列、数値、ブール値、または null を指定できます

list-contact-lists

アカウントのすべての連絡先リストを一覧表示します。

パラメーター：

• search（任意）：連絡先リストを名前で絞り込みます（大文字と小文字を区別しない一致）。例：news

get-contact-list

ID で連絡先リストを取得します。

パラメーター：

• list_id（必須）：取得する連絡先リストの ID

create-contact-list

新しい連絡先リストを作成します。

パラメーター：

• name（必須）：新しいリストの名前

update-contact-list

既存の連絡先リストの名前を変更します。

パラメーター：

• list_id（必須）：連絡先リストの ID
• name（必須）：リストの新しい名前

delete-contact-list

ID で連絡先リストを完全に削除します。

パラメーター：

• list_id（必須）：削除する連絡先リストの ID

list-contact-fields

アカウントのすべての連絡先フィールド定義を一覧表示します。

パラメーター：

• パラメーターは不要です

get-contact-field

ID で連絡先フィールド定義を取得します。

パラメーター：

• field_id（必須）：連絡先フィールドの ID

create-contact-field

新しい連絡先フィールド定義を作成します。merge_tag はアカウント内で一意である必要があり、テンプレート変数のプレースホルダー名として使用されます。

パラメーター：

• name（必須）：表示名（例：「名」）
• merge_tag（必須）：一意のプレースホルダー名（例：first_name）
• data_type（必須）：text、number、boolean、date のいずれか

update-contact-field

連絡先フィールド定義を更新します。name、merge_tag、data_type は任意の組み合わせで変更できます。

パラメーター：

• field_id（必須）：連絡先フィールドの ID
• name（任意）：新しい表示名
• merge_tag（任意）：新しいマージタグ（引き続き一意である必要があります）
• data_type（任意）：text、number、boolean、date のいずれか

delete-contact-field

ID で連絡先フィールド定義を完全に削除します。

パラメーター：

• field_id（必須）：削除する連絡先フィールドの ID

create-contact-import

連絡先を一括インポートします。インポートジョブのレコードを返します。get-contact-import でステータスを確認してください。

パラメーター：

• contacts（必須）：連絡先エントリーの配列。各エントリーには以下が必要です：
  • email（必須）：連絡先のメールアドレス
  • fields（任意）：マージタグをキーとするカスタムフィールド値（文字列または数値）
  • list_ids_included（任意）：連絡先を追加するリスト ID
  • list_ids_excluded（任意）：連絡先を削除するリスト ID

get-contact-import

作成数、更新数、上限超過数とともに、連絡先インポートジョブのステータス（created／started／finished／failed）を取得します。

パラメーター：

• import_id（必須）：連絡先インポートジョブの ID

create-contact-export

AND 条件で組み合わせた一連のフィルターに一致する連絡先をエクスポートします。エクスポートジョブのレコードを返します。status が finished になった後、get-contact-export でステータスをポーリングすると、ダウンロード URL を取得できます。

パラメーター：

• filters（必須）：フィルターオブジェクトの配列です。各オブジェクトには以下が含まれます。
  • name（必須）：フィルター対象のフィールド（list_id、subscription_status、email など）
  • operator（必須）：equal、not_equal、contains、not_contains、is_empty、is_not_empty のいずれか
  • value（必須）：比較する値（文字列、数値、ブール値、または配列）

get-contact-export

連絡先エクスポートジョブのステータスを取得します。status が finished になると、url フィールドに CSV のダウンロードリンクが格納されます。

パラメーター：

• export_id（必須）：連絡先エクスポートジョブの ID

list-email-campaigns

アカウントのメールキャンペーンを新しい順に一覧表示します。ページトークンによるページネーションに対応しています。search を指定すると、名前で絞り込めます。

パラメーター：

• token（任意）：取得するページ番号（ページトークンによるページネーション）。デフォルトは 1 です
• per_page（任意）：1 ページあたりのキャンペーン数。デフォルトは 50、最大は 100 です
• search（任意）：キャンペーンを名前で絞り込みます（大文字と小文字を区別しない部分一致）

get-email-campaign

ID を指定してメールキャンペーンを取得します。

パラメーター：

• email_campaign_id（必須）：メールキャンペーンの ID

create-email-campaign

新しいメールキャンペーンを作成します。キャンペーンは常に draft 状態で作成されます。スケジュール設定と開始には、それぞれ別のツール（schedule-email-campaign、start-email-campaign）を使用します。

パラメーター：

• name（必須）：キャンペーン名
• domain_id（必須）：キャンペーンに使用する、確認済みの送信ドメインの ID。Sending Domains エンドポイントから取得できます
• from_local_part（必須）：From アドレスのローカルパート（@ より前の部分）
• template_attributes（必須）：インラインのメールテンプレート。以下が含まれます。
  • subject（必須）：メールの件名（最大 255 文字）。Hi {{first_name}} のようなマージタグに対応しています
  • body_html（任意）：HTML 本文（デザイン）。キャンペーンのスケジュール設定または開始前に必須です。href に __unsubscribe_url__ プレースホルダーを含むアンカーを使用して、配信停止リンクを含めてください
  • body_text（任意）：メール本文のプレーンテキスト版
  • merge_tags（任意）：件名または本文で参照するマージタグの名前（タグ記号なし）。例：["first_name"]
• from_display_name（任意）：From ヘッダーに表示される名前
• reply_to（任意）：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

1 つのアカウントアクセス権に対する権限を一括作成、更新、または削除します。既存の (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 を指定して受信フォルダーを 1 つ取得します。フォルダーの完全なレコードを 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 を指定して受信トレイを 1 つ取得します。受信トレイの完全なレコードを JSON として返します。

パラメーター：

• folder_id（必須）：受信フォルダーの ID
• inbox_id（必須）：受信トレイの ID

create-inbound-inbox

フォルダー内に新しい受信トレイを作成します。

パラメーター：

• folder_id（必須）：受信フォルダーの ID
• name（必須）：受信トレイ名
• domain_id（任意）：カスタム送信ドメイン（すべてのメールを受信する受信トレイ）に関連付けます。Mailtrap ホストの受信トレイを使用する場合は省略します

update-inbound-inbox

受信トレイの名前を変更します。

パラメーター：

• folder_id（必須）：受信フォルダーの ID
• inbox_id（必須）：受信トレイの ID
• name（必須）：新しい受信トレイ名

delete-inbound-inbox

受信トレイを完全に削除します。

パラメーター：

• folder_id（必須）：受信フォルダーの ID
• inbox_id（必須）：受信トレイの ID

list-inbound-messages

受信トレイに届いたメッセージを一覧表示します（カーソルによるページネーション）。結果がさらにある場合は、次のページへのヒントを含む整形済みの要約を返します。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• last_id（任意）：前回のレスポンスの last_id に含まれるページネーションカーソル

get-inbound-message

単一の受信メッセージを、本文全体と添付ファイルのダウンロード URL とともに取得します。メッセージレコード全体を JSON で返します。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• message_id（必須）：メッセージの ID

delete-inbound-message

受信メッセージを完全に削除します。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• message_id（必須）：メッセージの ID

reply-to-inbound-message

受信メッセージに返信します（元の送信者に送信されます）。実際のメールを送信します。宛先には、メールアドレスのみの文字列または { email, name? } を指定できます。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• message_id（必須）：返信するメッセージの ID
• text / html（少なくとも一方を推奨）：返信本文
• from（任意）：送信者。Mailtrap がホストする受信トレイでは拒否されます。カスタムドメインの受信トレイでは必須です
• cc / bcc / reply_to（任意）：追加の宛先
• category（任意）：メッセージのカテゴリ
• attachments（任意）：{ content (base64), filename, type?, disposition?, content_id? } の配列
• headers / custom_variables（任意）：文字列値のオブジェクト

reply-all-to-inbound-message

受信メッセージに返信し、元のメッセージのほかの宛先も含めます。実際のメールを送信します。パラメーターは reply-to-inbound-message と同じです。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• message_id（必須）：返信するメッセージの ID
• さらに、reply-to-inbound-message と同じ任意の送信フィールドを指定します

forward-inbound-message

受信メッセージを新しい宛先に転送します。実際のメールを送信します。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• message_id（必須）：転送するメッセージの ID
• to（必須）：1 件以上の宛先（メールアドレスのみの文字列または { email, name? }、あるいは配列）
• さらに、reply-to-inbound-message と同じ任意の送信フィールドを指定します

list-inbound-threads

受信トレイの会話スレッドを一覧表示します（カーソルによるページネーション）。必要に応じて search で絞り込めます。結果がさらにある場合は、次のページへのヒントを含む整形済みの要約を返します。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• last_id（任意）：前回のレスポンスの last_id に含まれるページネーションカーソル
• search（任意）：スレッドの件名と、そのメッセージの差出人／宛先／CC／BCC アドレスに対して、大文字と小文字を区別せずに照合するテキスト。ページネーション時にも同じ値を指定します

get-inbound-thread

単一の受信スレッドを、メッセージを埋め込んだ状態で（古い順に）取得します。スレッドレコード全体を JSON で返します。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• thread_id（必須）：スレッドの ID

delete-inbound-thread

受信スレッドを完全に削除します。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• thread_id（必須）：スレッドの ID

list-inbound-forward-rules

受信トレイの転送ルールを一覧表示します。整形済みの要約を返します。

パラメーター：

• inbox_id（必須）：受信トレイの ID

get-inbound-forward-rule

ID を指定して単一の受信転送ルールを取得します。条件と転送先を含むルールレコード全体を JSON で返します。

パラメーター：

• inbox_id（必須）：受信トレイの ID
• forward_rule_id（必須）：転送ルールの ID

create-inbound-forward-rule

受信インボックスに転送ルールを作成します。すべての条件に一致する受信メッセージは、ルールの転送先に転送されます。

パラメーター：

• inbox_id（必須）：インボックスの ID
• name（必須）：ルール名。インボックス内で一意である必要があります
• conditions（任意）：{ match_type, operator, value?, header_key? } の配列。match_type は sender、recipient、header のいずれかです。operator は equal、not_equal、contains、starts_with、ends_with、empty、not_empty のいずれかです（empty／not_empty は header でのみ使用でき、value は指定しません）。header では header_key が必須です。すべてのメッセージに一致させるには、省略するか [] を渡します
• destinations（任意）：一致したメッセージの転送先を指定する { email } の配列

update-inbound-forward-rule

受信転送ルールを更新します。指定したフィールドのみが変更されます。conditions または destinations の配列を指定すると、既存のセット全体が置き換えられます。

パラメーター：

• inbox_id（必須）：インボックスの ID
• forward_rule_id（必須）：転送ルールの ID
• name（任意）：新しいルール名
• conditions（任意）：置き換える条件セット（作成時と同じ形式）。[] を指定するとすべての条件が削除され、ルールはすべてのメッセージに一致します
• destinations（任意）：置き換える転送先セット。[] を指定するとすべての転送先が削除されます

delete-inbound-forward-rule

受信転送ルールを完全に削除します。

パラメーター：

• inbox_id（必須）：インボックスの ID
• forward_rule_id（必須）：転送ルールの ID

開発

1. リポジトリをクローンします：

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

2. 依存関係をインストールします：

npm install

Claude Desktop または Cursor での設定

ヒント

設定ファイルの場所については、セットアップセクションを参照してください。

以下の設定を追加します：

{
  "mcpServers": {
    "mailtrap": {
      "command": "node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "[email protected]",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
      }
    }
  }
}

Node.js の管理に asdf を使用している場合は、実行ファイルの絶対パスを指定してください：

（Mac の例）

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

VS Code

ヒント

設定ファイルの場所については、セットアップセクションを参照してください。

{
  "mcp": {
    "servers": {
      "mailtrap": {
        "command": "node",
        "args": ["/path/to/mailtrap-mcp/dist/index.js"],
        "env": {
          "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
          "DEFAULT_FROM_EMAIL": "[email protected]",
          "MAILTRAP_ACCOUNT_ID": "your_account_id",
          "MAILTRAP_SANDBOX_ID": "your_sandbox_id"
        }
      }
    }
  }
}

テスト

実際の Mailtrap に対してツールを実行する

実際の Mailtrap アカウントに対してツールをエンドツーエンドで実行する方法は 2 つあります。対話的に試せるブラウザー UI の MCP Inspector と、シェルから 1 回限りの呼び出しを行う CLI モードです。

どちらの場合も、まずバンドルをビルドする必要があります：

npm run build

また、シェルで MAILTRAP_API_TOKEN と MAILTRAP_ACCOUNT_ID をエクスポートしてください（mcp:cli スクリプトは、起動するサーバーに両方を渡します）。

ブラウザー UI

npm run dev

Inspector に http://localhost:6274 のような URL が表示されます。URL を開き、Tools タブに切り替えてツール（例：get-template）を選択し、パラメーターを JSON 形式で入力して Run をクリックします。Mailtrap の応答が下のパネルに表示されます。

CLI

UI を使わずに 1 回限りの呼び出しを行うには、npm run mcp:cli を使用します。Inspector の CLI フラグは -- の後に渡してください。そうすると npm がそのまま転送します：

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

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

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg [email protected]

MCPB サーバーの実行

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

# Or use the provided binary
mailtrap-mcpb-server

ヒント

MCP Inspector を使った開発について：

npm run dev:mcpb

エラー処理

このサーバーでは、MCP の規約に沿った構造化エラー処理を使用しています：

• VALIDATION_ERROR：入力の検証エラー
• CONFIGURATION_ERROR：設定の欠落または無効な設定
• EXECUTION_ERROR：実行時エラー
• TIMEOUT：操作のタイムアウト（デフォルトは 30 秒）

エラーには対処可能なメッセージが含まれ、構造化された形式でログに記録されます。

セキュリティ

• Zod スキーマを使用した入力検証
• 環境変数を安全に処理
• 操作に対するタイムアウト保護（30 秒）
• エラー出力内の機密情報をサニタイズ

ロギング

INFO、WARN、ERROR、DEBUG のレベルを使用した構造化 JSON ログです。

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_id を指定するか（またはメッセージの送信／一覧表示／表示ツールでは従来の test_inbox_id を指定）、環境変数 MAILTRAP_SANDBOX_ID を設定してください
3. タイムアウトエラー：ネットワーク接続と Mailtrap API のステータスを確認してください
4. 検証エラー：必須フィールドがすべて指定されていることを確認してください

貢献

バグ報告やプルリクエストはGitHubで歓迎しています。このプロジェクトは、誰もが安心して協力できる場を目指しており、コントリビューターには行動規範の遵守をお願いしています。

ライセンス

このパッケージは、MIT ライセンスの条件のもとでオープンソースとして公開されています。

行動規範

Mailtrap プロジェクトのコードベース、課題トラッカー、チャットルーム、メーリングリストに関わるすべての人は、行動規範に従うことが求められます。