APIキーの作成と管理

公開日: 2026年7月16日 · 最終更新日: 2026年9月12日 · 著者 Marcus Biel

APIキーのページでは、外部システムが認証を経て、アカウント内の対応するMaildroppa APIエンドポイントにアクセスするためのキーを管理します。

APIキーは1つ作成できます。キーの完全な値をコピーするほか、ローテーション（キーの入れ替え）によって安全にリセットしたり、不要になったキーを削除したりできます。同じアカウントキーを、サーバー側の連携システムと、MaildroppaのオートメーションのAPIリクエストトリガーで使用できます。

APIキーはMaildroppaアカウントの認証情報です。パスワードと同じように扱ってください。キーを入手した人は、キーがローテーションまたは削除されるまで、そのキーで利用できるAPIエンドポイントを呼び出せます。

APIキーの用途

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

主な用途は次のとおりです。

• CRM、オンラインショップ、会員管理システム、社内データベースとの購読者情報の同期。
• サーバー側のアプリケーションからの購読者の作成・更新。
• 対応するエンドポイントを通じた、タグ、カスタム項目、カスタム項目の値、セグメントの読み取り・管理。
• オートメーションのAPIリクエストトリガーへのカスタムイベントの送信。
• APIを通じたトランザクションメールの送信。
• APIベースのWebhookサブスクリプションの管理。

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

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

APIキーページを開く

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

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

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

ページには次の項目が表示されます。

• betaバッジ付きのAPIキーパネル。
• 「View OpenAPI docs」リンク。
• キーがない場合は、未作成の状態と「Create API key」ボタン。
• キーがある場合は、現在のキーをマスクした表示。
• キーの完全な値をコピーする「Copy」ボタン。
• 現在のキーを置き換える「Rotate API key」と、削除する「Delete API key」。

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

APIキーを作成する

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

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

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

• 未作成の状態を示す表示が消えます。
• マスクされたキーが表示されます。
• 「Copy」「Rotate API key」「Delete API key」が利用できるようになります。
• 処理の成功を示す「API key updated」メッセージが表示されます。

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

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

このページでは、キーの完全な値をそのまま表示することはありません。先頭5文字に続けて、5つのアスタリスクが表示されます。例：

a1b2c*****

これは表示上のマスクにすぎません。アスタリスクの数はキーの実際の長さを表していません。また、マスクされた値はAPIリクエストには使用できません。

現在のキーの完全な値をクリップボードにコピーするには、「Copy」をクリックします。コピーに成功すると、ボタンの表示が一時的に「Copied!」に変わります。

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

キーを安全に保存する

コピーしたキーは、連携システムで使用するシークレットの保存先に直接保存してください。

適した保存先は次のとおりです。

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

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

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

他の人と共有するドキュメントやシェル履歴に残るcurlのサンプルに、キーを直接記述しないでください。代わりに、MAILDROPPA_API_KEYなどの環境変数を使用してください。

APIキーを使用する

キーの完全な値を、HTTPリクエストのX-API-Keyヘッダーに指定して送信します。

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

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

本番APIと、操作しながら確認できるOpenAPIドキュメントは、次のURLで利用できます。

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キーページには、スコープの設定や、エンドポイントごとに権限を指定するチェックボックスはありません。そのため、ある連携システムが単一のエンドポイントしか使用しない場合でも、現在のアカウントキーは重要な認証情報として厳重に扱う必要があります。

レート制限

現在のOpenAPI仕様には、APIキーの利用に関する次の制限が記載されています。

• 標準の顧客向けAPI：毎分300リクエスト、毎時2,000リクエスト。
• /eventsのEvents API：毎秒100リクエスト、バースト時の容量は500リクエスト。

これらの制限はMaildroppaアカウント単位で適用されます。同じキーを共有する各スクリプトに、個別の上限が割り当てられるわけではありません。複数の連携システムが同じ利用枠を消費します。

Maildroppaが429 Too Many Requestsを返した場合は、新しいリクエストの送信を止め、Retry-Afterレスポンスヘッダーがあれば、その指定に従ってください。多数の再試行を並列で開始せず、キューを使用し、待機時間を設けるバックオフで再試行を制御してください。

APIがベータ版の間は、レート制限のポリシーが変更される可能性があります。大量のリクエストを扱う連携システムを設計する前に、OpenAPIドキュメントの冒頭にある情報を確認してください。

オートメーションのAPIリクエストでキーを使用する

連携システムからMaildroppaのEvents APIにカスタムイベントを送信すると、オートメーションを開始できます。

「API request」トリガーの設定では、このページで管理するものと同じアカウントAPIキーを使用します。キーがない場合はトリガーの設定画面で作成でき、キーの完全な値を含む、あらかじめ用意されたcurlリクエストをコピーできます。

この仕組みには、次の2つの重要な注意点があります。

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

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

APIキーをリセット・置き換えする

現在の認証情報をリセットまたは置き換えるには、「Rotate API key」を使用します。Maildroppaは、この1回の操作で新しいキーを作成し、以前のキーを無効にします。

次のような場合にローテーションを行います。

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

マスクされたキーの下にある「Rotate API key」をクリックします。既存のキーが使えなくなることを知らせる警告ダイアログが開きます。

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

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

ローテーションを確定すると、古いキーはすぐに使えなくなります。古いキーと新しいキーが同時に有効になる期間はありません。

アカウントのキーは1つだけなので、ローテーションは、そのキーを使用するすべてのサーバー、定期実行ジョブ、連携システム、スクリプト、オートメーションのイベント送信元に影響します。

計画的にローテーションを行う場合は、次の手順で進めてください。

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

現在のキーが漏えいしたと考えられる場合は、直ちにローテーションしてください。正規のシステムの更新に必要な短時間の中断は、やむを得ないものとして対応します。

APIキーを削除する

アカウントでAPIキー認証によるリクエストを受け付ける必要がなくなったら、キーを削除します。

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

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

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

• 現在のキーはすぐに使えなくなります。
• ページが「No API key yet」の状態に戻ります。
• 削除されたキーを使用するサーバー側の連携システムは、認証できなくなります。
• そのキーを使用するオートメーションのAPIリクエスト送信元は、イベントを送信できなくなります。

キーを削除しても、購読者、キャンペーン、タグ、カスタム項目、セグメント、オートメーション、その他のアカウントデータは削除されません。削除されるのは、対応する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回クリックし、リクエストが完了するまで待ってください。

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

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

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

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

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

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

リクエストで401 Unauthorizedが返される

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

• ヘッダー名が正確にX-API-Keyになっている。
• ヘッダーにはキーの完全な値が含まれ、マスク表示のアスタリスクは含まれていない。
• 連携システムが、代わりにAuthorization: Bearerを送信していない。
• シークレットに余分な空白、引用符、改行が追加されていない。
• アカウントキーが他の人によってローテーションまたは削除されていない。
• 起動時にのみ環境変数を読み込むサービスは、再起動している。
• リクエストを正しいMaildroppa API環境に送信している。

ローテーション後、一部の連携システムだけ動かなくなった

動かなくなった連携システムは、古いキーを使い続けている可能性があります。新旧のキーが同時に有効になる期間はありません。シークレットを更新し、設定をキャッシュしているプロセスを再起動してください。

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連携システムに影響します。キーは必要な場合にだけ作成し、信頼できるサーバーで保管してください。ローテーションは、アカウント全体の認証情報の変更として計画しましょう。