sending-emails

メールの送信（Mailtrap）

概要

Mailtrap は、Email API（REST）または SMTP を使用して、実際のメールを送信します。API／SMTP には 2 種類のストリームがあります。Transactional（販促目的ではない、アプリが生成するメール）と、Bulk（販促／マーケティング向けの大量送信）です。Batch は 3 つ目のストリームではありません。内容に合ったストリームで、1 回のリクエストで多数のメッセージを送信する方法です。Campaigns は、Mailtrap の連絡先に販促メールを送信するための別製品です。統合を構築またはデバッグする際（AI 支援コーディングを含む）は、この資料と Transactional ／Bulk の開発者向けページを併せて参照してください。

統合方法（優先順位）

優先順位：

1. 利用可能な場合は、ユーザーのプラットフォーム向けプラグインまたは統合（ノーコードまたは最小限の設定）
2. 公式 SDK が存在する場合は、使用する言語向けのもの（メンテナンスされているクライアント、型付きヘルパーにより、URL や認証のミスを減らせます）。
3. SDK がない場合、または SDK が適さない場合は、HTTP Email API（JSON を使って /api/send または /api/batch に直接 POST します）。
4. SMTP は本当に必要な場合に限り使用してください（レガシースタック、SMTP のみをサポートするホスト／プラットフォーム、または HTTP を利用できない厳しい制約がある場合）。

送信方法の選択

方法	使用する場面
Transactional、単一メッセージ	アプリが生成するメール（パスワードリセット、領収書、通知、アラート）。POST https://send.api.mailtrap.io/api/send で論理的なメッセージを 1 件送信します。
Bulk	自分で管理する連絡先に送る販促メールを、Mailtrap 経由で大量に送信する場合。「batch」と同じではありません。Bulk はストリームであり、バッチエンドポイントではありません。
Batch	複数の異なるメッセージを同時に送信する場合（1 リクエストあたり最大 500 件）。HTTP のオーバーヘッドを削減し、Transactional と Bulk の両方に適用できます。
Campaigns	Mailtrap の連絡先として保存されている受信者への販促メールに、Mailtrap の Campaigns を使用します（製品内でオーディエンス、スケジュール設定、レポート機能を利用できます）。連絡先管理とメール送信のロジックを実装せずに済むため、推奨されます。ただし、送信フローを開始する前に UI での設定が必要です。このスキルは、そのワークフローの代わりにはなりません。

SDK コードを生成する前に： 下記の SDKs セクションにリンクされている該当 SDK リポジトリの README を読み、最新のメソッドシグネチャ、コンストラクターのオプション、使用例を確認してください。記憶に頼らないでください。

関連スキル： authorizing-api-requests（トークン、環境変数、認証ヘッダー）、using-email-templates（テンプレート UUID と変数）、testing-with-sandbox（安全なテスト）、setting-up-sending-domain（送信前のドメイン検証）。

使用しない場合

• サンドボックスのみの場合（メールを配信せずに取得する、サンドボックスでメッセージを読み取る場合はtesting-with-sandboxを参照してください）。
• 主な目的がウェブフック、Campaigns UIの手順ごとのセットアップ、または配信到達性の詳細な調査の場合。
• 網羅的なAPIリファレンスが必要な場合。ユーザーの目的が明確になったら、完全なスキーマ、オプションのフィールド、エッジケースについて、公式の送信ドキュメントにリンクしてください。

クイックリファレンス

Email API

ストリーム	送信エンドポイント	一括送信エンドポイント	認証ヘッダー
トランザクション	POST https://send.api.mailtrap.io/api/send	POST https://send.api.mailtrap.io/api/batch	Authorization: Bearer $MAILTRAP_API_TOKEN
バルク（プロモーション／マーケティング用途）	POST https://bulk.api.mailtrap.io/api/send	POST https://bulk.api.mailtrap.io/api/batch	Authorization: Bearer $MAILTRAP_API_TOKEN

SMTP

