authorizing-api-requests

Mailtrap API リクエストの認証

概要

Mailtrap API のリクエストには、必ず2つの要素が必要です。

1. 認証ヘッダーのAPI トークン — リクエスト元を証明し、スコープを指定します。
2. アカウントスコープのエンドポイント（送信ホスト以外の大半）では、URL パスの**account_id**。

このスキルは、両方に関する唯一の信頼できる情報源です。他のスキル（sending-emails、testing-with-sandbox、using-email-templates、managing-contacts、setting-up-sending-domain）は、これらの規約を重複して記載せず、参照します。

使用する場面

• コード、スクリプト、CI、IaC、AI エージェントから Mailtrap API を呼び出す前
• プロビジョニングするトークンのスコープとストリームを選ぶとき
• トークンの保存先（環境変数、シークレットマネージャー、CI）を決めるとき
• アカウントスコープのエンドポイントに使うaccount_idを特定するとき
• 401 Unauthorized／403 Forbiddenの応答をデバッグするとき

API トークン

Settings > API Tokensで、機能する範囲で最小限のスコープを指定してトークンを作成します。

• Email Sending API — send.api.mailtrap.ioとbulk.api.mailtrap.io用です。可能な場合は、ストリーム（トランザクション、バルク）ごとにスコープを設定します。
• Email Testing API — Sandbox（sandbox.api.mailtrap.io）用です。本番の送信トークンとは必ず分けてください。
• Account-level API — Contacts、Templates、Sending Domains、Suppressions、およびhttps://mailtrap.io/api/accounts/{account_id}/...配下にあるその他のエンドポイント用です。

ユーザーが適切なプランを利用していれば、1つのトークンで複数のスコープをカバーできます。漏えい時の影響範囲を抑えるため、より限定的なトークン（1つのストリーム／プロジェクト／製品領域）を推奨します。参考：API トークンのドキュメント。

認証ヘッダー（同等の形式が2つあります）

Mailtrap ではどちらのヘッダーも使えます。例では Bearer を使用します。これは一般的な HTTP 規約であり、多くの自動生成 SDK コードにも適合するためです。

形式	ヘッダー	使用する場面
Bearer（推奨）	Authorization: Bearer $MAILTRAP_API_TOKEN	新しいコード、SDK、curl の例での標準
Api-Token（従来形式）	Api-Token: $MAILTRAP_API_TOKEN	古いクライアントや Bearer の使用が難しい場合

両方を同時に送信しないでください。どちらのヘッダーでも同じ値を使います。

トークンの保存先

• ローカル開発： 環境変数、または.gitignoreに含まれる.envファイルを使います。direnv、dotenv、またはフレームワーク組み込みの仕組みで読み込みます。
• CI／ビルド： CI プロバイダーの暗号化されたシークレットストア（GitHub Actions secrets、GitLab CI variables、CircleCI contexts）を使います。環境変数としてのみ注入してください。
• 本番／ステージング： 適切なシークレットマネージャー（AWS Secrets Manager、GCP Secret Manager、Azure Key Vault、HashiCorp Vault、Doppler、1Password など）を使います。定期的にローテーションしてください。
• エージェント／LLM ワークフロー： ホストエージェントのシークレットストアを使います。トークンをチャットやプロンプトに貼り付けないでください。

厳守事項：

• トークンをソース、設定、ノートブックに絶対にハードコードしないでください。
• トークンを絶対にコミットしないでください。Git に入ってしまった場合はローテーションしてください。履歴は永久に保持されます。
• トークンをフラグとしてコマンドラインに絶対に渡さないでください。シェルの履歴、ps、CI ログに漏えいします。
• LLM に、生成コード内でリテラルトークンを絶対に出力させないでください。すべての例で$VAR_NAME形式のシェル変数プレースホルダーを使用し、生成コードがリテラル値ではなく環境変数を参照するようにしてください。
• Sandbox と本番のトークンを絶対に混在させないでください。Sandbox のキーが漏えいしても、本物のメールを送信できないようにしてください。

