APIキーの作成と管理

Published: 2026年7月16日 · Last updated: 2026年7月21日 · By Marcus Biel

APIキーのページでは、外部システムからアカウント内のサポート対象Maildroppa APIエンドポイントへ、認証済みでアクセスできるようにします。

APIキーは1つ作成でき、完全な秘密の値をコピーしたり、ローテーションによって安全にリセットしたり、不要になったときに削除したりできます。同じアカウントキーを、サーバーサイドの統合やMaildroppa AutomationsのAPIリクエストトリガーで使用できます。

APIキーはMaildroppaアカウントを表します。パスワードと同じように扱ってください。キーを取得した人は、キーをローテーションまたは削除するまで、そのキーで利用可能なAPIエンドポイントを呼び出せます。

APIキーの用途

Maildroppaの外部にあるソフトウェアが、ユーザーによる対話型ログインなしでMaildroppaと連携する必要がある場合に、APIキーを使用します。

一般的な例：

• CRM、ショップ、会員管理システム、社内データベースとの購読者の同期。
• サーバーサイドアプリケーションからの購読者の作成または更新。
• サポート対象エンドポイントを介したタグ、フィールド、フィールド値、セグメントの読み取りまたは管理。
• AutomationのAPIリクエストトリガーへのカスタムイベントの送信。
• APIを介したトランザクションメールメッセージの送信。
• APIベースのWebhook購読の管理。

APIキーはサーバー間通信を目的としています。訪問者のブラウザで実行されるコード、公開ウェブサイト、モバイルアプリケーション、埋め込み型登録フォームでの使用は想定されていません。

このページには現在「ベータ」と表示されています。現在APIでサポートされているエンドポイント、リクエスト本文、パラメーター、レスポンススキーマについては、リンク先のOpenAPIドキュメントを参照してください。

APIキーページを開く

「Settings」を開き、「Developers」を展開して、「API key」を選択します。

次のURLから直接ページを開くこともできます。

https://app.maildroppa.com/settings/developers/api-key

ページには次の項目があります。

• ベータバッジ付きのAPIキーパネル。
• 「View OpenAPI docs」リンク。
• キーが存在しない場合の空の状態と「Create API key」ボタン。
• キーが存在する場合の現在のキーのマスク表示。
• 完全なキーをコピーする「Copy」ボタン。
• 現在のキーを置き換えたり削除したりする「Rotate API key」および「Delete API key」操作。

Maildroppaでは、アカウントごとに1つのAPIキーを使用できます。個別のアプリケーション、環境、チームメンバーごとに別々のキーを作成することはできません。

APIキーを作成する

ページに「No API key yet」と表示されている場合は、「Create API key」をクリックします。

Maildroppaはキーをすぐに作成します。初回作成時に確認ダイアログは表示されません。リクエストの実行中はボタンが「Creating API key」に変わり、ページ上のキー操作が一時的に無効になります。

キーが作成されると、次のようになります。

• 空の状態が消えます。
• マスクされたキーが表示されます。
• 「Copy」、「Rotate API key」、「Delete API key」の操作が利用可能になります。
• Maildroppaに「API key updated」という成功メッセージが表示されます。

アカウントに別のキーがすでに存在する場合、Maildroppaは2つ目のキーを作成しません。既存のキーを使用するか、ローテーションしてください。

マスクされたキーについて

ページには完全な秘密の値が通常のテキストとして表示されません。先頭5文字に続けて5つのアスタリスクが表示されます。例：

a1b2c*****

これは視覚的なマスクにすぎません。アスタリスクはキーの実際の長さを表しておらず、マスクされた値をAPIリクエストに使用することはできません。

完全な現在のキーをクリップボードに書き込むには、「Copy」をクリックします。コピーに成功すると、ボタンが短時間「Copied!」に変わります。

ページに戻った後もキーはマスクされたままですが、「Copy」をクリックすると完全な現在の値がコピーされます。そのため、作成時に保存しなかったというだけで、有効なキーをローテーションする必要はありません。

キーを安全に保存する

コピーしたキーは、統合で使用する秘密情報ストレージへ直接移してください。

適した保存先には次のようなものがあります。

• 管理されたシークレットマネージャー。
• 保護されたサーバー環境設定。
• 暗号化されたデプロイ用シークレット。
• 運用上の復旧に使用するパスワードマネージャー。

次の場所にはキーを保存しないでください。

• ブラウザー側のJavaScriptや、ダウンロード可能な別のフロントエンドバンドル。
• リポジトリにコミットされた公開または非公開のソースコードファイル。
• URLやクエリパラメーター。
• 公開ドキュメント、スクリーンショット、サポートメッセージ、課題管理システム。
• 共有アプリケーションログ、分析イベント、エラーレポート。
• 暗号化されていないスプレッドシートや通常のチームチャット。

