Mailtrap Email Integration
MailtrapのEmail APIとSandboxを使用してアプリケーションにトランザクションメール送信を追加するためのパターン。認証、環境分離、一般的な配信の落とし穴をカバーしています。
アクティブ化のタイミング
- 「メール送信」機能の実装（サインアップ確認、パスワードリセット、通知、領収書）
- 開発/ステージング環境でメールが届かない理由のデバッグ
- プロジェクトへの初めてのメール送信統合のセットアップ
- Sandbox分離なしでメールAPIを直接呼び出すコードのレビュー
コアコンセプト
Sandboxと本番環境の分離。 Mailtrapは、メールを配信せずにキャプチャするSandbox APIを提供します。これは開発/ステージング環境で使用され、テストメールが実際の受信トレイに届かないようにします。本番送信には、別途検証済みドメインのエンドポイントを使用します。開発環境を本番送信エンドポイントに向けてはいけません。
認証。 リクエストはAuthorizationヘッダーのBearerトークンを使用します。トークンはプロジェクトごとにスコープされ、Sandboxと本番では通常異なるトークンを使用します。
ドメイン検証。 本番送信では、Mailtrapが実際の受信者に配信する前に、DNSレコード（SPF、DKIM、DMARC）を介して送信ドメインを検証する必要があります。これをスキップすると、サイレント配信エラーやスパムフォルダーへの格下げが発生します。
コード例
// MailtrapのEmail APIを使用した送信（本番環境）
async function sendEmail(to: string, subject: string, html: string) {
const response = await fetch("https://send.api.mailtrap.io/api/send", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.MAILTRAP_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: { email: "[email protected]", name: "Your App" },
to: [{ email: to }],
subject,
html,
}),
});
if (!response.ok) {
throw new Error(`Email send failed: ${response.status}`);
}
return response.json();
}
// 同じ呼び出しを非本番環境ではSandboxにルーティング
const MAILTRAP_ENDPOINT = process.env.NODE_ENV === "production"
? "https://send.api.mailtrap.io/api/send"
: `https://sandbox.api.mailtrap.io/api/send/${process.env.MAILTRAP_INBOX_ID}`;
アンチパターン
| アンチパターン | 問題点 | 代わりにすべきこと |
|---|---|---|
| 開発/テストで本番送信エンドポイントを使用 | 実際のテストメールが本番受信トレイに届き、スパム苦情やテストデータ漏洩のリスク | 非本番環境はSandboxエンドポイントにルーティングする |
| ソースコードへのAPIトークンのハードコーディング | バージョン管理にコミットすると認証情報漏洩リスク | 環境変数/シークレットマネージャーからトークンを読み込む |
| ドメイン検証完了前の送信 | メールがサイレントエラーになるかスパムフォルダーに格納 | 本番送信を有効にする前にSPF/DKIM/DMARCレコードを検証する |
| 送信失敗時のリトライ/エラーハンドリングなし | サイレントな通知失敗（例：ユーザーがパスワードリセットメールを受け取れない） | レスポンスステータスを確認し、失敗をログに記録し、実行可能なエラーを表示する |
ベストプラクティス
- Sandboxと本番のトークンは別々の環境変数に保持し、1つのトークンを複数の環境で共有しない
- メールを含む本番リリースの前に、送信ドメインのDNSレコードを検証する
- 配信失敗を十分なコンテキスト（受信者、テンプレート、タイムスタンプ、レスポンスコード）でログに記録する
- メール送信はエラーが発生し得るネットワーク呼び出しとして扱い、try/catchでラップし、成功を前提としない
関連スキル
api-and-interface-design, security-and-hardening, ci-cd-and-automation