Sostituisci il provider email

PUT /v1/email-provider · autorizzazione email-provider:write · tutti i piani

Sostituisce il modo in cui l'ambiente invia le email. Puoi scrivere cinque modalità:

• platform_default: KeenAuth invia dal proprio indirizzo. Si può impostare solo reply_to.
• platform_managed_domain: KeenAuth invia dal tuo dominio, firmato con DKIM per quel dominio. Aggiungi prima il dominio con domini mittenti email e pubblica prima i suoi record DNS; il dominio deve essere verified. Imposta sender_domain_id e un from_address esattamente in quel dominio (non in un suo sottodominio). Solo ambienti di produzione. Se il dominio in seguito smette di essere verificato, le email vengono inviate come platform_default finché il dominio non torna verificato; la configurazione in sé non cambia.
• customer_smtp: il tuo server SMTP sulla porta 465 (TLS implicito) o 587 (STARTTLS è obbligatorio). Il certificato deve essere valido per il nome host.
• customer_api: il tuo account presso ses, sendgrid, postmark, mailgun o brevo.
• customer_webhook: KeenAuth genera il messaggio e lo consegna a uno dei tuoi endpoint webhook; la tua applicazione lo invia (vedi Consegna webhook). Imposta webhook_endpoint_id su un endpoint abilitato di questo ambiente.

If-Match è obbligatorio e contiene la versione che hai letto (l'ETag di get). Per un ambiente mai configurato, invia If-Match: "0"; * non corrisponde. Una mancata corrispondenza restituisce 412.

La credenziale può essere scritta una sola volta. Inviala in credentials; nessuna risposta la restituisce. Se la ometti, la credenziale salvata viene mantenuta solo se modalità e destinazione (host SMTP, porta e nome utente, oppure provider) non cambiano. Altrimenti la richiesta fallisce con /credentials required.

Una modifica cancella il risultato dell'ultimo test di connessione e scrive un record di audit (email_provider.updated) con la modalità, il provider e solo l'id del dominio mittente, mai un indirizzo o la credenziale. Dopo una modifica, esegui un test di connessione.

Richiesta

Risposta

200 OK con la configurazione salvata (stessa struttura di get) e ETag impostato sulla nuova versione.

Errori

Regole in errors[]:

Consegna webhook

Nella modalità customer_webhook KeenAuth non invia il messaggio e non ricorre mai al proprio invio. Per ogni messaggio che genera (oggetto, HTML e testo), invia un evento firmato all'endpoint tramite HTTPS:

• La richiesta è POST con Content-Type: application/json e gli header Standard Webhooks v1 webhook-id, webhook-timestamp e webhook-signature. webhook-id è l'id del messaggio (msg_…) ed è lo stesso in ogni tentativo dello stesso messaggio, quindi deduplica su di esso. Il tipo di evento non deve trovarsi nella sottoscrizione agli eventi dell'endpoint: l'endpoint lo riceve perché è l'endpoint di consegna.
• Il successo è qualsiasi risposta 2xx. I reindirizzamenti non vengono seguiti e contano come errori. Un tentativo scade dopo 10 secondi.
• Un tentativo fallito viene ripetuto dopo 15 secondi, per un massimo di 3 tentativi in totale. Dopo il terzo errore il messaggio viene contrassegnato come fallito e non viene inviata alcuna email. Un endpoint eliminato o disabilitato dopo che hai salvato la configurazione fa fallire il messaggio subito, senza tentativi.
• Il contenuto del messaggio non viene memorizzato dal servizio webhook. Invia solo a endpoint di cui ti fidi: il corpo contiene l'indirizzo del destinatario e qualsiasi codice di accesso o link.

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

La firma è v1, seguito dal base64 di HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>"). La chiave è il valore di 32 byte codificato dai 43 caratteri base62 che seguono il prefisso idp_whsec_ del segreto di firma dell'endpoint. Verifica il corpo grezzo della richiesta prima di analizzarlo, e rifiuta un timestamp che si discosta più di 300 secondi dal tuo orologio. Durante la rotazione di un segreto, webhook-signature contiene due firme separate da spazi.

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

Esempio

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

Per inviare i messaggi a un endpoint webhook:

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

In questa modalità non c'è alcuna connessione da verificare con test; testa l'endpoint con Testa un endpoint webhook.

Per inviare dal tuo dominio mittente verificato:

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

In questa modalità non c'è alcuna connessione da verificare con test; controlla invece il dominio con verify.

CLI: keenauth email-provider put --if-match '"0"' --data @email-provider.json. Conserva la credenziale in un file oppure passala dallo standard input (--data -), così non finisce nella cronologia della shell.