sales-mailgun

Mailgun プラットフォームのヘルプ

REST API や SMTP リレーを使ったトランザクションメールの送信から、受信メールのルーティング、テンプレート、メーリングリスト、ドメイン、ルート、Webhook、メトリクス、Mailgun Optimize まで、Mailgun（Sinch）プラットフォームに関する質問に対応します。Mailgun は、Ev Kontsevoy と Taylor Wakefield が 2010 年に設立した、開発者向けのトランザクションメール API サービスです。Rackspace（2012 年）、Thoma Bravo（2019 年）、Sinch（2021 年）に買収されました。Josh Odom は、Sinch の開発者・メール部門のプレジデントです。

ステップ 1 — 背景情報を確認する

references/learnings.md が存在する場合は、蓄積された知識を確認するため、最初に読みます。

ユーザーに次の質問をします。

1. Mailgun のどの分野についてサポートが必要ですか？

   • A) Email API — REST API（POST /v3/{domain}/messages）または SMTP リレーを使ったトランザクションメールの送信
   • B) SMTP リレー — 従来型の SMTP 統合（ポート 25／465／587）
   • C) 受信メールのルーティング — カスタムルール（regex／JSONPath）による受信メールの処理と解析、添付ファイルを含む Webhook 配信
   • D) テンプレート — Handlebars のような変数を使った、アカウントレベルおよびドメインレベルの保存済みテンプレート
   • E) メーリングリスト — プログラムによるリスト管理、メンバーの CRUD
   • F) Domains API — ドメイン管理、DNS 検証、DKIM／SPF の設定
   • G) ルート — 受信メールを HTTP エンドポイントまたはメールアドレスに転送する、または 3 日間保存する機能
   • H) Webhook — イベント通知（accepted、delivered、opened、clicked、permanent_fail、temporary_fail、complained、unsubscribed）
   • I) Metrics API — 配信到達性、エンゲージメント、送信状況の健全性に関する分析
   • J) Mailgun Optimize — 受信トレイへの配置を確認するシードテスト、メールアドレスの検証（単件＋一括 CSV）、送信者レピュテーションの監視、ブロックリストのアラート
   • K) タグ — 送信の分類と追跡
   • L) アカウント／請求 — プラン、料金、API キー、カスタムのメッセージ上限
   • M) その他 — 内容を説明してください

2. あなたの役割は何ですか？

   • A) 開発者／エンジニア
   • B) DevOps／インフラ担当者
   • C) 管理者／アカウント所有者
   • D) 創業者／個人事業主
   • E) 代理店／フリーランス
   • F) その他

3. 何を実現しようとしていますか？（具体的な目標や質問を説明してください）

ユーザーのリクエストにこれらの背景情報の大部分がすでに含まれている場合は、該当するステップに直接進んでください。 妥当な前提を明示したうえで、できる限り適切な回答から始めます。その後、最後に最も重要な確認質問を 1〜2 個だけ尋ねます。必要な背景情報がすべてそろうまで回答を保留しないでください。

注：ユーザーが専門スキルを必要としている場合は、そのスキルのほうが適している理由を簡潔に説明して案内してください。

ステップ 2 — 案内するか、直接回答する

リクエストが専門スキルに該当する場合は、次のように案内します。

• 一般的なメール配信到達性の戦略／ベストプラクティス -> /sales-deliverability
• プラットフォーム横断のメールマーケティング戦略 -> /sales-email-marketing
• メールの開封／クリック追跡の戦略 -> /sales-email-tracking
• SendGrid 固有の質問 -> /sales-sendgrid
• Postmark 固有の質問 -> /sales-postmark
• Zapier またはミドルウェアを使った Mailgun と他のツールの連携 -> /sales-integration
• ファネル戦略／コンバージョン最適化 -> /sales-funnel

それ以外の場合は、以下のリファレンスにあるプラットフォームの知識に基づいて直接回答します。

ステップ 3 — Mailgun プラットフォームのリファレンス

詳細なモジュールのドキュメント、料金、連携、データモデルについては、references/platform-guide.md を読んでください。

プラットフォームガイドの詳細を参照する必要はもうありません。ユーザー固有の状況に注力してください。

ステップ 4 — 実行可能なガイダンス

ユーザーの具体的な質問に基づいて、次のように案内します。

