メールプロバイダを置き換える

PUT /v1/email-provider · 権限 email-provider:write · すべてのプラン

環境がメールを送信する方法を置き換えます。次の5つのモードを指定できます:

• platform_default: KeenAuth が独自のアドレスから送信します。設定できるのは reply_to のみです。
• platform_managed_domain: KeenAuth が お客様のドメインから送信し、そのドメインの DKIM で署名します。先に メール送信元ドメイン でドメインを追加し、DNS レコードを公開してください。ドメインは verified である必要があります。sender_domain_id と、そのドメイン内(サブドメインは不可)の from_address を設定してください。本番環境でのみ使用できます。後からドメインが検証済みでなくなった場合、ドメインが再び検証されるまでメールは platform_default として送信されます。設定自体は変わりません。
• customer_smtp: ポート 465(暗黙的 TLS)または 587(STARTTLS が必須)で、お客様の SMTP サーバーを使用します。証明書はホスト名に対して有効である必要があります。
• customer_api: ses、sendgrid、postmark、mailgun または brevo のお客様アカウントを使用します。
• customer_webhook: KeenAuth がメッセージをレンダリングし、お客様の Webhook エンドポイント のいずれかに渡します。送信はお客様のアプリケーションが行います(Webhook 配信を参照)。webhook_endpoint_id には、この環境で有効になっているエンドポイントを設定してください。

If-Match は必須で、読み取ったバージョン(get の ETag)を指定します。一度も設定されていない環境では If-Match: "0" を送信してください。* は一致しません。不一致の場合は 412 が返ります。

認証情報は書き込み専用です。credentials で送信してください。レスポンスには返されません。省略した場合、モードと送信先(SMTP ホスト、ポート、ユーザー名、またはプロバイダ)が変わらない場合にのみ保存済みの認証情報が保持されます。それ以外の場合、リクエストは /credentials の required で失敗します。

変更すると、最後の接続テストの結果はクリアされ、モード、プロバイダ、送信元ドメイン ID のみを含む監査レコード(email_provider.updated)が書き込まれます。アドレスや認証情報は記録されません。変更後は 接続テスト を実行してください。

リクエスト

レスポンス

200 OK と、保存された設定(get と同じ形式)が返ります。ETag には新しいバージョンが設定されます。

エラー

errors[] のルール:

Webhook 配信

customer_webhook モードでは、KeenAuth はメッセージを送信せず、自身の送信に切り替えることもありません。レンダリングしたすべてのメッセージ(件名、HTML、テキスト)について、HTTPS で署名付きイベントを 1 件エンドポイントに送信します。

• リクエストは POST で、Content-Type: application/json と Standard Webhooks v1 のヘッダー webhook-id、webhook-timestamp、webhook-signature を含みます。webhook-id はメッセージ ID(msg_…)で、同じメッセージのすべての試行で同じ値になります。そのため、この値で重複を排除してください。イベントタイプがエンドポイントのイベント購読に含まれている必要はありません。配信先のエンドポイントであるため、イベントは受信されます。
• 2xx のレスポンスを成功とみなします。リダイレクトは追跡されず、失敗として扱われます。1 回の試行は 10 秒でタイムアウトします。
• 失敗した試行は 15 秒後に再試行され、合計で最大 3 回試行されます。3 回目の失敗後、メッセージは失敗としてマークされ、メールは送信されません。設定を保存した後にエンドポイントが削除または無効化された場合、試行せずに即座にメッセージが失敗します。
• メッセージの内容は Webhook サービスに保存されません。信頼できるエンドポイントにのみ送信してください。ボディには受信者のアドレスと、サインイン用のコードやリンクが含まれます。

ボディ(schema_version 1):

