Probar una plantilla

POST /api/v1/templates/{templateId}/test-send Envía un email —la plantilla tal como está— a la dirección que elijas, para que una persona pueda comprobar el renderizado en una bandeja de entrada real antes de construir ninguna campaña sobre ella. Es el lado API del botón «Enviar una prueba» de la pantalla de la plantilla.

json

{"success": true, "data": {"templateId": "…", "email": "you@example.com", "status": "test_sent"}}

Una prueba consume un envío real. Sale por el mismo camino que una campaña —la misma dirección de remitente que usará la campaña, el mismo conjunto de configuración, el mismo asunto y HTML, sin prefijo [TEST]— y cuenta para la cuota de envío de 24 h. A diferencia de POST /api/v1/render, este endpoint no es gratuito de llamar en bucle.

subject y content sobrescriben lo que se renderiza, nunca quién eres. Existen para que el editor pueda probar el borrador que está mostrando, antes de guardarlo. El templateId sigue decidiendo todo lo que importa: qué organización tiene permiso para enviar, qué lista de supresión se comprueba y qué identidad firma el mensaje. Pasar HTML no convierte esto en un endpoint de envío libre. Lo que escribe una prueba: nada. No se crea ninguna fila de envío, así que no se mueve ninguna estadística en ninguna parte. De ahí se derivan dos consecuencias, las mismas que para una prueba de campaña:

En un envío real	En una prueba
Píxel de seguimiento de aperturas	Ausente: el píxel se direcciona mediante una fila de envío
Enlaces reescritos para los clics	No reescritos: el seguimiento de clics se direcciona mediante una fila de envío
Etiquetas de combinación por destinatario	Datos de ejemplo de la vista previa, los mismos que muestra el panel de vista previa
Enlace de baja	Un enlace de vista previa que no da de baja a nadie

Condición	Respuesta
todo permitido	`200`: la prueba se envió
`email` ausente o mal formado	`400`: no se envió nada
ningún enlace de baja en el contenido	`400`: la misma comprobación que `/render`, no se envió nada
envío masivo desactivado en toda la cuenta	`409`: no se envió nada
organización sin permiso para enviar	`409`: no se envió nada
dirección en la lista de supresión de la organización	`409`: no se envió nada
por encima del límite de pruebas	`409`: 10 pruebas por hora y por usuario
desconocido, o de otra organización	`404`

El límite de pruebas se comparte con las pruebas de campaña. Diez pruebas por hora y por usuario, campañas y plantillas juntas: gastarlo en /campaigns/{campaignId}/test-send también bloquea este endpoint, y al revés. El límite vive en el servicio, así que la pantalla y la API tiran del mismo presupuesto: ninguna es una forma de saltarse la otra.

Autorización

Rol en la organización	Este endpoint
`OWNER`	Permitido
`ADMIN`	Permitido
`MEMBER`	Rechazado — `403`

Una clave lleva el rol que su creador tiene en esta organización, nunca un rol sobre AgentsMail en sí. Consulta Claves de API.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`email`	string	sí	Adónde va la prueba
`subject`	string	no	Sobrescribe el `defaultSubject` de la plantilla solo para esta prueba
`preheader`	string	no	Hasta 200 caracteres, el texto de vista previa que quieres probar. Una plantilla no guarda ninguno: sin él, el bloque oculto del HTML queda vacío
`content`	string	no	Sobrescribe el HTML de la plantilla solo para esta prueba

Ejemplo

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  "https://www.agentsmail.io/api/v1/templates/$TEMPLATE_ID/test-send" \
  -d '{ "email": "you@example.com" }'

Respuesta

200 OK: la llamada se realizó correctamente.
401 Unauthorized: clave ausente o no válida, o su propietario salió de la organización.
403 Forbidden: el propietario de la clave es member de la organización, no admin.
404 Not Found: no existe ese recurso, o pertenece a otra organización. La API nunca confirma que un id existe a un llamante que no tiene derecho sobre él.
429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.

Campos de la respuesta

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación se realizó correctamente
`data.status`	string	`sent`, o el motivo por el que no salió

Ejemplo de respuesta