1. API を使ったトランザクションメールの送信：

   1. Mailgun アカウントに登録し、ダッシュボードから API キーをコピーします
   2. 送信ドメインを追加して検証します。必要な DNS レコード（include:mailgun.org を含む MX、SPF TXT、DKIM CNAME/TXT）を追加します
   3. DNS の伝播を待ち、Mailgun UI または GET /v3/domains/{domain} を使ってドメインを検証します
   4. 最初のメールを送信します。Basic Auth（api:YOUR_API_KEY）を使い、from、to、subject、text／html フィールドを渡して、POST /v3/{domain}/messages を実行します
   5. 必要に応じて、本番環境用の Domain Sending Key を作成します。セキュリティのため、キーの使用先が /messages エンドポイントのみに制限されます
   6. タグ（o:tag）とカスタム変数（v:my-var）を追加して、追跡や分析に利用します
   7. Events API（GET /v3/{domain}/events）で配信状況を監視するか、リアルタイム通知用の Webhook を設定します

2. 受信メールのルーティング設定：

   1. 受信ドメインに、Mailgun の受信サーバーを指す MX レコードを追加します
   2. Mailgun UI でドメインを検証します
   3. API（POST /v3/routes）または UI からルートを作成し、マッチ式とアクションを定義します
   4. マッチ式の例：match_recipient("[email protected]")、match_header("subject", ".*order.*")、catch_all()
   5. アクションの例：forward("https://yourapp.com/webhook")、forward("[email protected]")、store(notify="https://yourapp.com/notify")
   6. 解析済みメールを multipart/form-data（送信者、件名、本文、添付ファイル）で受信する Webhook エンドポイントを実装します
   7. 高度なルーティングロジックには、正規表現または JSONPath によるカスタム解析ルールを使用します

3. ドメインレベルのテンプレート設定：

   1. 名前、説明、初期バージョンのコンテンツを指定して、テンプレートを作成します：POST /v3/{domain}/templates
   2. テンプレート内では、Handlebars に似た変数を使用します：{{first_name}}、{{order_number}}、{{items}}
   3. A/B テストや反復改善用に、追加のバージョンを作成します
   4. テンプレートを使って送信するには、テンプレート名を指定した template パラメーターと、JSON データオブジェクトを含む h:X-Mailgun-Variables を指定します
   5. Templates API を使って、テンプレートの一覧表示、更新、削除をプログラムから行います

4. 配信状況追跡用の Webhook 設定：

   1. イベントタイプ（例：delivered、opened、permanent_fail）とエンドポイント URL を指定して、Webhook を作成します：POST /v3/domains/{domain}/webhooks
   2. JSON ペイロードを受信する Webhook エンドポイントを実装します
   3. API キーを使って Webhook の署名を検証します。Mailgun はセキュリティのため、すべての Webhook に署名します
   4. バッチ配信を処理します。1 回の POST で複数のイベントがエンドポイントに届く場合があります
   5. すぐに 200 ステータスコードを返します。負荷の高い処理はバックグラウンドキューに移します
   6. すべてを把握できるよう、8 種類すべてのイベントタイプ（accepted、delivered、opened、clicked、permanent_fail、temporary_fail、complained、unsubscribed）に Webhook を設定します

5. 配信到達率向上のための Mailgun Optimize の利用：

   1. Optimize アドオンプラン（Pilot は月額 $49、Starter は月額 $99）に登録します。これは Send プランとは別です
   2. 受信トレイへの配置テストを実施します。Mailgun のシードリストにテストメールを送信し、プロバイダーごとの受信トレイと迷惑メールの結果を確認します
   3. 送信前にメールアドレスを検証します：GET /v4/address/[email protected]。リスクレベル（deliverable、undeliverable、risky、unknown）が返されます
   4. CSV をアップロードして一括検証し、リストをクリーニングします
   5. Optimize ダッシュボードで送信者レピュテーションとブロックリストのステータスを監視します
   6. IP またはドメインがブロックリストに登録された際、すぐに通知を受け取れるよう、ブロックリストアラートを設定します

注意点

調査に基づくベストエフォートの情報です。特に、プランによって利用が制限される機能や、連携に関する注意点は古くなっている可能性があるため、確認してください。

