E-posta sağlayıcısını değiştir

PUT /v1/email-provider · izin email-provider:write · tüm planlar

Ortamın e-postayı nasıl gönderdiğini değiştirir. Beş mod belirtebilirsiniz:

• platform_default: KeenAuth, kendi adresinden gönderir. Yalnızca reply_to ayarlanabilir.
• platform_managed_domain: KeenAuth, kendi alan adınızdan gönderir ve bu alan adı için DKIM ile imzalar. Önce alan adını e-posta gönderen alan adları üzerinden ekleyin ve DNS kayıtlarını yayımlayın; alan adının durumu verified olmalıdır. sender_domain_id ve tam olarak bu alan adına ait bir from_address ayarlayın (alt alan adı olmamalıdır). Yalnızca üretim ortamlarında kullanılabilir. Alan adı daha sonra doğrulanmış durumunu kaybederse, alan adı yeniden doğrulanana kadar e-postalar platform_default ile gönderilir; yapılandırma kendisi değişmez.
• customer_smtp: 465 (örtük TLS) veya 587 (STARTTLS zorunludur) numaralı bağlantı noktasındaki SMTP sunucunuz. Sertifika, sunucu adı için geçerli olmalıdır.
• customer_api: ses, sendgrid, postmark, mailgun veya brevo üzerindeki hesabınız.
• customer_webhook: KeenAuth iletiyi oluşturur ve webhook uç noktalarınızdan birine iletir; iletiyi uygulamanız gönderir (bkz. Webhook teslimi). webhook_endpoint_id alanına bu ortamdaki etkin bir uç noktanın kimliğini yazın.

If-Match zorunludur ve okuduğunuz sürümü taşır (get işleminden gelen ETag). Hiç yapılandırılmamış bir ortam için If-Match: "0" gönderin; * bu değerle eşleşmez. Eşleşme olmazsa 412 döner.

Kimlik bilgisi yalnızca yazılabilir. credentials alanında gönderin; hiçbir yanıt bunu geri döndürmez. Bu alanı atlarsanız, kayıtlı kimlik bilgisi yalnızca mod ve hedef (SMTP sunucusu, bağlantı noktası ve kullanıcı adı ya da sağlayıcı) değişmediğinde korunur. Aksi halde istek /credentials required hatasıyla başarısız olur.

Bir değişiklik, son bağlantı testi sonucunu temizler ve yalnızca mod, sağlayıcı ve gönderen alan adı kimliğini içeren bir denetim kaydı (email_provider.updated) yazar; adres ya da kimlik bilgisi asla yazılmaz. Değişiklikten sonra bir bağlantı testi çalıştırın.

İstek

Yanıt

Kayıtlı yapılandırmayı içeren 200 OK (şekli get ile aynı) ve yeni sürüme ayarlanmış ETag.

Hatalar

errors[] içindeki kurallar:

Webhook teslimi

customer_webhook modunda KeenAuth iletiyi göndermez ve hiçbir zaman kendi gönderimine geri dönmez. Oluşturduğu her ileti (konu, HTML ve metin) için uç noktaya HTTPS üzerinden imzalı bir olay gönderir:

• İstek POST yöntemiyle, Content-Type: application/json ve Standard Webhooks v1 üstbilgileri webhook-id, webhook-timestamp ve webhook-signature ile gönderilir. webhook-id, ileti kimliğidir (msg_…) ve aynı iletinin her denemesinde aynıdır; bu nedenle yinelemeleri bu kimliğe göre ayıklayın. Olay türünün uç noktanın olay aboneliğinde bulunması gerekmez: uç nokta, teslim uç noktası olduğu için olayı alır.
• Başarı, herhangi bir 2xx yanıttır. Yönlendirmeler izlenmez ve başarısızlık sayılır. Tek bir deneme 10 saniyede zaman aşımına uğrar.
• Başarısız bir deneme 15 saniye sonra yeniden denenir; toplamda en fazla 3 deneme yapılır. Üçüncü başarısızlıktan sonra ileti başarısız olarak işaretlenir ve e-posta gönderilmez. Yapılandırmayı kaydettikten sonra silinen ya da devre dışı bırakılan bir uç nokta, iletiyi deneme yapmadan hemen başarısız kılar.
• İleti içeriği webhook hizmeti tarafından saklanmaz. Yalnızca güvendiğiniz uç noktalara gönderin: gövde, alıcı adresini ve varsa oturum açma kodunu ya da bağlantısını içerir.

Gövde (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"
  }
}

İmza, v1, ile birlikte HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>") değerinin base64 karşılığıdır. Anahtar, uç noktanın imzalama sırrındaki idp_whsec_ öneki ardından gelen 43 base62 karakterinin kodladığı 32 baytlık değerdir. Ham istek gövdesini ayrıştırmadan önce doğrulayın ve saatinizden 300 saniyeden fazla uzak bir zaman damgasını reddedin. Sır döndürme sırasında webhook-signature boşlukla ayrılmış iki imza içerir.

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);
  });
}

Örnek

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>"
}

İletileri bir webhook uç noktasına iletmek için:

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

Bu modda test ile bağlantı yoktur; uç noktayı Webhook uç noktasını test et ile test edin.

Doğrulanmış gönderen alan adınızdan göndermek için:

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

Bu modda test ile bağlantı yoktur; bunun yerine alan adını doğrula ile kontrol edin.

CLI: keenauth email-provider put --if-match '"0"' --data @email-provider.json. Kimlik bilgisini bir dosyada tutun ya da standart girdi üzerinden verin (--data -), böylece komut geçmişinize yazılmasın.