Reemplazar el proveedor de correo electrónico

PUT /v1/email-provider · permiso email-provider:write · todos los planes

Reemplaza la forma en que el entorno envía correos electrónicos. Puede escribir cinco modos:

• platform_default: KeenAuth envía desde su propia dirección. Solo puede establecerse reply_to.
• platform_managed_domain: KeenAuth envía desde su propio dominio, firmado con DKIM para ese dominio. Añada el dominio con dominios remitentes de correo electrónico y publique antes sus registros DNS; el dominio debe estar verified. Establezca sender_domain_id y un from_address que esté exactamente en ese dominio (no en un subdominio). Solo en entornos de producción. Si el dominio deja de estar verificado más adelante, el correo se envía como platform_default hasta que el dominio vuelva a verificarse; la configuración en sí no cambia.
• customer_smtp: su servidor SMTP en el puerto 465 (TLS implícito) o 587 (se requiere STARTTLS). El certificado debe ser válido para el nombre de host.
• customer_api: su cuenta en ses, sendgrid, postmark, mailgun o brevo.
• customer_webhook: KeenAuth genera el mensaje y lo entrega a uno de sus endpoints de webhook; su aplicación lo envía (consulte Entrega por webhook). Establezca webhook_endpoint_id en un endpoint habilitado de este entorno.

If-Match es obligatorio y contiene la versión que leyó (el ETag de obtener). Para un entorno que nunca se ha configurado, envíe If-Match: "0"; * no coincide con él. Una discrepancia devuelve 412.

La credencial se escribe una sola vez. Envíela en credentials; ninguna respuesta la devuelve. Si la omite, la credencial almacenada solo se conserva cuando el modo y el destino (host SMTP, puerto y nombre de usuario, o proveedor) no cambian. En caso contrario, la solicitud falla con /credentials required.

Un cambio borra el último resultado de la prueba de conexión y escribe un registro de auditoría (email_provider.updated) con el modo, el proveedor y solo el identificador del dominio remitente, nunca una dirección ni la credencial. Después de un cambio, ejecute una prueba de conexión.

Solicitud

Respuesta

200 OK con la configuración almacenada (misma forma que obtener) y ETag establecido en la nueva versión.

Errores

Reglas en errors[]:

Entrega por webhook

En el modo customer_webhook, KeenAuth no envía el mensaje y nunca recurre a su propio envío. Por cada mensaje que genera (asunto, HTML y texto), publica un evento firmado en el endpoint a través de HTTPS:

• La solicitud es POST con Content-Type: application/json y los encabezados Standard Webhooks v1 webhook-id, webhook-timestamp y webhook-signature. webhook-id es el identificador del mensaje (msg_…) y es el mismo en cada intento del mismo mensaje, así que deduplique por ese valor. El tipo de evento no tiene que estar en la suscripción de eventos del endpoint: el endpoint lo recibe porque es el endpoint de entrega.
• Un éxito es cualquier respuesta 2xx. No se siguen redirecciones y cuentan como fallos. Un intento agota el tiempo de espera a los 10 segundos.
• Un intento fallido se reintenta 15 segundos después, con un máximo de 3 intentos en total. Después del tercer fallo, el mensaje se marca como fallido y no se envía ningún correo. Un endpoint que se elimine o deshabilite después de guardar la configuración hace que el mensaje falle de inmediato, sin intento.
• El servicio de webhook no almacena el contenido del mensaje. Envíelo solo a endpoints de confianza: el cuerpo incluye la dirección del destinatario y cualquier código de inicio de sesión o enlace.

Cuerpo (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 es v1, más el base64 de HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<raw body>"). La clave es el valor de 32 bytes codificado por los 43 caracteres base62 que siguen al prefijo idp_whsec_ del secreto de firma del endpoint. Verifique el cuerpo de la solicitud sin procesar, antes de analizarlo, y rechace una marca de tiempo que difiera más de 300 segundos de su reloj. Durante una rotación de secretos, webhook-signature contiene dos firmas separadas por espacios.

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

Ejemplo

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

Para entregar mensajes a un endpoint de webhook:

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

En este modo no hay conexión con probar; pruebe el endpoint con Probar un endpoint de webhook.

Para enviar desde su dominio remitente verificado:

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

En este modo no hay conexión con probar; compruebe el dominio con verificar en su lugar.

CLI: keenauth email-provider put --if-match '"0"' --data @email-provider.json. Guarde la credencial en un archivo o páselala por la entrada estándar (--data -) para que no quede en el historial de su shell.