{
  "id": "msg_01k7xq3m5r8t9v0w1x2y3z4a5b",
  "type": "email.send_requested",
  "schema_version": 1,
  "environment_id": "env_01k7xq3m5r8t9v0w1x2y3z4a5b",
  "occurred_at": "2026-10-27T09:00:00Z",
  "data": {
    "message_id": "msg_01k7xq3m5r8t9v0w1x2y3z4a5b",
    "family": "email_otp",
    "locale": "en",
    "to": "ada@example.com",
    "from": "auth@example.com",
    "from_name": "Example",
    "reply_to": "support@example.com",
    "subject": "Your sign-in code",
    "html": "<p>Your code is 123456</p>",
    "text": "Your code is 123456",
    "link": "https://example.keenauth.app/...",
    "code": "123456"
  }
}

署名は v1, に続けて、HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>") を base64 エンコードした値です。鍵は、エンドポイントの署名シークレットの idp_whsec_ 接頭辞に続く 43 文字の base62 文字列でエンコードされた 32 バイトの値です。解析する前に生のリクエストボディを検証し、タイムスタンプがお客様の時計から 300 秒以上ずれている場合は拒否してください。シークレットのローテーション中は、webhook-signature に半角スペースで区切られた 2 つの署名が含まれます。

Python:

import base64, hashlib, hmac, time

ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
PREFIX = "idp_whsec_"


def signing_key(secret: str) -> bytes:
    """The HMAC key is the 32-byte value behind the 43 base62 characters after the prefix."""
    body = secret[len(PREFIX):len(PREFIX) + 43]
    n = 0
    for ch in body:
        n = n * 62 + ALPHABET.index(ch)
    return n.to_bytes(32, "big")


def verify(secret: str, headers: dict, raw_body: bytes, tolerance: int = 300) -> bool:
    msg_id = headers["webhook-id"]
    ts = headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > tolerance:
        return False
    signed = f"{msg_id}.{ts}.".encode() + raw_body
    mac = hmac.new(signing_key(secret), signed, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(mac).decode()
    # webhook-signature holds one or more space-separated signatures.
    return any(hmac.compare_digest(expected, s) for s in headers["webhook-signature"].split(" "))

Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
const PREFIX = "idp_whsec_";

// The HMAC key is the 32-byte value behind the 43 base62 characters after the prefix.
function signingKey(secret) {
  let n = 0n;
  for (const ch of secret.slice(PREFIX.length, PREFIX.length + 43)) n = n * 62n + BigInt(ALPHABET.indexOf(ch));
  return Buffer.from(n.toString(16).padStart(64, "0"), "hex");
}

export function verify(secret, headers, rawBody, tolerance = 300) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > tolerance) return false;
  const mac = createHmac("sha256", signingKey(secret)).update(`${id}.${ts}.`).update(rawBody).digest();
  const expected = Buffer.from(`v1,${mac.toString("base64")}`);
  // webhook-signature holds one or more space-separated signatures.
  return headers["webhook-signature"].split(" ").some((s) => {
    const got = Buffer.from(s);
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

例

curl -X PUT https://api.eu.keenauth.com/v1/email-provider \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "0"' \
  -d @email-provider.json

email-provider.json:

{
  "mode": "customer_smtp",
  "from_address": "no-reply@example.com",
  "smtp_host": "smtp.example.com",
  "smtp_port": 587,
  "smtp_username": "mailer",
  "credentials": "<SMTP password>"
}

メッセージを Webhook エンドポイントに渡す場合:

{
  "mode": "customer_webhook",
  "webhook_endpoint_id": "whe_01k7xq3m5r8t9v0w1x2y3z4a5b",
  "from_address": "auth@example.com"
}

このモードでは テスト への接続はありません。代わりに Webhook エンドポイントをテストする でエンドポイントをテストしてください。

検証済みの送信元ドメインから送信する場合:

{
  "mode": "platform_managed_domain",
  "sender_domain_id": "sdom_01k7xq3m5r8t9v0w1x2y3z4a5b",
  "from_address": "auth@mail.example.com",
  "reply_to": "support@example.com"
}

このモードでは テスト への接続はありません。代わりに 検証 でドメインを確認してください。

CLI: keenauth email-provider put --if-match '"0"' --data @email-provider.json。認証情報はファイルに保存するか、標準入力(--data -)で渡してください。そうすることで、シェルの履歴に残ることを防げます。