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 se reemplaza entero 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 genera con un valor por defecto, no con el valor que tenía. El recorrido está en Plantillas por API.

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

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 5000 caracteres. null la vacía.

configobject | null

Documento completo que reemplaza al actual, hasta 262144 bytes. Se guarda tal como se envía. 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

—

subjectstring | nullsiempre presente

—

preheaderstring | nullsiempre presente

—

statusstring, enum: `draft`siempre presente

Solo se actualiza una plantilla en borrador.

descriptionstring | nullsiempre presente

—

providerstring, enum: `fidelizador`siempre presente

—

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

—

updated_atstring (date-time)siempre presente

—

findingsobject[]siempre presente

Advertencias y sugerencias sobre el documento guardado, con la misma forma que en `POST /v1/mail-templates`.

Errores

Código	Cuándo
404	No existe una plantilla con ese template_id en la instancia (mail_template_not_found).
409	La 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).
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. errors[].code puede ser invalid_document (un ítem por error, con params.rule y params.uuid), essential_not_supported, template_html_too_large 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": []
}