# 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](preview.md) 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](list.md)). |
| `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`

```json
{
  "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

```bash
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](/docs/policies/personal-data) 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.