他の人と共有されるドキュメントやシェル履歴にコピーされるcurlの例へキーを追加しないでください。MAILDROPPA_API_KEYのような環境変数を使用してください。

APIキーを使用する

完全なキーをX-API-Key HTTPリクエストヘッダーで送信します。

X-API-Key: your-complete-api-key

Bearerトークンとして送信しないでください。Maildroppaが要求するのはAuthorization: Bearer ...ではなくX-API-Keyです。

本番APIと対話型OpenAPIドキュメントは、次の場所で利用できます。

https://api.maildroppa.com

APIキーページで「View OpenAPI docs」をクリックすると、ドキュメントが新しいブラウザータブで開きます。そこでエンドポイントを選択し、メソッド、パス、パラメーター、リクエスト本文、レスポンスタイプ、利用可能なステータスコードを確認してください。

リクエスト例

次の例では、購読者の1ページ目を取得します。シークレットをコマンドに直接記述せず、環境変数からキーを読み取ります。

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

統合が実行される安全な環境で変数を設定してください。正確なメソッド、パス、クエリパラメーター、本文はエンドポイントによって異なります。Maildroppaアプリケーションで利用できる操作から推測せず、OpenAPIドキュメントから詳細をコピーしてください。

JSON本文を含むリクエスト

JSONを送信するリクエストでは、次も含めてください。

Content-Type: application/json

基本構造は次のとおりです。

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpointとその本文はプレースホルダーです。ドキュメントに記載されたエンドポイントとリクエストスキーマに置き換えてください。

キーでアクセスできる範囲

キーは、APIキー認証をサポートするエンドポイントでのみ機能します。Maildroppaアプリケーション内部で使用されるページやリクエストが、自動的に公開顧客APIの一部になるわけではありません。

OpenAPIドキュメントには、サポート対象の顧客APIが記載されています。APIキーの使用が記載されていないパスに、キーでアクセスできると想定しないでください。

APIキーページには、スコープやエンドポイントごとの権限チェックボックスはありません。そのため、現在のアカウントキーは、1つの統合で単一のエンドポイントしか使用しない場合でも、高価値の認証情報として扱う必要があります。

レート制限

現在のOpenAPIコントラクトには、次のAPIキー制限が記載されています。

• デフォルトの顧客API：毎分300リクエスト、毎時2,000リクエスト。
• /eventsのEvents API：毎秒100リクエスト、バースト容量500リクエスト。

これらの制限は各スクリプトに個別に適用されるのではなく、Maildroppaアカウントに適用されます。そのため、複数の統合で同じ許容量を消費することになります。

Maildroppaが429 Too Many Requestsを返した場合は、新しいリクエストの送信を停止し、Retry-Afterレスポンスヘッダーが存在する場合はそれに従ってください。多数の並列リトライを開始するのではなく、キューと制御されたバックオフを使用してください。

APIがベータ版である間に、レート制限ポリシーが変更される可能性があります。大量処理の統合を設計する前に、OpenAPIドキュメント上部の情報を確認してください。

AutomationのAPIリクエストでキーを使用する

システムからMaildroppaのEvents APIへカスタムイベントを送信すると、Automationを開始できます。

「API request」トリガーを設定すると、Maildroppaはこのページで管理されている同じアカウントAPIキーを使用します。キーが存在しない場合、トリガーの設定でキーを作成でき、完全なキーを含む準備済みのcurlリクエストをコピーできます。

これには2つの重要な影響があります。

• アカウントキーをローテーションまたは削除すると、Automationsへカスタムイベントを送信するシステムにも影響します。
• コピーしたAutomationのリクエスト例には、画面上でキーがマスクされていても、クリップボード内にシークレットが含まれます。

キーをローテーションまたは削除する前に、すべてのAPIリクエストトリガーと外部イベント送信元を統合一覧に含めてください。

APIキーをリセットまたは置き換える

現在の認証情報をリセットまたは置き換える必要がある場合は、「Rotate API key」を使用します。Maildroppaは同じ操作の一環として新しいキーを作成し、以前のキーを無効にします。

次の場合はローテーションを使用します。

• キーが漏えいした可能性がある。
• キーを知っている人またはプロバイダーが、アクセスを必要としなくなった。
• セキュリティポリシーで定期的な認証情報の交換が求められている。
• 古い場所や安全でない場所に保存されたキーを置き換えたい。

マスクされたキーの下にある「Rotate API key」をクリックします。Maildroppaは、既存のキーが使用できなくなることを説明する警告ダイアログを開きます。

