> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Plantillas

> Diseños de correo reutilizables y adaptables, construidos con componentes MJML para que se vean bien en todos los clientes de correo y personalizados con Liquid.

![El editor visual de correos, con el árbol de estructura, el correo y la configuración del botón seleccionado](https://www.notifuse.com/docs/assets/screenshots/editor.png)

## Descripción general

Las plantillas de correo se crean en un editor visual de arrastrar y soltar. Usan el framework MJML, para que el correo se vea bien en todos los clientes y dispositivos, y Liquid para personalizarlo con variables como `{{ contact.first_name }}`. Cada cambio crea una nueva versión, así queda constancia del contenido que ya se envió. Tanto los envíos masivos como las notificaciones transaccionales usan plantillas.

## Funciones del editor de plantillas

- Edición con arrastrar y soltar
- Diseños adaptables que se ajustan a pantallas móviles
- Bloques listos para usar: encabezados, pies, botones, imágenes y secciones de contenido
- Ajustes de marca: colores, fuentes, logotipos y estilos
- Vista previa en directo del correo antes de enviarlo

## Crear una plantilla nueva

**Nueva plantilla** abre una ventana donde eliges el punto de partida de la plantilla:

- **Galería**: 15 correos listos para usar, por caso de uso: código de verificación, restablecimiento de contraseña, confirmación de suscripción, invitación a un equipo, recibo de pago, confirmación de pedido, pedido enviado, carrito abandonado, rebajas, newsletter, anuncio de producto, invitación a un evento, bienvenida, recuperación de clientes y confirmación de baja. Haz clic en uno para verlo en escritorio o móvil, con su categoría, su asunto y las variables que debe aportar un envío, y luego en **Usar este modelo**.
- **Tus plantillas**: una copia de una de tus plantillas, que conserva su modo de editor.
- **Simple**: un logotipo, un párrafo y el pie.

Un modelo de la galería llega en el idioma predeterminado del espacio de trabajo, más una traducción por cada otro idioma del espacio de trabajo que cubra la galería (inglés, francés, español, alemán, catalán, portugués de Brasil, japonés e italiano). Su nombre, categoría, asunto, texto de vista previa y datos de prueba vienen rellenados, y el logotipo y el nombre del espacio de trabajo sustituyen a los del ejemplo cuando el espacio de trabajo los tiene; el remitente se elige en **Configuración**. Si abres la ventana desde una newsletter, una lista o una notificación transaccional, solo muestra los modelos de la categoría que hace falta.

Las imágenes de la galería son marcadores de posición que sirve tu instancia de Notifuse, en `https://<your API endpoint>/console/gallery/`. Sustitúyelas por las tuyas antes de enviar: un destinatario solo las ve mientras tu instancia sea accesible desde Internet en esa dirección.

## Modos de editor

Al crear una plantilla, eliges cómo se escribe su correo:

- **Visual**: el editor de arrastrar y soltar, donde los bloques, los estilos y las variables de Liquid se editan en su sitio.
- **Código (MJML)**: escribes tú el MJML, con Liquid, en un editor de código con vista previa en directo.

El modo de editor se fija al crear la plantilla y no se puede cambiar después. Para pasar un diseño al otro editor, crea una plantilla nueva en ese modo y copia el contenido con el menú **Importar / Exportar** de cada editor:

- **De código a visual**: en la plantilla de código, usa **Exportar MJML**; en la nueva plantilla visual, usa **Importar → MJML** con ese archivo.
- **De visual a código**: en la plantilla visual, usa **Exportar → MJML**; en la nueva plantilla de código, usa **Importar MJML** con ese archivo.

Revisa la vista previa después de copiar. El editor visual rechaza los componentes MJML que no admite. El Liquid colocado entre bloques se conserva: un archivo MJML exportado por Notifuse recupera sus bloques Liquid y sus condiciones de visualización, y en cualquier otro archivo MJML, un fragmento con Liquid entre bloques (por ejemplo, un bucle `{% for %}` alrededor de varias secciones) se convierte en un bloque Liquid que guarda ese código tal cual, y luego lo editas como código. En el sentido contrario, escribe el Liquid dentro de los enlaces con comillas simples (`{{ link | append: '?ref=mail' }}`): el texto entre comillas dobles no sobrevive a la exportación.

La nueva plantilla tiene su propio ID. Apunta a ella tus envíos masivos, notificaciones transaccionales y automatizaciones, y luego elimina la antigua.

## Títulos

Los bloques de texto del editor visual admiten títulos de verdad, de **Título 1** a **Título 6**, para que los lectores de pantalla puedan listar las secciones de un correo y saltar de una a otra (WCAG 2.2, criterio de conformidad 1.3.1). Elige el nivel de la línea actual en el menú **Estilo de texto**, al principio de la barra de herramientas, o escribe `# ` (o `## `, `### `…) al principio de una línea. El lienzo muestra el nivel de cada título a su lado; esa marca no forma parte del correo.

**Estructura**: un título debería bajar como mucho un nivel respecto al anterior (un H2 después de un H1, no un H3). El editor nunca rechaza un nivel, porque mover u ocultar un bloque puede cambiar el orden más adelante, pero marca el nivel que se salta uno: junto al nivel en el menú, con una insignia en el bloque de texto y en un recuadro **Estructura de títulos** encima de la vista previa. Ese recuadro lee el correo tal como se envía, incluidos los títulos que escriben los bloques Liquid.

**Aspecto**: el tamaño, el grosor, el interlineado y el espaciado de cada nivel, y si quieres su fuente y su color, se definen una vez por plantilla en **Atributos predeterminados → Títulos**. Notifuse los escribe en cada título al enviar, así todos los clientes de correo los muestran. Un título toma la fuente y el color de su bloque de texto, salvo que su nivel defina los suyos.

El editor guarda estos estilos en un bloque `mj-style` de la plantilla, que se añade con el primer título. Si editas ese bloque a mano, la sección **Títulos** muestra un mensaje y deja de editarlo. Las plantillas que ya tenían títulos conservan su aspecto hasta que cambies **Títulos**.

## Biblioteca de bloques guardados

En el editor visual, la pestaña **Biblioteca**, junto a **Estructura**, reúne los bloques guardados en el espacio de trabajo, en forma de vistas previas, del más reciente al más antiguo, con un buscador y un filtro de secciones y bloques de contenido. Debajo están los bloques básicos: sección, contenedor, texto, imagen, botón, separador, espaciador, redes sociales, HTML sin procesar y Liquid.

Para añadir un bloque al correo:

- **Insertar**: pasa el puntero sobre un bloque guardado y haz clic en **Insertar**, o haz clic en un bloque básico. Se coloca después del bloque seleccionado (o al final del correo si no hay nada seleccionado) y pasa a ser el bloque seleccionado; la confirmación permite deshacerlo. Cuando la selección no admite el bloque, su descripción emergente dice qué seleccionar, por ejemplo una columna para un texto.
- **Arrastrar**: arrastra un bloque guardado o básico sobre el correo. Una línea indica dónde caerá, o un recuadro discontinuo si es una columna o un contenedor vacíos. Sobre un sitio que no lo admite, una etiqueta explica por qué, como "Va dentro de una columna" para un texto soltado entre secciones. Mantén el puntero cerca del borde superior o inferior del correo para desplazarlo, y pulsa Escape para cancelar. Los bloques solo se arrastran sobre el correo, no sobre el árbol de estructura.

Para guardar un bloque, selecciónalo y usa el botón de guardar de su barra de herramientas. El diálogo propone un nombre a partir del contenido del bloque, o puede reemplazar un bloque guardado del mismo tipo. Los bloques guardados están disponibles en todas las plantillas del espacio de trabajo. Una plantilla que ya contiene un bloque guardado conserva su propia copia, que no cambia si reemplazas o eliminas el bloque guardado. Después de guardar un bloque nuevo, la biblioteca se abre sobre él.

Para gestionar un bloque guardado, abre el menú **…** de su tarjeta en la biblioteca. El menú aparece en el editor abierto desde la página de plantillas, para los miembros que pueden editar plantillas:

- **Renombrar**: escribe el nombre nuevo y pulsa Intro, o Escape para mantener el anterior.
- **Reemplazar por el bloque seleccionado**: antes, selecciona en el correo un bloque del mismo tipo.
- **Duplicar**: añade una copia, con el nombre del bloque seguido de "(copia)".
- **Eliminar**: lo quita de la biblioteca para todas las plantillas del espacio de trabajo.

Las plantillas que ya contienen el bloque no cambian.

![La pestaña Biblioteca del editor visual, con los bloques guardados como vistas previas e Insertar al pasar el puntero](https://www.notifuse.com/docs/assets/screenshots/templates_saved_blocks.png)

Los botones **+** del árbol de estructura también muestran todos los bloques guardados en su pestaña **Bloques guardados**. Primero aparecen los bloques que pueden ir en ese sitio, con una vista previa al pasar el puntero. Los demás salen en gris bajo "No disponible aquí", con el motivo, como "Va dentro de una columna". Los botones **+** se abren en la última pestaña que usaste.

## Uso

En Notifuse, las plantillas se usan para:

- **Envíos masivos**: campañas de correo enviadas a tus listas de contactos
- **Notificaciones transaccionales**: correos automáticos que disparan las acciones de los usuarios
- **Correos de doble confirmación**: se envían cuando un contacto anónimo se suscribe a una lista
- **Correos de bienvenida**: se envían cuando un contacto confirma su suscripción a una lista
- **Confirmaciones de baja**: se envían cuando un contacto se da de baja

![La página de plantillas, con la categoría de cada plantilla, dónde se usa, su remitente y su última versión](https://www.notifuse.com/docs/assets/screenshots/templates.png)

## Eliminar una plantilla

Al eliminar una plantilla, desaparece de la lista de plantillas y de todos los selectores de plantilla, pero Notifuse la conserva con todas sus versiones: los mensajes ya enviados se generaron a partir de ellas, y el historial de mensajes y los informes de envíos masivos las siguen mostrando.

Por eso una plantilla eliminada conserva su ID. No se puede crear una plantilla nueva con el mismo ID, y `templates.update` de la API responde `404` para ella. Dale otro ID a la nueva plantilla.

Eliminar una plantilla sí retira las [versiones web](#view-in-browser) de los correos enviados con ella.

Las plantillas que gestiona una integración, como los correos de autenticación de [Supabase](https://www.notifuse.com/es/docs/integrations/supabase.md), no se pueden eliminar.

## Versión de texto plano

Cada correo que envía Notifuse lleva dos versiones de su contenido: el HTML y una versión de texto plano generada a partir de él, salvo que escribas la tuya. Los clientes de correo que solo muestran texto, algunos relojes y los lectores de pantalla muestran la versión de texto, y los filtros de spam tratan mejor un correo con las dos versiones que uno solo en HTML.

Por defecto, la versión de texto se genera en cada envío a partir del HTML final, así que no hay nada que escribir ni que mantener al día:

- los títulos y los párrafos conservan sus saltos de línea, y las listas pasan a `- item` o `1. item`;
- un enlace se convierte en su texto seguido de su URL entre paréntesis, como `Shop the sale (https://example.com/sale)`; una imagen con enlace usa su texto `alt` como texto del enlace;
- se omiten el contenido oculto (el texto de vista previa de la bandeja de entrada, los elementos con estilo `display:none`) y los píxeles de seguimiento.

Sus enlaces son los del HTML, con el mismo seguimiento de clics y los mismos parámetros UTM, decididos para cada destinatario igual que en el HTML, y un clic en la versión de texto cuenta como cualquier otro. Si tu proveedor de correo reescribe los enlaces para su propio seguimiento de clics (SendGrid, Mailgun o Postmark, cuando lo activas en su lado), también reescribe los de la versión de texto. Un correo cuyo HTML no tiene ningún texto, como una sola imagen sin `alt`, se envía solo en HTML.

Para verla antes de enviar, abre el modo **Versión de texto** junto a **Editar** y **Vista previa** en el editor visual, la pestaña **Versión de texto** del editor MJML o la pestaña **Versión de texto** de la vista previa de la plantilla. Muestran el texto generado con tus datos de prueba. Por la API, [`templates.compile`](https://www.notifuse.com/docs/api-reference/compile-template.md) lo devuelve en el campo `text`.

### Escribir la tuya

La versión automática sirve para la mayoría de los correos. Si quieres otra redacción, como un texto más corto o sin los enlaces que repite el diseño, elige **Personalizado** en el modo **Versión de texto** (o en la pestaña **Versión de texto** del editor MJML) y escribe el texto tú. Parte de la versión automática, con las variables incluidas, así que lo editas en lugar de empezar desde cero.

- **Liquid funciona como en el asunto.** `{{ contact.first_name }}`, las condiciones y los bucles se procesan para cada destinatario. Un `{{` literal debe ir dentro de `{% raw %}…{% endraw %}`. El texto se comprueba al guardar: un error de sintaxis de Liquid, una etiqueta `{% include %}` o `{% render %}` o un texto de más de 64 KB se rechazan con el motivo.
- **Sus enlaces se envían tal como están escritos.** Los enlaces de un texto personalizado no tienen seguimiento de clics ni parámetros UTM. El texto de un correo de marketing debería conservar `{{ unsubscribe_url }}`, y el de un correo de doble confirmación, `{{ confirm_subscription_url }}`; el editor te lo recuerda y avisa al guardar si falta el enlace.
- **No sigue al correo.** Un texto personalizado no se actualiza cuando cambias el HTML. **Empezar de nuevo desde la versión automática** lo sustituye por un punto de partida nuevo; elegir **Automática** lo elimina.
- **Un texto por idioma.** El texto que escribes en el editor principal es para el idioma predeterminado. Cada traducción tiene el suyo, que se escribe en su editor de la pestaña **Traducciones**; un idioma sin texto propio recibe la versión automática de su propio HTML, nunca el texto del idioma predeterminado.

> [!NOTE]
>
> El punto de partida conserva el Liquid escrito dentro de los bloques de texto. Conserva el texto de un [bloque condicional](#conditional-blocks), pero no su condición, y las condiciones y los bucles colocados entre bloques a menudo no se trasladan, según el diseño. El editor avisa cuando el punto de partida tiene menos etiquetas Liquid que el correo: revisa el texto y añade a mano lo que falte antes de guardar. Un texto personalizado no tiene condiciones de visualización: el texto de un bloque condicional llega a todos los destinatarios, salvo que lo envuelvas tú en `{% if %}`.

Si un texto personalizado no se puede procesar al enviar el correo, el correo sale con la versión automática y la vista previa de la plantilla explica el motivo. Por la API, el texto personalizado es el `email.text` de la plantilla (y `translations.<language>.email.text`); `templates.compile` lo recibe como `text` e indica en `text_source` si el texto devuelto es `custom` o `auto`.

## Bloques condicionales

Un bloque del editor visual puede enviarse solo a algunos destinatarios: dale una **condición de visualización** sobre los datos del correo, como "`order.total` es mayor que 100" o "`contact.custom_string_1` es igual a `vip`". Los destinatarios para los que la condición no se cumple reciben el correo sin el bloque.

Selecciona un bloque y usa **+ Condición** en la franja **Condición de visualización**, arriba de su configuración. Una condición es una lista de reglas, cada una formada por una variable, un operador y, para la mayoría de los operadores, un valor. Elige si se deben cumplir **todas las** reglas o **al menos una de las** reglas; una condición admite hasta 20 reglas.

Se pueden poner condiciones en secciones, contenedores, textos, imágenes, botones, separadores, espaciadores, bloques de redes sociales y bloques de HTML sin procesar. Una condición en una sección o un contenedor oculta todo lo que contiene. Las columnas y los grupos no pueden tener una, porque quitar una columna rompería el ancho de las demás; pon la condición en la sección o en los bloques de dentro de la columna. Un bloque que contiene un bloque Liquid tampoco puede tenerla: ocultarlo quitaría también el bloque Liquid, que puede contener la mitad de una etiqueta como `{% if %}` cuyo `{% endif %}` está en otro sitio. Saca antes el bloque Liquid. Por la misma razón, el editor no deja poner un bloque Liquid dentro de un bloque que tiene una condición.

### Variables

Una variable es una ruta sin llaves, tal como la escribirías dentro de `{{ }}`: `contact.first_name`, `order.total`, `order.items.size`. `.empty` y `.to_liquid` no se pueden usar en una ruta; para comprobar si una lista o un texto están vacíos, usa **es falso o vacío**. Todas las variables de los datos del correo están disponibles: los [campos del contacto](#contact-variables), los `data` de una [llamada a la API transaccional](https://www.notifuse.com/es/docs/features/transactional-api.md), los [data feeds](https://www.notifuse.com/es/docs/features/broadcast-campaigns.md#data-feeds). Las variables asignadas con Liquid dentro del correo (un `{% assign %}` en un bloque Liquid o de HTML) no lo están, porque una condición lee los datos con los que se envía el correo, no su contenido.

### Operadores

| Operador                                                               | Se cumple cuando la variable                                                                                                                                                 |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| es verdadero                                                           | es `true`, o el texto `true`                                                                                                                                                 |
| es falso o vacío                                                       | es `false`, está vacía, solo tiene espacios o no existe                                                                                                                      |
| está definido / no está definido                                       | tiene un valor, o no tiene ninguno: no existe, es `null`, un texto o una lista vacíos, un objeto vacío o un texto que solo tiene espacios (`false` y `0` sí están definidos) |
| es igual a / no es igual a                                             | es exactamente el texto del valor: `vip` no es igual a `VIP`                                                                                                                 |
| contiene / no contiene                                                 | en un texto, contiene el valor; en una lista, tiene un elemento igual al valor; en un objeto, tiene un campo con ese nombre; un número o un booleano no contiene nada        |
| es mayor que, es mayor o igual que, es menor que, es menor o igual que | es un número, o un texto que lo es (`"150"`), comparado con el valor                                                                                                         |

Algunos detalles:

- **Variables ausentes**: una regla sobre una variable que no está en los datos es falsa, salvo **es falso o vacío**, **no está definido**, **no es igual a** y **no contiene**, que se cumplen.
- **Números y booleanos**: **es igual a** `100` también coincide con el número `100`, y **es igual a** `true` coincide con el booleano `true`. Las comparaciones (**es mayor que** y las demás) necesitan como valor un número de 15 cifras como máximo antes del separador decimal; una variable que no es un número las hace falsas.
- **Los valores de texto** son libres: vale cualquier carácter, salvo los delimitadores de Liquid `{{`, `}}`, `{%` y `%}`.

### Comprobar una condición

El editor de condiciones muestra, para cada regla y para la condición completa, su resultado con los datos de prueba de la plantilla, y avisa cuando falta una variable en esos datos. La vista previa oculta los bloques que ocultarían tus datos de prueba e indica cuántos son. En el árbol de capas y en el lienzo, un icono marca los bloques que tienen una condición.

### Traducciones y exportaciones

Cada [traducción](#translations) tiene su propio contenido y, por tanto, sus propias condiciones: defínelas también en la traducción. **Restablecer traducción** copia con el contenido predeterminado también sus condiciones.

**Exportar → MJML** escribe cada condición como Liquid alrededor de su bloque, así una plantilla de código creada a partir de la exportación envía los mismos bloques. Hay una diferencia: en la plantilla de código, la condición también ve las variables que asigna el propio Liquid del correo, como un `{% assign %}` en un bloque Liquid o la variable de un bucle `{% for %}` alrededor del bloque. Si vuelves a importar ese archivo en el editor visual, los bloques recuperan sus condiciones: la exportación marca cada condición con un comentario Liquid, que no genera nada. Un archivo exportado antes de la versión 44.0 no tiene esas marcas: cada condición vuelve dentro de un bloque Liquid, junto con su bloque.

El MJML de una plantilla de código pasa entero por Liquid, y Liquid acepta como máximo 100 KB (102.400 bytes) de una vez. Cada condición exportada añade alrededor de su bloque entre unos cientos y unos miles de caracteres de Liquid, según sus reglas, así que un correo con muchas condiciones puede superar el límite una vez exportado, y entonces su plantilla de código no compila. Deja ese correo en el editor visual, donde las condiciones no cuentan para el límite.

Por la API, un bloque de `visual_editor_tree` lleva su condición en `display_condition`:

```json
{
  "type": "mj-section",
  "display_condition": {
    "match": "all",
    "rules": [
      { "variable": "order.has_image", "operator": "is_true" },
      { "variable": "order.total", "operator": "gt", "value": "100" }
    ]
  },
  "children": []
}
```

Los operadores son `is_true`, `is_blank`, `is_present`, `is_absent`, `eq`, `neq`, `contains`, `not_contains`, `gt`, `gte`, `lt` y `lte`, y `match` vale `all` o `any`. Una condición en un bloque que no puede tenerla, o una condición no válida, se rechaza con un `400`.

## Traducciones

Una plantilla puede llevar una versión de su contenido por idioma. Notifuse elige la versión al enviar según el campo `language` del contacto, así un solo envío masivo o una sola notificación transaccional sirve para todos los idiomas que hayas escrito, sin ramificar nada en tus automatizaciones ni en tus llamadas a la API.

### Activar idiomas en el espacio de trabajo

Solo se ofrecen traducciones para los idiomas que el espacio de trabajo tiene activados. Abre **Configuración → General**, panel **Idioma y zona horaria**:

- **Idiomas admitidos**: los idiomas en los que trabaja este espacio de trabajo. Añade todos los idiomas para los que pienses escribir plantillas; un idioma que no esté aquí no puede tener traducción.
- **Idioma predeterminado**: el idioma del contenido principal de una plantilla, y la versión que recibe un contacto cuando no hay nada que encaje mejor. Cada espacio de trabajo tiene exactamente uno.

Los códigos de idioma son códigos ISO de dos letras, como `en`, `fr`, `de`, `es`. El idioma predeterminado debe ser uno de los idiomas admitidos, y la lista debe tener al menos uno.

> [!NOTE]
>
> Con un solo idioma admitido, el editor de plantillas no muestra ningún control de traducción. La pestaña **Traducciones** aparece en cuanto el espacio de trabajo admite más de un idioma.

### Escribir una traducción

Al crear o editar una plantilla, el editor tiene dos pestañas: **Plantilla**, en el idioma predeterminado del espacio de trabajo, y **Traducciones**, que muestra cada uno de los demás idiomas admitidos. Abre un idioma para escribir su propio asunto, su texto de vista previa y su cuerpo, con el mismo editor visual, el mismo modo de código MJML y las mismas variables de Liquid que el idioma predeterminado. El remitente y la dirección de respuesta se definen una sola vez, en la plantilla, y todas las traducciones se envían con ellos. **Restablecer traducción** copia el contenido del idioma predeterminado en la traducción como punto de partida y sustituye lo que hubiera.

Un idioma sin traducción se omite al enviar, así que no hace falta traducir una plantilla a todos los idiomas admitidos de una vez.

### Qué versión recibe un contacto

Al enviar, Notifuse lee el `language` del contacto:

1. Si está vacío o es el idioma predeterminado del espacio de trabajo, el contacto recibe el **contenido predeterminado**.
2. Si la plantilla tiene una traducción para ese idioma, el contacto recibe **esa traducción**.
3. Si no, el contacto recibe el **contenido predeterminado**.

El contenido predeterminado siempre es la alternativa, así que una traducción que falta nunca deja a un contacto sin correo. Define el idioma de un contacto al importarlo, por la API (`language` en `contacts.upsert`) o desde un formulario de suscripción; consulta [Contactos](https://www.notifuse.com/es/docs/features/contacts.md).

Para revisar un idioma concreto antes de enviar, la vista previa de la plantilla y el diálogo de envío de prueba tienen un selector **Idioma**.

> [!NOTE]
>
> **En autoalojado, añadir un idioma a una plantilla o editar el contenido de una traducción existente requiere una [clave de licencia](https://www.notifuse.com/es/docs/self-hosting/licence.md).** Las traducciones ya guardadas se siguen enviando sea cual sea el estado de la licencia, editar el resto de una plantilla que las lleva nunca se rechaza y quitar una traducción siempre está permitido. Notifuse Cloud incluye las traducciones de plantillas desde el plan Starter ([detalles](https://www.notifuse.com/es/docs/self-hosting/licence.md#on-notifuse-cloud)).

## Sintaxis de Liquid

Notifuse usa Liquid para insertar contenido dinámico en los correos. Las variables van entre dobles llaves y se sustituyen por los datos reales al enviar.

> [!NOTE]
>
> Liquid se evalúa en la plantilla que escribes, no en tus datos. Un valor que viene de un campo del contacto, de un data feed o de una llamada a la API se inserta como texto: si contiene `{{ ... }}` o `{% ... %}`, ese texto se muestra tal cual y no se ejecuta como Liquid. Pon las etiquetas de combinación en la plantilla y pasa valores simples en los datos.

### El HTML de tus datos se escapa

En el HTML de un correo, toda salida (`{{ }}`, `echo` y `cycle`) se escapa: un valor se muestra como el texto que contiene, nunca se interpreta como HTML. Un contacto que escribe `<a href="https://example.com">` como nombre ve esos caracteres en el correo, no un enlace. El asunto y la versión de texto no son HTML, así que no se escapan.

Cuando un valor es HTML a propósito, como un [data feed](https://www.notifuse.com/es/docs/features/broadcast-campaigns.md#data-feeds) que devuelve un bloque de HTML, escríbelo con el filtro `raw`:

```liquid
{{ global_feed.article_html | raw }}
```

Usa `raw` solo con datos que controlas. En un campo del contacto, o en cualquier cosa que pueda rellenar un formulario o quien llama a la API, permite que ese valor añada enlaces y marcado a tu correo.

Algunas salidas no se escapan una segunda vez:

- **Ya escapadas**: `{{ name | escape }}` se escapa una sola vez, también cuando le siguen `newline_to_br`, `strip` o `truncate`. `{{ bio | escape | newline_to_br }}` conserva sus saltos de línea.
- **HTML capturado**: el texto de un `{% capture %}` se escribe tal cual: sus propias salidas se escaparon al capturarlo, y el resto es el marcado de tu plantilla.

El escape sirve para el texto y los atributos HTML:

- **CSS y scripts**: un valor escrito en CSS (`mj-style`, un elemento `<style>`) o en un script necesita `raw` y debe venir de datos de confianza, como tus ajustes de marca, nunca de los contactos.
- **Atributos entre comillas**: una salida dentro del valor de un atributo solo es segura entre comillas. Escribe `class="{{ value }}"`, no `class={{ value }}`.

### Un error de Liquid detiene el correo

Cuando Liquid no puede evaluar una parte de un correo, el correo no se envía: el envío falla con el error, y la vista previa y el envío de prueba lo muestran, para que puedas corregir la plantilla antes de que le llegue a nadie. Esto vale para el HTML, el asunto y la versión de texto. Antes, el correo salía con un texto `Liquid error: ...` dentro.

Las causas habituales son:

- **Un texto comparado con un número**: `{% if contact.custom_string_1 >= 10 %}` falla cuando el campo contiene `"12"` (`comparison of String with 10 failed`). Compara un campo numérico, o compara con un texto entre comillas: `{% if contact.custom_string_1 == "12" %}`.
- **Un operador desconocido**: `{% if x = 1 %}` falla (`Unknown operator =`). Escribe `==`.
- **Un filtro que falla**: `{{ order.total | divided_by: order.count }}` falla cuando `order.count` es 0 (`divided by 0`), igual que un filtro al que le falta un argumento, como `{{ contact.first_name | replace }}` (`wrong number of arguments`). Protege el valor: `{% if order.count > 0 %}{{ order.total | divided_by: order.count }}{% endif %}`.

Por la API, `transactional.send` y `broadcasts.sendToIndividual` responden a ese envío con un `422` cuyo `error` es el error de Liquid.

Un campo que falta no es un error: `{{ contact.first_name }}` no muestra nada cuando está vacío, y `{% if order.total > 50 %}` es falso cuando no hay `order`. Los bloques condicionales nunca provocan un error. En los temas de blog, el error se sigue mostrando en la página.

### Variables del contacto

El objeto `contact` contiene el perfil completo del contacto, así que puedes usar cualquier campo del contacto para personalizar:

```liquid
Hello {{ contact.first_name }}!

Your account email: {{ contact.email }}
Full name: {{ contact.first_name }} {{ contact.last_name }}
```

**Ejemplo de salida:**

```
Hello John!

Your account email: john.doe@example.com
Full name: John Doe
```

### Variables de la lista

Haz referencia a la información de la lista de correo:

```liquid
You're subscribed to: {{ list.name }}
List ID: {{ list.id }}
```

**Ejemplo de salida:**

```
You're subscribed to: Newsletter
List ID: newsletter
```

### URL del sistema

Usa URL generadas de antemano para las acciones habituales:

#### Enlace de baja

```liquid
<a href="{{ unsubscribe_url }}">Unsubscribe from this list</a>
```

Al abrir este enlace, el contacto se da de baja de la lista al momento y ve el [centro de notificaciones](https://www.notifuse.com/es/docs/features/notification-center.md). Los clientes de correo también pueden mostrar su propio botón para darse de baja, a partir de la cabecera `List-Unsubscribe` que Notifuse añade a cada correo enviado a una lista, salvo en los envíos masivos que también van a los contactos dados de baja de la lista.

Para comprobar estos enlaces y la cabecera antes de enviar, elige una **Lista de correo** al enviar un correo de prueba; una prueba enviada desde un envío masivo ya tiene elegida la lista del envío. La prueba lleva entonces los enlaces de esa lista y, como el envío masivo, la cabecera `List-Unsubscribe`, y funcionan: darse de baja o confirmar desde la prueba, o un rebote o una queja registrados sobre ella, cambia la suscripción del destinatario de prueba a la lista. El campo **Lista de correo** no se ofrece para las notificaciones transaccionales, cuyos envíos reales no llevan enlaces de lista. Sin lista, los enlaces de baja de la prueba no llevan a ninguna lista real y la prueba no tiene cabecera `List-Unsubscribe`.

#### Confirmación de suscripción

```liquid
<a href="{{ confirm_subscription_url }}">Confirm your subscription</a>
```

#### Centro de notificaciones

```liquid
<a href="{{ notification_center_url }}">Manage your preferences</a>
```

#### Preferencias de seguimiento del correo

```liquid
<a href="{{ tracking_preferences_url }}">Choose what we track</a>
<a href="{{ tracking_optout_url }}">Stop tracking my opens and clicks</a>
```

El primero abre el diálogo de seguimiento del correo del centro de notificaciones; el segundo pide al contacto que confirme en ese diálogo y luego rechaza el seguimiento de aperturas y clics. Consulta [Seguimiento del correo](https://www.notifuse.com/es/docs/features/email-tracking.md#template-links).

#### Ver en el navegador

```liquid
{% if view_in_browser_url != blank %}
  <a href="{{ view_in_browser_url }}">View this email in your browser</a>
{% endif %}
```

El enlace abre la versión web del correo, para los destinatarios cuyo cliente de correo lo muestra mal. En el editor visual, selecciona un texto, abre el editor de enlaces y elige el tipo de enlace **Versión web del email**.

- **Disponible en envíos masivos y automatizaciones.** Los correos transaccionales y de doble confirmación dejan la variable vacía, salvo que una llamada a la API transaccional defina `view_in_browser_url` en sus propios datos. Protege el enlace como arriba en una plantilla que compartan.
- **Solo donde se usa.** Solo tienen versión web los correos cuya plantilla usa la variable. No hay ningún ajuste del espacio de trabajo.
- **El correo tal como se envió.** La página se genera a partir de la versión de la plantilla y de los datos de ese envío, en el idioma del contacto. Editar la plantilla después no la cambia.
- **En la página no se registra nada.** Verla no registra ninguna apertura, y sus enlaces no registran ningún clic; conservan los parámetros UTM del envío. Con el seguimiento de clics activado, el clic en el enlace del propio correo cuenta como un clic, igual que cualquier otro enlace.
- **Se retira con la plantilla o con el contacto.** [Eliminar la plantilla](#deleting-a-template) o [eliminar el contacto](https://www.notifuse.com/es/docs/features/contacts.md#deleting-a-contact) hace que la página responda "This email is no longer available".

Cualquiera que tenga el enlace puede abrir la página, como pasa con un correo reenviado. Muestra lo mismo que el correo, incluidos los enlaces de baja y del centro de notificaciones del contacto, así que quien la tenga puede dar de baja a ese contacto. La versión web de cada correo se abre como máximo 30 veces por minuto: no está pensada como enlace de archivo público.

El enlace firma el dominio con el que se envió, la [URL de endpoint personalizada](https://www.notifuse.com/es/docs/features/workspaces.md#custom-endpoint-url) de tu espacio de trabajo o la dirección `API_ENDPOINT`, y la página solo se abre ahí y en la dirección `API_ENDPOINT`. Así, el dominio personalizado de otro espacio de trabajo no puede mostrar tu correo bajo su propia dirección. Lo que esto no cubre:

- La dirección `API_ENDPOINT` abre la versión web de todos los espacios de trabajo, porque cualquier enlace puede recurrir a ella.
- Los espacios de trabajo que ya compartían un dominio personalizado antes de la 44.0 muestran en él las versiones web de los demás.
- Cualquiera que tenga el enlace puede descargar la página y publicar una copia en otro sitio, como con cualquier correo que reciba.
- Se comprueba que un dominio personalizado apunta a Notifuse, no que pertenece al espacio de trabajo que lo guarda. El primer espacio de trabajo que guarda un dominio se queda con él; consulta [URL de endpoint personalizada](https://www.notifuse.com/es/docs/features/workspaces.md#custom-endpoint-url).

Cuando tu espacio de trabajo cambia de dominio personalizado, los enlaces enviados con el antiguo siguen funcionando mientras el dominio antiguo apunte a Notifuse, hasta que otro espacio de trabajo lo ocupe; dejan de funcionar unos minutos después. Una redirección desde el dominio antiguo solo los mantiene si va a la dirección `API_ENDPOINT`, no al nuevo dominio personalizado.

Detrás de un proxy inverso, reenvía la cabecera `Host` original, o pon su valor en `X-Forwarded-Host`: cuando esa cabecera está presente, la página se evalúa solo con ella. Un proxy que sustituye `Host` por su dirección de upstream, como `notifuse:8080`, hace que todas las versiones web respondan "This email is no longer available". Uno que la sustituye por el host de `API_ENDPOINT` desactiva la regla: todos los dominios personalizados muestran entonces las versiones web de todos los espacios de trabajo.

La página no ejecuta ningún script y está separada de la consola, aunque las dos se sirven desde el mismo dominio.

En la vista previa de una plantilla y en un correo de prueba, el enlace abre una página que indica que la versión web existirá cuando el correo se envíe a un contacto.

> [!NOTE]
>
> Las versiones web se sirven bajo `/v/`. En un [blog](https://www.notifuse.com/es/docs/blog/setup.md) servido desde un dominio personalizado, no se puede acceder a una categoría cuyo slug sea `v`: dale otro slug.

### Variables de automatización

Un correo enviado por una automatización también recibe:

- `{{ automation_id }}` y `{{ automation_name }}`
- `{{ trigger_event }}`: el evento que inició el recorrido. `{{ trigger_event.kind }}` es su tipo (`custom_event.cart_abandoned`, `list.subscribed`, `email.link_clicked`…) y `{{ trigger_event.occurred_at }}`, el momento en que ocurrió. Para un evento personalizado, `{{ trigger_event.name }}`, `{{ trigger_event.external_id }}` y sus propiedades, `{{ trigger_event.properties.<key> }}`.

```liquid
{% if trigger_event.properties.items %}
  {% for item in trigger_event.properties.items %}
    {{ item.name }} × {{ item.quantity }}: {{ item.price }}
  {% endfor %}
{% endif %}
```

Un recorrido que empezó antes de la versión 44 no tiene `trigger_event`: protégelo con `{% if %}`.

### Ejemplo completo

```liquid
Welcome {{ contact.first_name }}!

Thank you for subscribing to {{ list.name }}. We're excited to have you on board!

Your registered email: {{ contact.email }}

Manage Preferences: {{ notification_center_url }}

Don't want to receive these emails?
Unsubscribe here: {{ unsubscribe_url }}
```

### Estructura de datos disponible

Las plantillas pueden usar esta estructura de datos:

```json
{
  "contact": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "list": {
    "id": "newsletter",
    "name": "Newsletter"
  },
  "unsubscribe_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=unsubscribe&email=john.doe@example.com&lid=newsletter&lname=Newsletter&wid=workspace123&mid=msg_123&email_hmac=abc123",
  "confirm_subscription_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=confirm&email=john.doe@example.com&lid=newsletter&lname=Newsletter&wid=workspace123&mid=msg_123&email_hmac=abc123",
  "notification_center_url": "https://your_notifuse_endpoint.your_website.com/notification-center?email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "tracking_preferences_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=tracking&email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "tracking_optout_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=tracking_optout&email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "view_in_browser_url": "https://your_notifuse_endpoint.your_website.com/v/ODkyY2Q..."
}
```

### Diferencias con Shopify Liquid

Notifuse procesa Liquid con [liquidgo](https://github.com/Notifuse/liquidgo), que sigue [Shopify Liquid](https://shopify.github.io/liquid/) 5.11. Algunos comportamientos difieren a propósito, porque tus datos vienen de JSON y tus correos los leen personas:

- **El texto vacío es falso**: `{% if contact.first_name %}` se salta a un contacto cuyo nombre está vacío. En Shopify Liquid, solo `nil` y `false` son falsos.
- **Los números de tus datos son decimales**: con `order.total` a `1999`, `{{ order.total | plus: 1 }}` muestra `2000` (no `2000.0`), y `{{ order.total | divided_by: 100 }}` conserva los decimales y muestra `19.99`. Añade `| floor` para quedarte con la parte entera.
- **En un tema de blog, un error de filtro no muestra nada**: `{{ 1 | divided_by: 0 }}`, un `base64_decode` no válido o un filtro con demasiados argumentos no muestran nada, en lugar de `Liquid error: ...`. En un correo, detiene el correo (consulta [Un error de Liquid detiene el correo](#a-liquid-error-stops-the-email)).
- **Las listas se muestran con corchetes**: `{{ contact.custom_json_1.tags }}` muestra `["vip", "early"]`. Usa `{{ contact.custom_json_1.tags | join: ", " }}` para enumerarlas.
- **`date`** interpreta una fecha escrita sin zona horaria como UTC, y un número como una marca de tiempo Unix.

En los temas de blog, que son las únicas plantillas con parciales, `{% render %}` recibe un nombre de plantilla entre comillas, como en Shopify Liquid 5.11 (`{% render 'footer' %}`); los correos lo rechazan. `{% snippet %}` no está admitido.
