REST API
メールボックスを、素の HTTP で。
自分のコードからメールを送信、閲覧、管理できます。各キーが持つのは、付与したスコープだけです。
概要
メール API とは？
メール API は、アプリを介さずに HTTP でソフトウェアがメールを送信・閲覧できるようにするものです。各リクエストのキーが、呼び出し元の触れてよい範囲を決めます。
104
ドキュメント化されたオペレーション
25
1 つのキーの送信範囲に入れられるドメイン全体
50
それに加えて指定できる個別アドレス
仕組み
キーごとに役目を 1 つに
キーが持つスコープと、必要なら使ってよい差出人を選びます。スコープが足りない場合や、リストにない差出人の場合は 403 になります。
二重送信せずに再試行
各送信には、何かが送り出される前に msg_ の id が付きます。同じ Idempotency-Key で再試行すると、最初の結果が返ります。
シークレットを替えて、キーは残す
ローテーションで替わるのはシークレットだけなので、id、スコープ、リクエスト履歴は引き継がれます。失効したキーには revoked_api_key が返ります。
キーに持たせられるスコープ
全部で 30 種類。新しいキーは emails:send から始まります。
最初のメールを送る
素の HTTP と JSON。インストールは不要です。
curl -X POST https://api.openemail.uk/emails \ -H "Authorization: Bearer $OPENEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "Acme Billing <[email protected]>", "to": ["[email protected]"], "subject": "Your September invoice", "html": "<p>Invoice attached.</p>" }'できること
いま使える機能
すべての送信に id
/events で宛先ごとの履歴、/tracking で開封とクリック。
403 の理由がわかる
GET /ping は、キーのスコープと、ロールが残したものを示します。
MCP からキーを管理
MCP サーバーでも、キーの一覧、ローテーション、失効、有効化ができます。
上手な使い方
使いこなすために
- 01
サービスごとに 1 つのキー
漏れたキーを失効させても、止まるのはすべてではなく 1 つの連携だけです。
- 02
Idempotency-Key を設定
請求書番号のような一意の値から作れば、再試行で最初の結果が再現されます。
- 03
差出人を絞る
サービスが送信に使うアドレスだけを指定します。ドメイン全体なら、後から追加したアドレスも含まれます。
現状
知っておきたいこと
- アップロード用エンドポイントがない
- インライン添付は base64 で合計 5 MB まで。それより大きいファイルはワークスペースのファイル id で、ダウンロードリンクとして送ります。
- 送信にバウンス状態がない
- GET /emails はバウンスしたメッセージを送信済みとして返します。バウンスは宛先と email.bounced Webhook に表れます。
質問
よくある質問
さらに見る
