ナレッジベース
REST API
発行・スコープ設定・失効ができるキーを備えた、ドキュメント化されたHTTP API。
詳細
- すべての環境で有効。APIは68のパスにまたがる104の文書化された操作（emails、threads、drafts、labels、contacts、audiences、domains、templates、rules、roles、members、settings、calendar、tracking、webhooks、そしてアカウント）を、GET /openapi.json でキーなしに読めるOpenAPI 3.1ドキュメントのもとで提供する。アクセス範囲は、Settingsで発行するワークスペースキーによって決まる。
- かつて待たれていた永続性は実装済みである。送信では何かが発送される前に行が書き込まれ、msg_ に続く24桁の16進数という形式の公開idが付く。GET /emails/{id} でそれを参照でき、/events では受信者ごとの記録が、/tracking では開封とクリックが得られる。1〜255文字の Idempotency-Key は、そのキーとAPIキーの組に対する一意インデックスで確保されるため、タイムアウト後の再試行では二重送信ではなく、Idempotency-Replayed: true を付けて最初の結果が返る。キー付きの送信は、確定していれば 200、まだキューに入っているか予約中であれば 202 を返す。
- キーは「設定 → APIキー」で発行、スコープ設定、ローテーション、失効を行う。コンソールが発行するキーはすべて oe_live_ である。oe_test_ というプレフィックスは検証側と送信経路が理解し、テストモードの送信はトランスポートに到達することなく記録され、送信済みとして応答される。ただし、今のところこれを発行する手段はない。no-opトランスポートがDurable Objectの上に置かれる前にこの選択肢を提供すれば、実際に配信してしまうテストキーを渡すことになるからである。キーは、最大25のドメイン全体と50の個別アドレスからなる送信スコープを持ち、ドメイン全体を指定した場合は後から追加されたアドレスも含まれる。さらに1〜3650日の任意の有効期限と、任意でロールを持てる。ロールは2つ目の付与ではなく上限である。GET /ping はキーに付いたスコープと、ロールが残したスコープの両方を返すため、キーに明示されているスコープで 403 になっても原因が目に見える。失効は削除ではなく更新なので、以降の呼び出しには単に認証失敗ではなく revoked_api_key が返る。ローテーションはシークレット以外のすべてを保つ。idも、スコープも、送信スコープも、リクエスト履歴もそのまま引き継がれ、古いシークレットは新しいものが発行された瞬間に失効する。keys:write を持つキーはAPI経由で自身をローテーションできる。同じ一覧・ローテーション・失効・有効化の操作は、キーを管理できるロールを持つ人であればMCPサーバーからも利用できる。
- 本当に存在しないもの。APIには独自のアップロード用エンドポイントがない。インライン添付は合計5MBの上限のもとbase64で送られ、それより大きいファイルは、ワークスペースにすでにあるファイルをidで指定して送る。これはダウンロードリンクとして届く。バウンスは送信ログではなくメールボックス側で扱われる。配信レポートは解析され、Message-IDで元のメールと突き合わされ、スレッドにラベルが付き、email.bounced のwebhookとして送出されるが、送信行には何も書き戻されない。送信行のstatusにはバウンスの状態がないため、GET /emails 越しにはバウンスしたメッセージも依然として送信済みに見える。アプリの作成画面から送ったメールも GET /emails には現れない。作成画面は同じ送信経路を通らないからである。