1. 米国とEUのリージョンでは正しいベースURLが必要で、ドメイン作成後にリージョンを変更することはできません。 米国のドメインでは https://api.mailgun.net/v3/、EUのドメインでは https://api.eu.mailgun.net/v3/ を使用します。ドメインをあるリージョンで作成すると、もう一方のリージョンに移動できません。GDPRへの準拠のためEUでのデータ保管が必要な場合は、最初からEUリージョンでドメインを作成してください。誤ったベースURLを使用すると、原因の特定が難しい認証エラーが返されることがあります。
2. Mailgun Optimizeは別途有料のアドオン（月額49ドル以上）であり、どのSendプランにも含まれていません。 受信トレイへの到達率を調べるシードテスト、メールアドレスの検証、送信者レピュテーションの監視、ブロックリストのアラートを利用するには、Sendプランに加えてOptimizeのサブスクリプションが必要です。これらの機能がFoundationプランやScaleプランに含まれていると思い込まないでください。含まれていません。
3. ドメイン送信キーでできるのはメッセージの送信のみです。ドメイン、ルート、Webhookの管理はできません。 アプリケーションでルートの作成、ドメインの管理、Webhookの設定が必要な場合は、メインのAPIキーを使用する必要があります。ドメイン送信キーは、セキュリティ上の分離のため、/messages エンドポイントに制限されています。その他のAPI呼び出しにドメイン送信キーを使用すると、401エラーが返されます。
4. 専用IPは1つにつき月額59ドルで、ウォームアップが必要です。含まれていると思い込まないでください。 専用IPは、ScaleプランとEnterpriseプランで利用できるアドオンです。新しい専用IPにはレピュテーションがないため、徐々にウォームアップする必要があります（少量から始め、2～4週間かけて増やしてください）。ウォームアップ前の専用IPから大量に送信すると、配信到達率が低下します。送信量が少ない場合は、Mailgunの共有IPプールのほうが配信結果が良いことがよくあります。
5. Freeプランは1日あたり100通であり、月あたりではありません。テストには非常に制限があります。 開発やテストのワークフローでは、想像以上に厳しい制限です。十分な規模で一斉送信、Webhookの処理、テンプレートのレンダリングをテストするには、少なくともFoundationプラン（月額35ドル、月あたり50,000通）が必要です。1日の上限はUTCの午前0時にリセットされます。

• 継続的な改善：ここに記載されていない情報を見つけた場合は、今日の日付を付けて references/learnings.md に追記してください。

ステップ5 — 関連スキル

• /sales-deliverability — プラットフォームを横断したメール配信到達率 — SPF/DKIM/DMARC、ウォームアップ、受信トレイへの到達率
• /sales-email-marketing — 各種ツールを活用したオプトインメールマーケティング戦略
• /sales-email-tracking — メールエンゲージメントの追跡戦略
• /sales-integration — Webhook/Zapierを介したMailgunとCRM、Slack、その他のツールとの連携
• /sales-sendgrid — SendGridプラットフォームのサポート — Mailgunの主要な競合サービス
• /sales-postmark — Postmarkプラットフォームのサポート — Mailgunの主要な競合サービス
• /sales-customerio — Customer.ioプラットフォームのサポート — トランザクションメールにMailgunに似たAPIを使用
• /sales-do — どのスキルを使えばよいかわからない場合に使用します。ルーターがあらゆる営業目標に適したスキルを選びます。インストール：npx skills add sales-skills/sales --skill sales-do

例

例1：Node.js アプリで REST API を使ってトランザクションメールを送信する

ユーザーの発言：「Mailgun を使って、Node.js アプリからパスワードリセットメールと注文確認メールを送信したいです。」 スキルの内容：

1. Mailgun アカウントの作成方法を案内し、ダッシュボードから API キーをコピーします
2. 送信ドメインの追加と認証の手順を説明します。MX、SPF（include:mailgun.org）、DKIM の DNS レコードを追加します
3. mailgun.js SDK の使用方法を示します。API キーとドメインを使って初期化し、from、to、subject、html／text を指定して mg.messages.create() を呼び出します
4. Handlebars の変数を使って、ドメイン単位のテンプレートを2つ作成します。1つはパスワードリセット用（{{reset_url}}、{{expiry_minutes}}）、もう1つは注文確認用（{{order_number}}、{{items}}、{{total}}）です
5. 本番環境では、キーの権限を送信のみに制限するため、Domain Sending Key の作成を推奨します
6. 配信状況を監視してアラートを発生させるため、delivered、permanent_fail、complained イベントの Webhook を設定します 結果：テンプレート、権限を限定した API キー、適切な DNS 認証、配信状況の監視を備えた、本番環境対応のトランザクションメールを利用できます

例2：サポートシステム向けの受信メールルーティングを設定する

ユーザーの発言：「[email protected] で顧客からの返信メールを受信し、チケット管理システムの Webhook に転送したいです。」 スキルの内容：

1. ourdomain.com の MX レコードを追加し、Mailgun の受信サーバーを指定する方法を案内します
2. Mailgun の UI でドメインを認証します
3. API を使って、アクション forward("https://app.ourdomain.com/api/tickets/inbound") を指定したルート match_recipient("[email protected]") を作成します
4. Webhook ペイロードの形式を説明します。送信者、件名、stripped-text（引用された返信を含まない本文）、ファイルアップロードとしての添付ファイルが含まれます
5. 該当するルートがない受信メールを3日間保存する catch_all() のフォールバックルート（store(notify="https://app.ourdomain.com/api/catchall")）を推奨し、メールが何も通知されずに破棄されないようにします
6. 件名から正規表現でチケット ID を抽出し、既存のチケットにルーティングするカスタム解析ルールの使用方法を示します 結果：すべてを受け止める安全策を備え、顧客からの返信をチケット管理システムに転送する受信メールルーティングを利用できます