続行するにはダイアログの「Rotate API key」をクリックし、現在のキーを維持するには「Cancel」をクリックします。

ローテーションに猶予期間はありません

ローテーションを確定すると、古いキーはすぐに機能しなくなります。Maildroppaは古いキーと新しいキーを同時に有効にすることはありません。

アカウントにはキーが1つしかないため、ローテーションは、そのキーを使用するすべてのサーバー、スケジュールジョブ、統合、スクリプト、Automationイベント送信元に影響します。

計画的なローテーションには、次の手順を使用してください。

1. 現在のキーを使用するすべての統合を一覧化します。
2. 各統合のシークレット設定とデプロイプロセスにアクセスできるよう準備します。
3. APIアクセスの中断が重要な場合は、短いメンテナンス時間を設定します。
4. 「Rotate API key」をクリックし、ダイアログの「Rotate API key」で警告を確定します。
5. 「Copy」をクリックして完全な新しいキーをコピーします。
6. すべての統合のシークレットを直ちに置き換えます。
7. 起動時にのみシークレットを読み込むサービスを再起動または再デプロイします。
8. 各統合を確認するため、影響のないドキュメント化されたリクエストを送信します。
9. 古いキーを使い続けている、忘れられたサービスからの401 Unauthorizedレスポンスを確認します。

現在のキーが侵害されたと考えられる場合は、直ちにローテーションし、正規のシステムを更新するために必要な短時間の中断を受け入れてください。

APIキーを削除する

アカウントでAPIキー認証されたリクエストを今後受け付けないようにする場合は、キーを削除します。

マスクされたキーの下にある「Delete API key」をクリックします。Maildroppaは、キーがアカウントから完全に削除されることを説明する警告ダイアログを開きます。

削除するにはダイアログの「Delete API key」をクリックし、保持するには「Cancel」をクリックします。

削除後は次のようになります。

• 現在のキーはすぐに機能しなくなります。
• ページが「No API key yet」の状態に戻ります。
• 削除されたキーを使用するサーバー統合は認証できなくなります。
• そのキーを使用するAutomationのAPIリクエスト送信元はイベントを配信できなくなります。

キーを削除しても、購読者、キャンペーン、タグ、フィールド、セグメント、Automations、その他のアカウントデータは削除されません。サポート対象APIエンドポイントへのアクセスに使用する認証情報が削除されるだけです。

後で「Create API key」をクリックして新しい認証情報を作成できます。削除した値は復元されません。新しいキーを使用するには、すべての統合を更新する必要があります。

リセットまたは削除：どちらを選ぶべきか

新しい認証情報でAPIアクセスを継続する場合は、「Rotate API key」を選択します。

少なくとも当面の間、APIアクセスを完全に停止する場合は、削除を選択します。

どちらの操作でも現在のキーはすぐに無効になります。ローテーションでは同じ操作の一環として置き換えキーが作成されますが、削除後はアカウントにキーが存在しなくなります。

セキュリティに関する推奨事項

API呼び出しはサーバーで行う

ブラウザーやモバイルアプリでは、埋め込まれたシークレットを確実に保護できません。ユーザーはアプリケーション、リクエストヘッダー、ソースマップ、ネットワークトラフィックを調査してキーを取り出せます。

ウェブサイトやアプリでアクションを実行する必要がある場合は、まず自分の認証済みバックエンドへリクエストを送信してください。そのバックエンドでユーザーを検証し、サーバーに保存したキーを使用してMaildroppaを呼び出します。

露出を最小限にする

キーは必要なシステムにだけ渡してください。すべての開発者に配布したり、複数のローカル設定ファイルに貼り付けたりしないでください。

現在、このページでは複数の名前付きキーやスコープ付きキーではなく、アカウント全体で1つのキーを管理しています。複数のアプリケーション間でより強い分離が必要な場合は、社内統合サービスまたはプロキシを使用してください。

リクエストヘッダーをマスキングする

HTTPクライアント、リバースプロキシ、オブザーバビリティツール、エラーレポーターでX-API-Keyをマスキングするよう設定してください。デバッグログを通じて認証情報が漏えいしていても、リクエスト自体は正常に動作する可能性があります。

環境を分離する

本番キーをローカル開発、サンプルコード、スクリーンショット、テストフィクスチャで再利用しないでください。環境ごとのシークレットは、環境ごとのシークレットストアに保存します。

「View OpenAPI docs」リンクは、本番ユーザーを自動的に本番APIドキュメントへ移動させます。実際のキーを送信する前に、必ずホスト名を確認してください。

漏えいが疑われる場合はローテーションする

