Crear una plantilla de email

POST/v1/mail-templates

Para desarrolladores

Descripción

Crea una plantilla de email. La plantilla nace siempre como borrador (draft); publicarla, despublicarla y eliminarla se hace desde el panel.

El diseño se entrega de una de dos formas, excluyentes entre sí:

config — el documento completo, que se guarda tal como se envía. Es también la forma de crear una plantilla en modo HTML crudo.
catalog_slug — una plantilla de la biblioteca, que se copia como punto de partida.

Sin ninguna de las dos, la plantilla se crea solo con su nombre, y el diseño se agrega después con PATCH /v1/mail-templates/{template_id}. El recorrido completo, desde crear una plantilla hasta editar su diseño, está en Plantillas por API, y la estructura del documento en Formato de plantillas.

Guía relacionada

Plantillas por API — Cree y edite plantillas desde su integración.
Plantillas de email — Cree y reutilice el contenido de sus envíos.

Autenticación

Authorizationbearer tokenheaderobligatorio: API key con scope templates:write. Formato: Bearer <API_KEY>.
X-Instance-Slugstringheaderobligatorio: Identificador de su instancia. Ver Autenticación.

Request

Body:

{
  "name": "Black Friday 2026",
  "subject": "Ofertas de fin de semana",
  "preheader": "Hasta 40% de descuento este fin de semana",
  "catalog_slug": "holidays/black-friday"
}

namestringobligatorio: Nombre de la plantilla, 1–255 caracteres. Los espacios al inicio y al final se eliminan, y un nombre que queda vacío se rechaza. Es único en la instancia: no puede repetir el de otra plantilla, sin importar mayúsculas ni tildes.
subjectstring | null: Asunto del correo, hasta 254 caracteres.
preheaderstring | null: Texto que la bandeja de entrada muestra junto al asunto, hasta 255 caracteres. Se incluye en el HTML como un bloque oculto al comienzo del cuerpo.
descriptionstring | null: Descripción libre, hasta 5000 caracteres.
configobject | null: Documento completo, hasta 262144 bytes, como lo devuelve `GET /v1/mail-templates/{template_id}`. Se guarda tal como se envía: un campo omitido se genera con un valor por defecto. Para el modo HTML crudo: {"mode": "html", "rawHtml": "<html>…</html>", "page": {"rows": []}}. Excluye a catalog_slug.
catalog_slugstring | null: Identificador de una plantilla de la biblioteca, por ejemplo holidays/black-friday, tal como lo devuelve `GET /v1/template-catalog`. Excluye a config.

Response

201 CreatedDevuelve el objeto creado. El header Location trae su URL (ver Headers).

idintegersiempre presente: Identificador de la plantilla creada.
namestringsiempre presente: —
subjectstring | nullsiempre presente: —
preheaderstring | nullsiempre presente: —
statusstring, enum: `draft`siempre presente: Una plantilla nueva es siempre un borrador.
descriptionstring | nullsiempre presente: —
providerstring, enum: `fidelizador`siempre presente: Editor de contenido de la plantilla.
htmlstring | nullsiempre presente: HTML que la plataforma genera a partir del diseño. null si la plantilla se creó sin diseño.
configobject | nullsiempre presente: Documento completo tal como quedó guardado. Con catalog_slug, es la copia de la plantilla de la biblioteca.
created_atstring (date-time)siempre presente: —
updated_atstring (date-time)siempre presente: —
findingsobject[]siempre presente: Advertencias (warning) y sugerencias (suggestion) sobre el documento guardado. Vacío si no hay ninguna o si la plantilla no tiene diseño.

levelstring, enum: `warning | suggestion`siempre presente: Gravedad. Un documento con errores no se guarda, así que esta respuesta nunca trae error.
codestringsiempre presente: Regla que se señala, por ejemplo placeholder_link.
messagestringsiempre presente: Descripción en inglés.
pathstringsiempre presente: Puntero JSON al valor señalado dentro del documento.
fixstringsiempre presente: Cómo corregirlo, en inglés.
uuidstring | nullsiempre presente: uuid de la fila, columna o módulo afectado, cuando lo hay.
lineinteger | nullsiempre presente: Línea del HTML, solo en una advertencia del modo HTML crudo.
columninteger | nullsiempre presente: Columna del HTML, solo en una advertencia del modo HTML crudo.

Errores

Código	Cuándo
404	`catalog_slug` no corresponde a ninguna plantilla de la biblioteca (`catalog_template_not_found`).
409	La creación de plantillas no está disponible en este entorno (`template_editor_unavailable`). También cuando ya existe otra plantilla con ese nombre (`template_name_taken`): elija otro nombre.
413	El body supera el tamaño máximo de una petición (`request_too_large`).
422	El body no es válido, o el documento tiene errores. En `errors[]`:

Valores de errors[].code propios de este endpoint:

invalid_document — el documento no cumple el formato. Hay un ítem por cada error. pointer señala el valor dentro del body (/config/page/rows/0/columns/0/modules/3/type). params.rule trae la regla incumplida (unknown_module_type, unsafe_link, unsafe_html, …) y params.uuid, el nodo afectado, cuando lo hay. El message incluye cómo corregirlo.
catalog_slug_is_exclusive — se combinó catalog_slug con config.
essential_not_supported — el body trae el campo essential. Esta API recibe el diseño completo en config.
template_html_too_large — en modo HTML crudo, rawHtml supera los 102400 bytes.
value_error — config supera los 262144 bytes, o name queda vacío.

Detalle en Errores genéricos: Errores por campo (422), request-too-large, not-found y conflict.

Notas

Antes de crear, valide. POST /v1/mail-templates/validate y POST /v1/mail-templates/preview revisan y renderizan un documento sin guardar nada.
Un documento con errores no se guarda. La respuesta 422 los trae todos a la vez, cada uno con su puntero, para corregirlos en una sola pasada.
Lo que config omite no se toma del editor. El documento se guarda tal como llegó. Un campo que falta toma un valor por defecto, que no siempre coincide con el del editor del panel. Envíe el documento completo, por ejemplo el que devuelve GET /v1/mail-templates/{template_id} de otra plantilla.
El modo HTML crudo guarda el HTML sin cambios, salvo el preheader, que se inserta o reemplaza. Sus advertencias de sintaxis (tag-pair, tagname-lowercase, attr-no-duplication) llegan en findings y nunca impiden guardar.
El campo html no se acepta como entrada: la plataforma lo genera a partir del diseño, y un html en el body se ignora.

Request

curl -X POST "https://$API_HOST/v1/mail-templates" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "name": "Black Friday 2026",
  "subject": "Ofertas de fin de semana",
  "preheader": "Hasta 40% de descuento este fin de semana",
  "catalog_slug": "holidays/black-friday"
}'

Response

{
"id": 41,
"name": "Black Friday 2026",
"subject": "Ofertas de fin de semana",
"preheader": "Hasta 40% de descuento este fin de semana",
"status": "draft",
"description": null,
"provider": "fidelizador",
"html": "<!DOCTYPE html><html>…</html>",
"config": {
  "page": {
    "title": "Black Friday",
    "body": {
      "…": "…"
    },
    "rows": [
      "…"
    ]
  }
},
"created_at": "2026-10-12T14:22:31Z",
"updated_at": "2026-10-12T14:22:31Z",
"findings": []
}

Descripción​

Guía relacionada​

Autenticación​

Request​

Response​

Errores​

Descripción

Guía relacionada

Autenticación

Request

Response

Errores