例3：Mailgun Optimize でメールの配信到達率を改善する

ユーザーの発言：「Mailgun のメールが Gmail の迷惑メールフォルダーに振り分けられています。原因を特定して改善するにはどうすればよいですか？」 スキルの内容：

1. ユーザーが Mailgun Optimize を利用しているか確認します。利用していない場合は、受信トレイへの到達状況をテストできる Pilot プラン（$49/mo）を推奨します
2. 受信トレイへの到達状況を確認するシードテストを実行し、Gmail、Outlook、Yahoo などのプロバイダーでメールがどこに振り分けられるか確認します
3. Domains API を使って、ドメインの DNS 認証を確認します。SPF、DKIM、DMARC のレコードが適切に設定されているか検証します
4. Optimize ダッシュボードで送信者の評判を確認し、ブロックリストへの登録状況と評判スコアを調べます
5. CSV を一括アップロードして送信先リストを検証し、無効なアドレス、使い捨てアドレス、リスクの高いアドレスを削除します（バウンス率を最大21％削減できます）
6. complained Webhook イベントを確認し、迷惑メールの苦情につながっているコンテンツや宛先を特定します 結果：迷惑メールフォルダーに振り分けられる根本原因（DMARC の設定漏れ、IP のブロックリスト登録、高いバウンス率など）を特定し、継続的な監視を含む具体的な改善計画を立てられます

トラブルシューティング

ドメイン送信キーを使用するとメールが 401 Unauthorized で拒否される

症状：GET /v3/domains や POST /v3/routes などのエンドポイントへの API 呼び出しは 401 Unauthorized を返しますが、メールの送信は正常に動作します 原因：ドメイン送信キーは /messages エンドポイントのみに制限されています。ドメイン、ルート、ウェブフック、メーリングリスト、その他の Mailgun リソースの管理には使用できません。セキュリティ分離のための仕様です。 解決策：送信以外の操作には、Mailgun ダッシュボードの「API Security」にあるメイン API キーを使用してください。本番環境での送信コードには、ドメイン送信キーのみを使用してください。プログラムからリソースを管理する必要がある場合は、メイン API キーを環境変数に安全に保存し、別のサービスまたはデプロイパイプラインで管理操作に使用してください。

ウェブフックイベントがエンドポイントに届かない

症状：Mailgun でウェブフックを設定したのに、エンドポイントがイベントを受信せず、サーバーログにもリクエストが記録されません 原因：よくある原因は、（1）ウェブフック URL に外部からアクセスできない（localhost またはファイアウォールの内側にある）、（2）エンドポイントが 2xx 以外のステータスコードを返すため、Mailgun が再試行後にリトライ間隔を延ばしている、（3）誤ったドメインにウェブフックを設定している、または（4）イベントが生成されていない（例：開封／クリックのトラッキングが有効になっていない）ことです。 解決策：エンドポイントに外部からアクセスできることを確認してください。ローカル開発には ngrok などのツールを使用してください。Mailgun ダッシュボードの「Sending」>「Webhooks」で、配信状況と最近の試行を確認してください。エンドポイントが数秒以内に 200 ステータスコードを返すことを確認してください。正しいドメインにウェブフックが設定されていることを確認してください。開封／クリックイベントについては、ドメイン設定でトラッキングが有効になっていることを確認してください。webhook.site などのシンプルなエンドポイントでテストし、問題が Mailgun の配信にあるのか、エンドポイント側の処理にあるのかを切り分けてください。

ドメインが EU にあるのにメールが米国リージョンから送信される（またはその逆）

症状：ドメインが検証済みで API キーも正しいのに、メールを送信しようとすると API 呼び出しが 404 または認証エラーを返します 原因：ドメインを一方のリージョン（米国または EU）で作成した一方で、API 呼び出しにもう一方のリージョンのベース URL を使用しています。米国のドメインには https://api.mailgun.net/v3/、EU のドメインには https://api.eu.mailgun.net/v3/ を使用する必要があります。ドメインは作成後にリージョン間で移動できません。 解決策：Mailgun ダッシュボードでドメインのリージョンを確認してください（ドメインページにあるリージョン表示を確認します）。API ベース URL をドメインのリージョンに合わせて更新してください。リージョンを切り替える必要がある場合（例：GDPR への準拠）、ドメインを削除して正しいリージョンで再作成し、その後 DNS レコードを再検証する必要があります。アプリケーションの設定、環境変数、SDK の初期化をすべて更新し、正しいリージョンの URL を使用してください。