Saltar al contenido principal

Actualizar una plantilla de email

PATCH/v1/mail-templates/{template_id}

Para desarrolladores

Descripción​

Actualiza los campos de una plantilla en borrador. Solo cambian los campos incluidos en el body: un campo omitido queda como estaba, y uno enviado con null se vacía.

El diseño completo se reemplaza con el documento que llega en config. Para cambiar una parte, lea el documento con GET /v1/mail-templates/{template_id}, modifíquelo y envíelo completo: un campo que el documento omite se guarda con su valor por defecto, si lo tiene, o sigue heredando si hereda; nunca con el valor que tenía. El recorrido está en Plantillas por API.

Guía relacionada​

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​

Path params:

template_idintegerobligatorio
Identificador de la plantilla.

Body:

{
  "subject": "Nuevo asunto",
  "preheader": null
}
namestring
1–255 caracteres. No acepta null. No puede repetir el de otra plantilla de la instancia, sin importar mayúsculas ni tildes.
subjectstring | null
Asunto, hasta 254 caracteres. null lo vacía.
preheaderstring | null
Hasta 255 caracteres. null lo vacía. Cambiarlo vuelve a generar el HTML de la plantilla.
descriptionstring | null
Descripción libre, hasta 5.000 caracteres. null la vacía.
configobject | null
Documento completo que reemplaza al actual, hasta 256 KB. Un campo omitido se guarda con su valor por defecto, si lo tiene; uno que hereda sigue heredando. null vacía el diseño y su HTML.

Response​

200 OKDevuelve un objeto con los campos que siguen.
idintegersiempre presente
Identificador de la plantilla.
namestringsiempre presente
Nombre de la plantilla.
subjectstring | nullsiempre presente
Asunto del email.
preheaderstring | nullsiempre presente
Texto que la bandeja de entrada muestra junto al asunto.
statusstring, enum: `draft`siempre presente
Solo se actualiza una plantilla en borrador.
descriptionstring | nullsiempre presente
Descripción libre.
providerstring, enum: `fidelizador`siempre presente
Editor de contenido con el que se creó.
htmlstring | nullsiempre presente
HTML generado a partir del diseño.
configobject | nullsiempre presente
Documento completo tal como quedó guardado.
created_atstring (date-time)siempre presente
Fecha y hora de creación.
updated_atstring (date-time)siempre presente
Fecha y hora de la última modificación.
findingsobject[]siempre presente
Advertencias sobre el documento guardado, con la misma forma que en POST /v1/mail-templates.

Errores​

CódigoCuándo
404No existe una plantilla con ese template_id en la instancia (mail_template_not_found).
409La plantilla está publicada (template_published): despublíquela desde el panel antes de editarla. También cuando la plantilla es de un editor que ya no se ofrece y quedó en solo lectura (template_read_only), o cuando ya existe otra plantilla con el nombre nuevo (template_name_taken).
413El body supera el tamaño máximo de una petición, o el documento, una vez completado con sus valores por defecto, supera los 256 KB (request_too_large).
422El body no es válido o el documento tiene errores. errors[].code puede ser invalid_document (un ítem por error, con params.rule y params.uuid), essential_not_supported, template_html_too_large, template_syntax_error (el subject o el preheader no es una plantilla Liquid válida) o value_error (por ejemplo, null en name).

Los códigos de 422 se explican en POST /v1/mail-templates. Detalle en Errores genéricos: conflict y Errores por campo (422).

Notas
  • Una plantilla publicada no se edita. Para cambiarla, despublíquela desde el panel, edítela y vuelva a publicarla.
  • El body puede traer los campos que devolvió la lectura. id, status, html y las fechas se ignoran, así que una integración puede enviar de vuelta la plantilla leída con sus cambios.
  • 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 PATCH "https://$API_HOST/v1/mail-templates/41" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "subject": "Nuevo asunto",
  "preheader": null
}'
Response
{
"id": 41,
"name": "Bienvenida",
"subject": "Nuevo asunto",
"preheader": null,
"status": "draft",
"description": null,
"provider": "fidelizador",
"html": "<!DOCTYPE html><html>…</html>",
"config": {
  "page": {
    "title": "Bienvenida",
    "body": {
      "…": "…"
    },
    "rows": [
      "…"
    ]
  }
},
"created_at": "2026-10-12T14:22:31Z",
"updated_at": "2026-10-12T15:03:10Z",
"findings": []
}