Plantillas
Crea versiones de plantillas, publica una por alias y úsalas al enviar.
Crear una plantilla
Crea una versión de plantilla. Las versiones que comparten alias pertenecen a la misma plantilla, y cada alias solo tiene una versión publicada a la vez. Cuando envías un email con template igual a un alias, Emailit usa la versión publicada. Requiere una clave de API con el permiso full.
/templatesCuerpo de la petición
namestringObligatorioEl nombre de la plantilla que se muestra en el panel. Hasta 191 caracteres.
aliasstringObligatorioEl identificador que agrupa las versiones de una plantilla. Hasta 191 caracteres; solo letras minúsculas, números, guiones bajos y guiones (^[a-z0-9_-]+$).
Si ninguna plantilla usa todavía este alias, la nueva versión se publica de inmediato. Si el alias ya existe, la nueva versión se crea sin publicar (published_at es null) y la publicas con Publicar una plantilla.
fromstringEl remitente por defecto, por ejemplo Acme <hello@acme.com>. Hasta 191 caracteres.
subjectstringEl asunto por defecto. Hasta 191 caracteres. Puede contener variables de Temple como {{ first_name }}.
reply_tostring | string[]La dirección de respuesta, o un array de direcciones. Todos los valores deben ser direcciones de email válidas.
htmlstringEl cuerpo HTML.
textstringEl cuerpo en texto plano.
sourcestringEl documento de origen del editor, por ejemplo el JSON de Dragit de una plantilla creada en el editor de arrastrar y soltar. Se guarda tal cual. Con editor: "mjml", es el MJML: Emailit lo valida, lo guarda como un documento MJML y compila html a partir de él.
editorstringEl editor al que pertenece la plantilla: html (por defecto), text, dragit o tiptap. mjml está en alfa y solo está abierto al equipo de Emailit; las demás peticiones reciben 403 con error: "mjml_alpha". Consulta Editores y API de MJML.
Devuelve
Devuelve 201 Created con la plantilla en data y un message de confirmación. La plantilla incluye html, text y source. Emailit también envía un evento de webhook template.created.
Las plantillas MJML también devuelven un objeto mjml con las versiones del documento. Un MJML no válido devuelve 422 con errors.source y diagnostics; consulta Validación.
Si un campo no supera la validación, la respuesta es 400 con message: "Validation failed" y un objeto errors con una clave por campo; por ejemplo, si el alias tiene mayúsculas o la dirección de reply_to no es válida. Si falta name o alias, o si editor tiene un valor no permitido, se devuelve en su lugar el error de validación 400 estándar con un array details. Consulta Errores.
{
"data": {
"id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
"name": "Welcome email",
"alias": "welcome-email",
"from": null,
"subject": "Welcome to Acme, {{ first_name }}",
"reply_to": null,
"html": "<h1>Welcome, {{ first_name }}</h1>",
"text": null,
"source": null,
"editor": "html",
"published_at": "2026-09-30T10:30:00.482119Z",
"preview_url": null,
"created_at": "2026-09-30T10:30:00.482119Z",
"updated_at": "2026-09-30T10:30:00.482119Z"
},
"message": "Template was successfully created."
}{
"message": "Validation failed",
"errors": {
"alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
}
}Obtener una plantilla
Devuelve una versión de plantilla, con su contenido, y enumera en versions las demás versiones del mismo alias. Las plantillas solo se buscan por ID, no por alias. Requiere una clave de API con el permiso full.
/templates/:idParámetros de ruta
idstringObligatorioEl ID de la plantilla, por ejemplo tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.
Devuelve
Devuelve 200 OK con la plantilla en data. Además de los campos de la plantilla, la respuesta incluye un array versions con el id, el name, published_at, created_at y updated_at de cada una de las demás versiones que comparten el alias, de la más reciente a la más antigua. La versión publicada es la que tiene un published_at no nulo.
Devuelve 404 con message: "Template not found" si el ID no existe en tu espacio de trabajo.
{
"data": {
"id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
"name": "Welcome email",
"alias": "welcome-email",
"from": "Acme <hello@acme.com>",
"subject": "Welcome to Acme, {{ first_name }}",
"reply_to": ["support@acme.com"],
"html": "<h1>Welcome, {{ first_name }}</h1>",
"text": "Welcome, {{ first_name }}",
"source": null,
"editor": "html",
"published_at": "2026-09-30T10:30:00.482119Z",
"preview_url": null,
"created_at": "2026-09-28T08:12:45.103882Z",
"updated_at": "2026-09-30T10:30:00.482119Z",
"versions": [
{
"id": "tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f",
"name": "Welcome email (October)",
"published_at": null,
"created_at": "2026-09-30T14:02:11.550731Z",
"updated_at": "2026-09-30T14:02:11.550731Z"
}
]
}
}{
"message": "Template not found"
}Actualizar una plantilla
Actualiza una versión de plantilla. Envía solo los campos que quieras cambiar. La versión conserva su estado de publicación: una versión publicada sigue publicada y un borrador sigue siendo un borrador. Requiere una clave de API con el permiso full.
/templates/:idParámetros de ruta
idstringObligatorioEl ID de la plantilla, por ejemplo tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.
Cuerpo de la petición
namestringEl nombre de la plantilla. Hasta 191 caracteres.
aliasstringEl nuevo alias. Hasta 191 caracteres; solo letras minúsculas, números, guiones bajos y guiones. No puede ser un alias que ya use otra plantilla.
fromstringEl remitente por defecto, por ejemplo Acme <hello@acme.com>. Hasta 191 caracteres. Envía una cadena vacía para borrarlo.
subjectstringEl asunto por defecto. Hasta 191 caracteres. Envía una cadena vacía para borrarlo.
reply_tostring | string[]La dirección de respuesta o un array de direcciones. Envía una cadena vacía para borrarla.
htmlstringEl cuerpo HTML.
textstringEl cuerpo en texto plano.
sourcestringEl documento de origen del editor, por ejemplo el JSON de Dragit. En una plantilla MJML, es el MJML completo: Emailit lo valida y vuelve a compilar html, y se ignora cualquier html que envíes.
editorstringhtml, text, dragit o tiptap. mjml está en alfa y solo está abierto al equipo de Emailit; cambiar el contenido de una plantilla MJML sin acceso a MJML devuelve 403 con error: "mjml_alpha". Cambiarle el nombre o publicarla funciona para todos. Consulta Editores y API de MJML.
Devuelve
Devuelve 200 OK con la plantilla actualizada en data y un message de confirmación. Emailit también envía un evento de webhook template.updated.
Devuelve 400 con message: "Validation failed" y un objeto errors si un valor no es válido, por ejemplo "Alias already exists". Los valores de más de 191 caracteres o un editor desconocido devuelven el error de validación 400 estándar. Devuelve 404 si la plantilla no existe.
To make this version the one used for sending, call Publish a template.
{
"data": {
"id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
"name": "Welcome email",
"alias": "welcome-email",
"from": "Acme <hello@acme.com>",
"subject": "Welcome aboard, {{ first_name }}",
"reply_to": ["support@acme.com"],
"html": "<h1>Welcome, {{ first_name }}</h1>",
"text": "Welcome, {{ first_name }}",
"source": null,
"editor": "html",
"published_at": "2026-09-30T10:30:00.482119Z",
"preview_url": null,
"created_at": "2026-09-28T08:12:45.103882Z",
"updated_at": "2026-10-01T09:15:27.640000Z"
},
"message": "Template was successfully updated."
}{
"message": "Validation failed",
"errors": {
"alias": ["Alias already exists"]
}
}{
"message": "Template not found"
}Listar plantillas
Devuelve la versión publicada de cada plantilla, de la más reciente a la más antigua. Las versiones sin publicar no aparecen en el listado; para ver todas las versiones de un alias, obtén la plantilla. Requiere una clave de API con el permiso full.
/templatesParámetros de consulta
pageintegerEl número de página, empezando por 1. Por defecto, 1.
per_pageintegerPlantillas por página, de 1 a 100. Por defecto, 25.
include_contentbooleanPonlo en true para incluir html, text y source en cada plantilla. Por defecto se omiten para que las respuestas sean pequeñas.
filter[name]stringCoincidencia parcial en el nombre o el alias de la plantilla, sin distinguir mayúsculas y minúsculas.
filter[alias]stringEl alias exacto.
filter[editor]stringEl editor: html, text, dragit, tiptap o mjml (alfa).
matchstringall (por defecto) exige que coincidan todos los filtros key.condition. or exige que coincida cualquiera de ellos. Consulta Filtrado.
sortstringLa clave de ordenación: name, alias, created_at (por defecto), updated_at o published_at.
orderstringLa dirección de la ordenación: asc o desc (por defecto).
Filtros
Los filtros de listado son un único nivel de parámetros de consulta key.condition=value. Consulta Filtrado para ver match, order, direction y la lista de condiciones de cada tipo.
Claves de filtro
| Clave | Tipo | Condiciones | Notas |
|---|---|---|---|
name | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
alias | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
editor | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
subject | string | exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty | |
created_at | date | exact, before, after, empty, not_empty |
Claves de ordenación
Este endpoint ordena con sort igual a una de estas claves y order igual a asc o desc (aquí order=<key> devuelve 400): name, alias, editor, subject, created_at
En este endpoint, order solo acepta asc o desc. Pasa la clave de ordenación en sort, por ejemplo sort=name&order=asc.
Devuelve
Devuelve 200 OK con las plantillas en data y los campos de paginación total_records, per_page, current_page y total_pages. Cada plantilla incluye total_versions, el número de versiones que comparten su alias.
{
"data": [
{
"id": "tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a",
"name": "Welcome email",
"alias": "welcome-email",
"from": "Acme <hello@acme.com>",
"subject": "Welcome to Acme, {{ first_name }}",
"reply_to": ["support@acme.com"],
"editor": "html",
"published_at": "2026-09-30T10:30:00.482119Z",
"preview_url": null,
"total_versions": 3,
"created_at": "2026-09-28T08:12:45.103882Z",
"updated_at": "2026-09-30T10:30:00.482119Z"
}
],
"total_records": 1,
"per_page": 25,
"current_page": 1,
"total_pages": 1
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "Invalid API key"
}Publicar una plantilla
Publica una versión de plantilla y despublica todas las demás versiones con el mismo alias, en una sola transacción. Úsalo para poner en producción un borrador nuevo o para volver a una versión anterior. Requiere una clave de API con el permiso full.
/templates/:id/publishParámetros de ruta
idstringObligatorioEl ID de la versión que se publica, por ejemplo tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f.
Cuerpo de la petición
Sin cuerpo. Publicar una versión que ya está publicada establece un nuevo published_at.
Devuelve
Devuelve 200 OK con la plantilla publicada en data y un message de confirmación. Devuelve 404 si la plantilla no existe.
Emailit envía un evento de webhook template.updated por la versión que has publicado y otro por cada versión que se ha despublicado.
{
"data": {
"id": "tem_2xKyB4qLm7RtV9sNd3HwEa6uC1f",
"name": "Welcome email (October)",
"alias": "welcome-email",
"from": "Acme <hello@acme.com>",
"subject": "Welcome to Acme, {{ first_name }}",
"reply_to": ["support@acme.com"],
"html": "<h1>Welcome, {{ first_name }}</h1><p>Here is your October guide.</p>",
"text": "Welcome, {{ first_name }}. Here is your October guide.",
"source": null,
"editor": "html",
"published_at": "2026-10-01T09:20:04.118502Z",
"preview_url": null,
"created_at": "2026-09-30T14:02:11.550731Z",
"updated_at": "2026-10-01T09:20:04.118000Z"
},
"message": "Template was successfully published."
}{
"message": "Template not found"
}Eliminar una plantilla
Elimina de forma permanente una versión de plantilla. Las demás versiones del mismo alias se conservan. Requiere una clave de API con el permiso full.
/templates/:idParámetros de ruta
idstringObligatorioEl ID de la plantilla, por ejemplo tem_2xKx7M2c9wQe3kHhJ8sVtY1pZ0a.
Devuelve
Devuelve 200 OK con data: null y un message de confirmación. Emailit envía un evento de webhook template.deleted con la versión eliminada. Devuelve 404 si la plantilla no existe.
Si eliminas la versión publicada, ninguna versión de ese alias queda publicada hasta que publiques otra, y los envíos con ese alias fallan. Eliminar un borrador no afecta a la versión publicada. La eliminación no se puede deshacer.
{
"data": null,
"message": "Template was successfully deleted."
}{
"message": "Template not found"
}