Saltar al contenido principal

Plantillas por API

Para desarrolladores

Con una API key se puede crear una plantilla, cambiar su diseño, validarlo y ver el correo que resultaría, sin abrir el panel. Es el camino de una integración que arma o ajusta sus correos por su cuenta.

Esta página recorre ese trabajo de principio a fin. Cada endpoint tiene su ficha con todos los campos y errores, y la estructura del documento de una plantilla está en Formato de plantillas. Para que un asistente de IA edite plantillas, vea Plantillas con un asistente de IA.

Antes de empezar​

  • La API key necesita el scope templates:read para leer, validar y previsualizar, y templates:write para crear, editar e importar. Los dos son independientes: una key con templates:write y sin templates:read no puede leer plantillas.
  • Los ejemplos usan las variables $API_HOST, $API_KEY y $SLUG de la introducción de la API, y la herramienta jq para modificar el JSON.
  • Una plantilla nace en borrador, y solo un borrador se puede editar. Las respuestas de error siguen el formato application/problem+json descrito en Errores.

El ciclo de edición​

El diseño de una plantilla es un documento JSON que la API devuelve en el campo config. Se trabaja siempre completo, en tres pasos:

  1. Lea la plantilla con GET /v1/mail-templates/{template_id}.
  2. Modifique su config.
  3. Envíe el documento completo con PATCH /v1/mail-templates/{template_id}.

El documento se envía tal como lo devolvió la lectura, con sus cambios. Un campo que se omite no conserva su valor anterior: se genera con un valor por defecto, que no siempre coincide con el que el editor del panel le daría. Por eso conviene partir de una plantilla que ya existe, creada en el panel, importada desde un HTML o tomada de la biblioteca, y no escribir el documento desde cero.

Conocer el documento​

La especificación del documento está publicada en Formato de plantillas, y la API la entrega con dos consultas de solo lectura:

Para ver un documento completo real, GET /v1/template-catalog/{category}/{name} devuelve una plantilla de la biblioteca sin copiarla.

curl "https://$API_HOST/v1/mail-templates/format/modules/button" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Instance-Slug: $SLUG"

Crear una plantilla​

POST /v1/mail-templates recibe el nombre y, opcionalmente, el asunto, el preheader y el diseño. El diseño puede venir de tres lugares:

  • La biblioteca, con catalog_slug. Es el punto de partida más simple; ver Partir de la biblioteca.
  • Un documento completo, en config, por ejemplo el de otra plantilla que ya leyó.
  • Ninguno: la plantilla se crea solo con el nombre y el diseño se agrega después.

La respuesta es 201 Created, con la plantilla en borrador, su id y el header Location. Un documento con errores responde 422 con todos los errores a la vez, cada uno con su puntero.

Partir de la biblioteca​

GET /v1/template-catalog lista las plantillas de la biblioteca, cada una con su identificador (slug) y su miniatura, y GET /v1/template-catalog/{category}/{name} muestra el documento completo de una sin copiarla. Para crear una plantilla a partir de una, envíe su identificador en catalog_slug:

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", "catalog_slug": "holidays/black-friday"}'

La copia es suya y se edita como cualquier otra plantilla. Revise los findings de la respuesta: una plantilla de la biblioteca puede traer advertencias, por ejemplo un botón sin enlace, que se resuelven con los datos de su campaña.

Leer y modificar el documento​

GET /v1/mail-templates/{template_id} devuelve la plantilla con su diseño en config. Guárdelo en un archivo para modificarlo:

curl -s "https://$API_HOST/v1/mail-templates/41" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Instance-Slug: $SLUG" \
  | jq '.config' > config.json

El documento está formado por filas, columnas y módulos, cada uno con su uuid; la estructura y las propiedades de cada tipo de módulo están en Formato de plantillas y en GET /v1/mail-templates/format/modules/{kind}. Por ejemplo, para cambiar el texto del primer botón del documento:

