Enviar un correo electrónico de prueba

POST /v1/email-templates/{family}/{locale}:test-send · permiso email-templates:write · plan Startup y superiores

Renderiza una versión de una plantilla de correo electrónico con los mismos datos de muestra que vista previa y la envía a una dirección a través de la ruta de envío normal, para que pueda revisarla en una bandeja de entrada real. El asunto comienza con [TEST] . La plantilla se valida de nuevo antes de enviarse.

Reglas:

El destinatario debe ser una dirección de correo electrónico verificada de un miembro active de su cuenta del panel. Cualquier otra dirección se rechaza, y la dirección nunca se repite en la respuesta ni en los registros.
Cada entorno puede enviar como máximo 20 correos de prueba por día UTC. El 21.º se rechaza con 429 hasta el día UTC siguiente (Retry-After indica la espera en segundos).
La lista de supresión sigue aplicándose. Si el destinatario está suprimido, el mensaje se registra con estado suppressed, no se entrega y aun así cuenta para el límite diario.
El entorno debe enviar plantillas personalizadas: un envío de prueba se rechaza cuando el modo de envío es platform_default o cuando el envío está restringido o suspendido.
Cada envío de prueba aceptado se escribe en el registro de auditoría de gestión como email_template.test_sent, con la familia, el idioma y la versión, pero sin el destinatario.

Parámetros de ruta

Parámetro	Descripción
`family`	Familia de correo electrónico, por ejemplo `verify_email` o `email_otp` (consulte Listar plantillas de correo electrónico).
`locale`	Etiqueta de idioma, por ejemplo `en` o `de`.

Encabezados

Encabezado	Descripción
`Idempotency-Key`	Opcional, de 16 a 64 caracteres de `A-Z a-z 0-9 _ -`. Repetir una solicitud con la misma clave devuelve el primer mensaje y no lo envía ni lo cuenta de nuevo. Los SDK y la CLI lo configuran por usted.

Solicitud

Campo	Tipo	Descripción
`to`	string	Obligatorio. El destinatario: una dirección verificada de un miembro `active` del panel, sin nombre para mostrar. Se ignoran las mayúsculas y los espacios al inicio y al final.
`version`	integer	La versión guardada que se enviará (1 o más). Predeterminado: la versión más reciente.
`published`	boolean	`true` envía la versión publicada. No puede combinarse con `version`.

Respuesta

200 OK

{
  "message_id": "0199f3c4-5d6e-7a8b-9c0d-1e2f3a4b5c6d",
  "state": "queued",
  "version": 3,
  "accepted_at": "2026-10-19T09:00:00Z"
}

Campo	Descripción
`message_id`	El identificador del mensaje.
`state`	`queued` (se enviará en breve) o `suppressed` (el destinatario está en la lista de supresión). Una solicitud repetida devuelve el estado actual del primer mensaje, que también puede ser `sent`, `failed` o `expired`.
`version`	La versión que se envió.
`accepted_at`	Momento en que se aceptó el mensaje.

Errores

HTTP	código	Cuándo
400	`unknown_field`	El cuerpo tiene un campo desconocido o no es un objeto JSON.
400	`malformed_request`	El cuerpo no es JSON válido, o `Idempotency-Key` está mal formado o repetido.
401	`unauthenticated`	La credencial falta, no es válida o fue revocada.
403	`insufficient_permissions`	La credencial carece del permiso requerido.
403	`plan_feature_unavailable`	El plan del entorno no incluye plantillas de correo electrónico personalizadas (Startup y superiores; `required_plan` indica cuál).
404	`not_found`	La familia o el idioma no existen, la versión no existe, o se envió `published` y no hay nada publicado.
409	`email_template_not_deliverable`	El modo de envío o el estado de envío del entorno no permite enviar plantillas personalizadas.
422	`validation_failed`	Falta `to` o no es una dirección de correo electrónico simple, `version` es menor que 1, se enviaron `version` y `published` a la vez (`conflicts_with_published`), o la versión ya no supera la validación.
422	`template_forbidden_construct`	La versión usa una construcción de Liquid fuera del entorno aislado.
422	`test_recipient_not_allowed`	El destinatario no es una dirección verificada de un miembro `active` del panel.
429	`rate_limited`	El entorno ya envió 20 correos de prueba este día UTC, o se superó el límite de frecuencia de la API; reintente después del periodo indicado en `Retry-After`.
503	`test_recipient_source_unavailable`	No se puede comprobar el destinatario en este momento; no se envió nada. Reintente después del periodo indicado en `Retry-After`.
503	`service_unavailable`	Una dependencia no está disponible temporalmente; reintente después del periodo indicado en `Retry-After`.

Ejemplo

curl -X POST https://api.eu.keenauth.com/v1/email-templates/verify_email/en:test-send \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-send-verify-email-en-0001" \
  -d '{"to":"you@example.com","version":3}'

CLI: keenauth email-templates test-send verify_email en --to you@example.com --version 3

Datos personales

Este endpoint trata datos personales: usuarios del panel y contactos de la cuenta. Datos personales en las API de KeenAuth describe qué se almacena, durante cuánto tiempo se conserva y cómo se elimina. No envíe categorías especiales de datos personales (salud, datos biométricos, religión, opiniones políticas, orientación sexual) en ningún campo.