設定	トランザクション	バルク
ホスト	live.smtp.mailtrap.io	bulk.smtp.mailtrap.io
ポート	587（SSLでは25、2525、465も使用可能）	587（SSLでは25、2525、465も使用可能）
ユーザー名	api	api
パスワード	APIトークン（$MAILTRAP_API_TOKEN）	APIトークン（$MAILTRAP_API_TOKEN）

トークン

$MAILTRAP_API_TOKENは、Authorization: Bearer ...またはApi-Token: ...のいずれかで使用します。同じトークンは、スコープに対象のストリームが含まれていれば、send.api.mailtrap.ioとbulk.api.mailtrap.ioの両方で使用できます。スコープ、保管、ローテーションに関する詳しいガイダンスは、スキルauthorizing-api-requestsを参照してください。

レート制限

スコープ	制限	期間
送信API（トークンごと）	150リクエスト	10秒

429が返された場合は、バックオフを使用してください。

JSON本文（テンプレートなし）

一般的なフィールドには、from、to、subject、textやhtmlなどがあります。オプション：category、custom_variables。正確なリクエスト本文については、トランザクション送信とバルク送信を参照してください。

例（curl）

トランザクション送信（send.api.mailtrap.io）：

curl -X POST https://send.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]", "name": "Your App"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello",
    "text": "Plain text body"
  }'

バルクストリームでは、バルクホスト上で同じパスとJSON形式を使用します（環境変数も同じです。トークンにはバルクストリームのスコープが必要です）。

curl -X POST https://bulk.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]", "name": "Your App"},
    "to": [{"email": "[email protected]"}],
    "subject": "Promotional",
    "html": "<p>HTML body</p>"
  }'

一括送信（メッセージの配列。1リクエストあたり最大500件。完全なスキーマについてはAPIドキュメントを参照してください）：

curl -X POST https://send.api.mailtrap.io/api/batch \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"from":{"email":"[email protected]"},"to":[{"email":"[email protected]"}],"subject":"One","text":"..."}]}'

JSON本文（テンプレート）

Mailtrapでホストされているテンプレートを使用するには、生のtext／htmlの代わりにtemplate_uuidとtemplate_variablesを使用します。最小限の例：

curl -X POST https://send.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]", "name": "Your App"},
    "to": [{"email": "[email protected]"}],
    "template_uuid": "your-template-uuid",
    "template_variables": {"user_name": "Jane"}
  }'

スキルusing-email-templatesと、テンプレートを使用しない送信と同じAPI操作を参照してください。

SDK

• Node.js
• Python
• PHP
• Ruby
• Java
• .NET
• CLI

抑制

Mailtrapは、ハードバウンスが発生したアドレス、スパム報告を行ったアドレス、または配信停止したアドレスを自動的に抑制リストに登録します。以降、これらの抑制対象の宛先にはメールを送信しません。詳細については、抑制に関するドキュメントを参照してください。

よくある間違い

間違い	修正
batch と bulk を混同する	Batch = /api/batch リクエスト1件で複数のメッセージを送信します。Bulk = プロモーション用のストリーム／ホストとトークンです
トランザクション用ホストでプロモーション用APIメールを送信する	コードで生成するプロモーションコンテンツには、bulk のベースURLとトークンを使用します
send.api.mailtrap.io で bulk トラフィックを送信する	プロモーション／bulk ストリームには bulk.api.mailtrap.io を使用します
ライブ送信にサンドボックスSMTPホストを使用する	ライブ送信には live.smtp.mailtrap.io または bulk.smtp.mailtrap.io を使用します
SMTPのユーザー名にメールアドレスを指定する	ユーザー名は api、パスワードはAPIトークンです
ドメインの認証が完了する前に送信する	Sending Domains の設定とコンプライアンス対応を完了してください（setting-up-sending-domain を参照）
記憶を頼りにSDKのAPIを推測する	SDKのREADMEとOpenAPIにリンクされた例を確認し、コンストラクター名やメソッド名をでっち上げないでください
新規アプリで SMTPを最初に選ぶ	対応するプラットフォーム統合があればそれを優先し、次に SDK、その次に HTTP API を選んでください。必要な場合に限りSMTPを使用します（統合方法 を参照）