jq '(first(.. | objects | select(.type? == "fidelizador-modules-button")) | .descriptor.button.label) = "Entrar a mi cuenta"' \
  config.json > config-nuevo.json
  • Conserve el uuid de cada fila, columna y módulo que ya existe. Un bloque nuevo necesita un uuid propio, distinto de todos los demás del documento, y al copiar un bloque la copia y todo lo que contiene necesitan identificadores nuevos.
  • Cambie solo lo necesario y deje el resto del documento como lo devolvió la lectura.

Validar y previsualizar​

Dos endpoints revisan un documento completo sin guardar nada y sin que exista una plantilla:

jq '{config: .}' config-nuevo.json \
  | curl -X POST "https://$API_HOST/v1/mail-templates/validate" \
      -H "Authorization: Bearer $API_KEY" \
      -H "X-Instance-Slug: $SLUG" \
      -H "Content-Type: application/json" \
      --data-binary @-

Si al documento le faltan los enlaces especiales que todo correo lleva, la respuesta lo advierte (abreviada a una advertencia):

{
  "valid": true,
  "findings": [
    {
      "level": "warning",
      "code": "missing_special_link",
      "message": "The email has no `fide:unsubscribe` link.",
      "path": "/page",
      "fix": "Add a link to `fide:unsubscribe`, usually in the footer.",
      "uuid": null,
      "line": null,
      "column": null
    }
  ]
}

Un error impide guardar. Una advertencia y una sugerencia no, y también llegan en el campo findings de la respuesta al guardar. message y fix vienen en inglés.

Enviar el documento completo​

PATCH /v1/mail-templates/{template_id} reemplaza el diseño entero cuando recibe config, y cambia además el nombre, el asunto, el preheader o la descripción que vengan en el cuerpo. Solo cambian los campos enviados.

jq '{config: .}' config-nuevo.json \
  | curl -X PATCH "https://$API_HOST/v1/mail-templates/41" \
      -H "Authorization: Bearer $API_KEY" \
      -H "X-Instance-Slug: $SLUG" \
      -H "Content-Type: application/json" \
      --data-binary @-

La respuesta trae la plantilla guardada, con el HTML que se generó a partir del documento y las advertencias en findings. El cuerpo puede incluir también los campos que devolvió la lectura, como id o status: se ignoran.

El campo essential no se acepta en ningún cuerpo de esta API: una petición que lo trae responde 422 con el código essential_not_supported.

Importar HTML​

POST /v1/mail-templates/html-import convierte el HTML de una campaña en un documento editable por bloques, sin guardar nada. El resultado viene en config, junto con el preheader que se detectó y lo que se descartó (manejadores de eventos, enlaces que ejecutan código y elementos que los clientes de correo no muestran).

La conversión es aproximada: revise el resultado con la vista previa antes de guardarlo. Para guardarlo, envíe ese config a POST /v1/mail-templates y el preheader en preheader, si lo quiere conservar.

Modo HTML crudo​

Para conservar un HTML exactamente como está, créelo en modo HTML crudo, en config:

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": "Mi HTML", "config": {"mode": "html", "rawHtml": "<html><body><p>Hola</p><a href=\"fide:unsubscribe\">Darse de baja</a></body></html>", "page": {"rows": []}}}'
  • El HTML se guarda tal cual, salvo el preheader, que se inserta o se reemplaza. Puede pesar hasta 102400 bytes.
  • Solo se revisa su sintaxis, con tres advertencias que nunca impiden guardar: tag-pair, tagname-lowercase y attr-no-duplication, cada una con su línea y columna. El contenido es responsabilidad de quien lo escribe.
  • Para cambiarlo, envíe el HTML completo en config con PATCH /v1/mail-templates/{template_id}. En el panel no se abre en el editor visual.

Lo que se hace desde el panel​

Publicar, despublicar y eliminar una plantilla se hace desde el panel. Una plantilla publicada se usa en un envío indicando su template_id en POST /v1/mails/send. Una plantilla publicada no se puede editar por API: para cambiarla, despublíquela primero.

En esta página