E-Mail-Anbieter ersetzen

PUT /v1/email-provider · Berechtigung email-provider:write · alle Tarife

Ersetzt, wie die Umgebung E-Mails versendet. Sie können fünf Modi festlegen:

• platform_default: KeenAuth sendet von einer eigenen Adresse. Nur reply_to darf gesetzt werden.
• platform_managed_domain: KeenAuth sendet von Ihrer eigenen Domain, signiert mit DKIM für diese Domain. Fügen Sie die Domain zuerst über E-Mail-Absenderdomains hinzu und veröffentlichen Sie vorher ihre DNS-Einträge; die Domain muss verified sein. Setzen Sie sender_domain_id und eine from_address genau in dieser Domain (nicht in einer Subdomain davon). Nur für Produktionsumgebungen. Wenn die Domain später nicht mehr verifiziert ist, wird E-Mail als platform_default gesendet, bis die Domain erneut verifiziert ist; die Konfiguration selbst ändert sich nicht.
• customer_smtp: Ihr SMTP-Server auf Port 465 (implizites TLS) oder 587 (STARTTLS ist erforderlich). Das Zertifikat muss für den Hostnamen gültig sein.
• customer_api: Ihr Konto bei ses, sendgrid, postmark, mailgun oder brevo.
• customer_webhook: KeenAuth rendert die Nachricht und übergibt sie an einen Ihrer Webhook-Endpunkte; Ihre Anwendung versendet sie (siehe Webhook-Zustellung). Setzen Sie webhook_endpoint_id auf einen aktivierten Endpunkt dieser Umgebung.

If-Match ist erforderlich und enthält die Version, die Sie gelesen haben (das ETag von get). Für eine Umgebung, die noch nie konfiguriert wurde, senden Sie If-Match: "0"; * passt darauf nicht. Bei einer Abweichung wird 412 zurückgegeben.

Die Zugangsdaten sind nur beim Schreiben möglich. Senden Sie sie in credentials; keine Antwort gibt sie zurück. Wenn Sie das Feld weglassen, bleiben die gespeicherten Zugangsdaten nur erhalten, wenn Modus und Ziel (SMTP-Host, Port und Benutzername oder Anbieter) unverändert sind. Andernfalls schlägt die Anfrage mit /credentials required fehl.

Eine Änderung löscht das letzte Ergebnis des Verbindungstests und schreibt einen Audit-Eintrag (email_provider.updated) nur mit Modus, Anbieter und ID der Absenderdomain, niemals mit einer Adresse oder den Zugangsdaten. Führen Sie nach einer Änderung einen Verbindungstest aus.

Anfrage

Antwort

200 OK mit der gespeicherten Konfiguration (gleiche Struktur wie bei get) und ETag auf die neue Version gesetzt.

Fehler

Regeln in errors[]:

Webhook-Zustellung

Im Modus customer_webhook versendet KeenAuth die Nachricht nicht selbst und weicht niemals auf den eigenen Versand aus. Für jede Nachricht, die gerendert wird (Betreff, HTML und Text), sendet KeenAuth ein signiertes Ereignis per HTTPS an den Endpunkt:

• Die Anfrage ist ein POST mit Content-Type: application/json und den Standard-Webhooks-v1-Headern webhook-id, webhook-timestamp und webhook-signature. webhook-id ist die Nachrichten-ID (msg_…) und bleibt bei jedem Versuch derselben Nachricht gleich, deduplizieren Sie daher anhand dieses Werts. Der Ereignistyp muss nicht in der Ereignisliste des Endpunkts enthalten sein: Der Endpunkt erhält ihn, weil er der Zustellendpunkt ist.
• Erfolg ist jede Antwort mit 2xx. Weiterleitungen werden nicht verfolgt und gelten als Fehler. Ein Versuch läuft nach 10 Sekunden ab.
• Ein fehlgeschlagener Versuch wird 15 Sekunden später wiederholt, insgesamt höchstens 3 Versuche. Nach dem dritten Fehlschlag wird die Nachricht als fehlgeschlagen markiert und keine E-Mail gesendet. Ein Endpunkt, der nach dem Speichern der Konfiguration gelöscht oder deaktiviert wurde, lässt die Nachricht sofort ohne Versuch fehlschlagen.
• Der Nachrichteninhalt wird vom Webhook-Dienst nicht gespeichert. Senden Sie nur an Endpunkte, denen Sie vertrauen: Der Body enthält die Empfängeradresse sowie etwaige Anmelde-Codes oder Links.

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

Die Signatur ist v1, plus die Base64-Kodierung von HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>"). Der Schlüssel ist der 32-Byte-Wert, der durch die 43 Base62-Zeichen nach dem Präfix idp_whsec_ des Signiergeheimnisses des Endpunkts kodiert ist. Prüfen Sie den rohen Request-Body, bevor Sie ihn parsen, und weisen Sie einen Zeitstempel ab, der mehr als 300 Sekunden von Ihrer Uhr abweicht. Während einer Geheimnis-Rotation enthält webhook-signature zwei durch Leerzeichen getrennte Signaturen.

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

Beispiel

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

Um Nachrichten an einen Webhook-Endpunkt zu übergeben:

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

In diesem Modus gibt es keine Verbindung zu test; testen Sie den Endpunkt mit Einen Webhook-Endpunkt testen.

Um von Ihrer verifizierten Absenderdomain zu senden:

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

In diesem Modus gibt es keine Verbindung zu test; prüfen Sie stattdessen die Domain mit verify.

CLI: keenauth email-provider put --if-match '"0"' --data @email-provider.json. Bewahren Sie die Zugangsdaten in einer Datei auf oder übergeben Sie sie über die Standardeingabe (--data -), damit sie nicht in Ihrem Shell-Verlauf landen.