推奨される環境変数名

これらの名前は、このリポジトリ内のほかのすべてのスキルと、以下のコード例で一貫して使用されています。

変数	用途
MAILTRAP_API_TOKEN	一般 API：メール送信（トランザクションメールおよび一括送信）、テンプレート、連絡先、送信ドメイン、抑制
MAILTRAP_SANDBOX_API_TOKEN	サンドボックス／メールテスト（個別のスコープ）
MAILTRAP_ACCOUNT_ID	アカウント単位のエンドポイント用パスパラメーター

環境で異なる名前を使っている場合は、起動時に一度エイリアスを設定してください。そうすれば、ほかのスキルのコード例を変更せずに使えます。

account_id を自動的に解決する

account_id は、すべての https://mailtrap.io/api/accounts/{account_id}/... エンドポイントで使われる整数のプレフィックスです。ハードコードしないでください。 環境ごとに異なり、組織によっても異なるため、スクリプトをチームメイトのアカウントにコピーすると、気付かないまま誤った値になります。

トークンでアクセス可能なすべてのアカウントを一覧表示する Accounts エンドポイントから、セッションごとに一度だけ解決してください。

curl -s https://mailtrap.io/api/accounts \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN"

レスポンスの形式（配列）：

[
  {"id": 12345, "name": "My Company", "access_levels": [1000]},
  {"id": 67890, "name": "Client Account", "access_levels": [100]}
]

access_levels の値：

• 1000 — アカウント所有者
• 100 — 管理者
• 10 — 閲覧者（ほとんどのエンドポイントで読み取り専用）

環境変数にキャッシュするワンライナー（トークンから複数のアカウントが見える場合は、適切なアカウントを選択してください）：

export MAILTRAP_ACCOUNT_ID=$(curl -s https://mailtrap.io/api/accounts \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" | jq '.[0].id')

参考：Accounts API。

クイックリファレンス

# Live sending (no account_id in path)
curl -X POST https://send.api.mailtrap.io/api/send \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# Account-scoped endpoint
curl "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/lists" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN"

# Sandbox / Testing
curl -X POST "https://sandbox.api.mailtrap.io/api/send/$MAILTRAP_INBOX_ID" \
  -H "Authorization: Bearer $MAILTRAP_SANDBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

よくある間違い

間違い	修正方法
コード、設定ファイル、ノートブックにトークンをハードコードする	$MAILTRAP_API_TOKEN（環境変数、.env、CI シークレット、シークレットマネージャー）から読み込みます。トークンが漏えいした場合はローテーションしてください
CLI フラグ（--token=...）としてトークンを渡す	環境変数を使ってください。CLI フラグはシェルの履歴、ps、CI ログに漏れる可能性があります
トークンをコミットした後、後のコミットで削除する	履歴に値が永久に残るため、ファイルを削除するだけでなく、直ちにトークンをローテーションしてください
トークンをチャット／プロンプト／課題に貼り付ける	チャットは公開されているものとして扱い、貼り付けてしまった場合はローテーションしてください
ライブ環境用の MAILTRAP_API_TOKEN をサンドボックスホストに使用する	サンドボックスでは独自のスコープと MAILTRAP_SANDBOX_API_TOKEN を使用します。混同すると失敗するか、誤って実際のメールを送信します
account_id をハードコードする	実行ごとに GET https://mailtrap.io/api/accounts で解決し、$MAILTRAP_ACCOUNT_ID に渡してください
トークンから複数のアカウントが見えるのに、誤ったアカウントを選ぶ	.[0] ではなく、name または access_levels（1000 = 所有者）で GET /api/accounts のレスポンスを絞り込んでください
Authorization と Api-Token の両方のヘッダーを送信する	どちらか一方を選んでください（新しいコードでは Bearer）。両方指定する必要はなく、一部の中継機器を混乱させます
閲覧者スコープのトークンで書き込みを行う	access_levels を確認してください。書き込みには、対象アカウントで 100（管理者）または 1000（所有者）が必要です