メッセージ、リポジトリのコミット、ログ行、スクリーンショットを削除しても、誰もキーをコピーしていない証明にはなりません。完全な値が公開された場合は、ローテーションしてください。

APIエラーへの対処

HTTPステータスとドキュメントに記載されたレスポンス本文を使用して、統合の動作を決めてください。

一般的なケース：

• 400 Bad Request — パス、パラメーター、JSON本文がエンドポイントの契約を満たしていません。リクエストをOpenAPIスキーマと比較してください。
• 401 Unauthorized — X-API-Keyヘッダーがない、空白、無効、削除済み、またはローテーション後の古い値です。
• 403 Forbidden — 認証されたキーではその操作を許可されていません。
• 404 Not Found — パスまたは参照されたリソースがこのアカウントに存在しません。
• 429 Too Many Requests — 統合がAPIレート制限に達しました。リクエストを一時停止し、Retry-Afterヘッダーが存在する場合はそれに従ってください。
• 5xx — Maildroppaがリクエストを完了できませんでした。APIキーを含めないログを記録しながら、安全な操作を制限付きの指数バックオフで再試行してください。

すべての失敗を盲目的に再試行しないでください。同じリクエストを再送する前に、400、401、403、およびほとんどの404レスポンスの原因を修正してください。

変更を伴うリクエストでは、自動的に再送する前に、エンドポイントの再試行動作と冪等性を確認してください。接続失敗は、Maildroppaで変更が行われなかったことを必ずしも意味しません。

トラブルシューティング

「Create API key」が表示されたままになる

現在、アカウントにキーが存在しません。ボタンを1回クリックし、リクエストが完了するまで待ってください。

作成に失敗した場合は、再試行する前にページを再読み込みしてください。別のページやAutomationの設定ですでにアカウントキーが作成されている可能性があります。

ページ上のキーが短すぎるように見える

ページには意図的に先頭5文字と*****だけが表示されます。完全な値をコピーするには「Copy」をクリックしてください。マスクされたテキストをリクエストに送信しないでください。

「Copy」が「Copied!」に変わらない

ブラウザーがクリップボードへのアクセスをブロックしている可能性があります。ページをアクティブなタブに置き、表示された場合はクリップボードへのアクセスを許可してから、もう一度「Copy」をクリックしてください。

マスクされたテキストからキーを復元しようとしないでください。

リクエストが401 Unauthorizedを返す

次の点を確認してください。

• ヘッダー名が正確にX-API-Keyである。
• ヘッダーに完全な値が含まれており、表示されるアスタリスクが含まれていない。
• 統合が代わりにAuthorization: Bearerを送信していない。
• シークレットに空白、引用符、改行が追加されていない。
• 誰もアカウントキーをローテーションまたは削除していない。
• 起動時にのみ環境変数を読み取るサービスを再起動した。
• リクエストが正しいMaildroppa API環境へ送信されている。

1つの統合は動作するが、ローテーション後に別の統合が停止した

2つ目の統合が古いキーをまだ使用している可能性があります。重複して有効な期間はありません。シークレットを更新し、設定をキャッシュしているプロセスを再起動してください。

OpenAPIページは動作するが、エンドポイントが403を返す

すべてのアプリケーションエンドポイントがAPIキー認証をサポートしているわけではありません。顧客API向けに記載された操作を使用し、OpenAPIページで認証要件を確認してください。

リクエストが429 Too Many Requestsを返す

リクエストのバーストを減らし、処理をキューに入れ、APIが返した遅延後に再試行してください。並列リトライの集中を避けてください。複数のアプリケーションで1つのアカウントキーを共有している場合、それぞれがアカウントのAPI制限を共有するため、リクエスト量を調整してください。

推奨セットアップチェックリスト

統合を通常運用する前に、次の点を確認してください。

• キーがサーバーサイドのシークレット設定にのみ保存されている。
• リクエストでX-API-Keyヘッダーを使用している。
• 本番環境でhttps://api.maildroppa.comを使用している。
• すべてのメソッド、パス、パラメーター、JSON本文がOpenAPIドキュメントに従っている。
• ログとエラーレポートでキーがマスキングされている。
• タイムアウトと制限付きリトライが設定されている。
• 401、403、429、サーバーエラーを監視している。
• 統合の所有者が記録されている。
• アカウントキーを共有するすべてのシステムがローテーション計画に含まれている。
• キーが侵害された場合に迅速にローテーションできる。

APIキーページは意図的に簡潔ですが、その操作はアカウントに接続されたすべてのAPI統合に影響します。必要な場合にのみキーを作成し、信頼できるサーバーで保管し、アカウント全体の認証情報変更としてローテーションを計画してください。