Tipos de variables

 

Mailjet ofrece cuatro tipos de variables y cada una tiene un propósito distinto en el lenguaje de plantillas. Estos tipos de variable incluyen:

1. Data (estática): Estas variables se utilizan para datos que no cambian con mucha frecuencia. Normalmente son valores predefinidos.
2. Var (dinámica): Las variables Var se utilizan para datos dinámicos que pueden cambiar en función de distintas condiciones o entradas.
3. Variables predefinidas de MJ: Estas variables están predefinidas por Mailjet y proporcionan información y funcionalidades útiles dentro del lenguaje de plantillas.
4. Estructuras de variables de segmentación: Estas variables se utilizan para fines de segmentación complejos y no son en lo que se centrará este artículo.

Nos centraremos principalmente en los dos primeros tipos de variables (data y var), pero también hablaremos brevemente de las variables predefinidas.

Los tipos de variable de uso más común son data y var. Y aunque ambas variables sirven para sustituir un marcador de posición por un valor que cambia dinámicamente, se diferencian entre sí en cómo deberían utilizarse, cómo se le proporciona el valor al sistema y el tipo de mensajes en los que pueden utilizarse.

Además de las variables por sí mismas, el lenguaje de plantillas incluye herramientas (funciones) que permiten a los usuarios incorporar variables en operaciones lógicas y aritméticas más complejas, además de influir en el formato y el código. En esta guía veremos específicamente el uso de funciones como "Set" y "FormatNumberLocale". Además, profundizaremos en las declaraciones condicionales-if y en los bucles-for en más detalle.

 

Data

El tipo de variable data es muy versátil y puede utilizarse tanto en mensajes de marketing como en mensajes transaccionales. Esta flexibilidad surge del hecho de que no requiere de ninguna acción por parte del usuario para proporcionarle un valor al marcador de posición de la variable. En vez de eso, el sistema sustituye automáticamente el valor en función de los objetos de propiedad de contacto.

Ya sea que estés enviando una campaña o un email transaccional, siempre y cuando el mensaje esté dirigido a un contacto existente y el nombre de la variable se corresponda con una propiedad de contacto, el sistema será capaz de procesar esa variable de tipo data. Si el destinatario tiene un valor asignado para esa propiedad, se mostrará en vez del marcador de posición de la variable.

 

Ilustremos esto con un ejemplo. Supongamos que incluyo la variable [[data:country]] en el contenido de mi mensaje y se lo envío a uno de mis contactos. Existen dos resultados posibles en esta situación:

1. Si el contacto tiene un valor configurado para la propiedad de contacto "country" (país), recibirá el mensaje con la variable [[data:country]] sustituida por el valor correspondiente.
2. Si el contacto no tiene un valor configurado para la propiedad de contacto "country" (país), recibirá el mensaje sin ningún sustituto para la variable [[data:country]]. Eso sí, la variable en sí misma no se mostrará, al ser un elemento del lenguaje de plantillas, en la versión final del mensaje.

Veamos un ejemplo concreto. Consideremos estos dos contactos: usuario1@dominio.es, con el valor de la propiedad "country" como "España" y usuario@dominio.es, que no tiene ningún valor configurado para la propiedad "country".

Si les envío a ambos el mismo mensaje que contiene la frase:

"Hola, ¿cómo va todo en [[data:country]] después de la pandemia?"

 

Ambos contactos verán un contenido distinto:

• usuario1@dominio.es verá: "Hola, ¿cómo va todo en España después de la pandemia?"
• usuario2@dominio.es verá: "Hola, ¿cómo va todo en después de la pandemia?"

Como vemos en el segundo ejemplo, el sistema simplemente no muestra nada porque el usuario no tiene un valor configurado para la propiedad asociada a la variable data utilizada.

 

Var

Es importante tener en cuenta que el tipo de variable var no debería utilizarse en plantillas de marketing ni en borradores de campaña. Aunque puede añadirse a estos objetos, intentar enviar un mensaje así generará un evento "BLOCKED" (bloqueado) por error del lenguaje de plantillas. Por lo general, el mensaje de error indicará que no se ha proporcionado un valor a la variable var, lo que es de esperar ya que no hay forma de asignarle un valor.

 

Sin embargo, hay formas de hacer que las variables var funcionen en una plantilla de marketing o en la configuración de una campaña. Los dos enfoques más sencillos son:

• Añadir la variable var con un valor predeterminado.
• Definir la variable utilizando la función set.

Si bien estos enfoques funcionan técnicamente, pueden ser contraproducentes y menos útiles. Esto se debe a que requieren que establezcas el valor de la variable en la plantilla antes de enviar, sin permitir ninguna variación en el valor mostrado en función del destinatario. Esto contradice el propósito de tener una variable y anula su flexibilidad.

 

La utilización adecuada de las variables var es incluirlas en las plantillas transaccionales o directamente en el contenido de los mensajes transaccionales. El usuario proporciona los valores utilizados para reemplazar estas variables a través de una llamada a la API de envíos (como parte del cuerpo de la solicitud) o durante la sesión de retransmisión SMTP (como un encabezado personalizado), según el canal transaccional que se utilice.

Para declarar las variables y proporcionar sus respectivos valores, se utilizan pares clave-valor JSON. Por ejemplo, "nombre": "Juan" o "testVariable123": "testValor", etc.

En el contexto de la API de envíos v3, el objeto que contiene las variables se denomina "Vars". Para la API de envíos v3.1, el principio sigue siendo el mismo, pero el objeto se llama "Variables". Para los mensajes generados por servidor SMTP, el encabezado personalizado que debe contener las variables codificadas en JSON es "X-MJ-Vars".

 

Ten en cuenta que para que el lenguaje de plantilla se procese correctamente y no como texto sin formato, el sistema de Mailjet se basa en propiedades específicas que indican si los elementos del lenguaje de plantilla deben tratarse como tales. Estas propiedades son de tipo booleano y, a continuación, encontrarás el nombre de propiedad apropiado para cada canal transaccional:

• API de envíos v3: "Mj-TemplateLanguage"
• API de envíos v3.1: "TemplateLanguage"
• Servidor SMTP: "X-MJ-TemplateLanguage"

Es importante tener en cuenta que el valor predeterminado para cada una de estas propiedades es "falso" o "0". Si se pasa por alto este detalle, incluso si las configuraciones son correctas, es posible que las configuraciones del lenguaje de plantillas no funcionen como se esperaba. Esto se debe a que sin habilitar las propiedades anteriores, el sistema interpreta los elementos del lenguaje de plantilla en el mensaje enviado como cadenas de texto ordinarias sin ningún significado adicional.

Por último, en un escenario nicho en el que los usuarios crean objetos de borrador de campaña a través de la API y tienen la intención de utilizar un lenguaje de plantillas en el contenido del borrador de campaña, deben asegurarse de que el objeto "/campaigndraft/$ID/detailcontent" asociado con su borrador incluya la siguiente propiedad en el objeto "Headers" (Encabezados):

Al incluir esta propiedad, el sistema reconoce el uso de lenguaje de plantillas en el contenido del borrador de la campaña.

 

Valores predeterminados

Tanto las variables var como las data admiten el uso de valores predeterminados. Un valor predeterminado actúa como un valor alternativo o de seguridad que los usuarios proporcionan a nuestro sistema cuando configuran la variable en la plantilla o el cuerpo del mensaje. Si se cumplen ciertas condiciones, nuestro sistema mostrará el valor predeterminado:

• Variables data: Si el contacto que recibe el mensaje no tiene un valor de propiedad de contacto establecido para esa variable/propiedad de contacto específica.
• Variables var: Si no se envía ningún valor a través de la llamada API o la sesión SMTP.

En estos escenarios, el valor predeterminado sirve como sustituto para garantizar que siempre se muestre un valor para la variable, incluso cuando los datos necesarios no estén disponibles o no se proporcionen.

 

Sintaxis

Con las consideraciones anteriores en mente, profundicemos en la sintaxis adecuada para las variables independientes (variables que no se usan dentro de una función).

 

• Variables var

  • Para añadir una variable var, usa la siguiente sintaxis: {{var:variableName}}
  • Para proporcionar un valor predeterminado junto con la variable: {{var:variableName:defaultValue}}
    • Sintaxis alternativa: {{var:variableName:"defaultValue"}} (ambas opciones funcionan igual de bien)
  • Para utilizar un espacio como valor predeterminado, escríbelo entre comillas: {{var:variableName:" "}}
  • Para no mostrar nada como valor predeterminado, usa comillas vacías: {{var:variableName:""}}

• Variables data

  • Para añadir una variable data, usa la siguiente sintaxis: [[data:contactPropertyName]]
  • Para proporcionar un valor predeterminado junto con la variable:[[data:contactPropertyName:defaultValue]]
    • Sintaxis alternativa: [[data:contactPropertyName:"defaultValue"]]

Nota: Si bien utilizar las llaves dobles "{{}}" en lugar de los corchetes dobles "[[]]" también funciona para las variables de datos, se recomienda usar corchetes a menos que se requieran para funciones específicas que requieran llaves dobles.

 

Es importante tener en cuenta que el comportamiento del sistema difiere cuando se encuentra en una situación en la que carece de un valor para una variable data en comparación con una variable var. Si una variable data no tiene un valor predeterminado y el contacto no tiene un valor establecido para la propiedad respectiva, se imprimirá un espacio en blanco en el mensaje. Sin embargo, si no tiene un valor predeterminado para una variable var y no lo declara en la llamada a la API o en la sesión SMTP, el mensaje se bloqueará.

 

Los valores predeterminados no son obligatorios, pero pueden ser útiles para evitar el bloqueo de mensajes. De forma predeterminada, cuando el sistema encuentra una variable var sin un valor proporcionado, bloquea el mensaje. Para influir en este comportamiento, puedes incluir una propiedad booleana especial en tu llamada a la API o encabezado SMTP:

• API de envíos v3: "Mj-TemplateErrorDeliver"
• API de envíos v3.1: "TemplateErrorDeliver"
• SMTP: "X-MJ-TemplateErrorDeliver"

El valor predeterminado para esta propiedad es "falso", por lo que habilitarla manualmente permite que se envíen mensajes incluso si hay errores de lenguaje de plantilla. Habilitar esta propiedad evita que se bloqueen los mensajes.

 

Por último, los usuarios pueden elegir si desean recibir una notificación por correo electrónico cuando sus mensajes se bloqueen debido a errores en el lenguaje de las plantillas. Esto se puede lograr a través de otra propiedad especial:

• API de envíos v3: "Mj-TemplateErrorReporting" (ejemplo: "Mj-TemplateErrorReporting": "informes@dominio.es")
• API de envíos v3.1: "TemplateErrorReporting" (ejemplo: {"Email": "informes@dominio.es", "Name": "Nombre del destinatario"})
• SMTP: "X-MJ-TemplateErrorReporting" (ejemplo de encabezado personalizado: X-MJ-TemplateErrorReporting: "informes@dominio.es")

 

Variables predefinidas

En nuestro sistema, ciertos nombres de variables están reservados para variables estáticas predefinidas. Estas variables permiten a los usuarios especificar una variable que corresponde a un valor específico basado en el sistema. Algunas variables predefinidas de uso común incluyen:

• ID de contacto del destinatario
• Dirección de email de contacto del destinatario
• ID de la plantilla
• Enlaces para compartir en redes sociales para la versión en línea del correo electrónico (Twitter, Facebook, LinkedIn, etc.) - Esto se aplica a newsletters igual que las versiones estándar en línea/PERMALINKS.

Puedes encontrar una lista de estas variables estáticas predefinidas aquí.

 

La sintaxis para usar cualquiera de estas variables predefinidas es la siguiente: {{predefinedVarHere}}.

Ejemplo: {{mj:template.ID}} mostrará el ID de plantilla en la versión final del mensaje si se utilizó una plantilla para enviar el correo electrónico.

 

Ten en cuenta que hay otras variables reservadas, como el enlace para darse de baja o la versión en línea, que se introducen entre corchetes dobles (p. ej., [[PERMALINK]]). Estas variables generalmente las agrega automáticamente el sistema, pero los usuarios también pueden introducirlas manualmente en el editor de arrastrar y soltar, en el HTML sin formato, en las plantillas MJML sin formato o en otros objetos de contenido detallado de los borradores de campaña. Es importante recordar que estas variables predefinidas especiales no deben introducirse entre corchetes. Introducirlas con corchetes hará que el sistema las trate como variables que deben definirse en una llamada API o durante una sesión SMTP (como variables "var") en lugar de variables que el sistema puede obtener por sí solo.

Por lo tanto, cualquier variable estática predefinida especificada en la documentación de referencia mencionada anteriormente (que comience con "mj:") debe introducirse usando "{{}}", mientras que cualquier variable predefinida que no figure en esa documentación (que no comience con "mj:") debe introducirse usando "[[]]".

 

Objetos y matrices muldimensionales

Nuestro lenguaje de plantillas permite el uso de objetos multidimensionales y matrices multidimensionales (son útiles en varias situaciones, por ejemplo) para introducir valores que se usarían en un bucle-for.

 

Un objeto o matriz multidimensional es aquel que involucra variables que están anidadas una debajo de la otra. Estos solo se pueden usar en plantillas/mensajes transaccionales, ya que requieren que el usuario proporcione los valores y esto debe hacerse a través de una estructura JSON específica.

Aquí hay un ejemplo de una variable multidimensional que debería presentarse como un objeto multidimensional en los datos JSON donde se declararán las variables para ese mensaje:

 

{{var:clothes.winter.coat}}

 

Cada punto (".") representa una "capa" de anidamiento: el valor más a la izquierda indica el nivel más externo, mientras que cuanto más a la derecha nos movemos, más abajo nos encontramos dentro de la estructura anidada. Aquí está la estructura JSON correcta que debe usarse, para que nuestro sistema ubique correctamente el valor de la variable "clothes.winter.coat" (el ejemplo incluye la propiedad v3.1 "Variables" pero eso variaría dependiendo del canal transaccional utilizado, como se discutió en una sección anterior):

La configuración anterior daría como resultado que las palabras "blazer" se mostrara en la posición donde se colocó "{{var:clothes.winter.coat}}" en la plantilla/contenido del correo electrónico.

 

En cuanto a las matrices multidimensionales, estas se usan más comúnmente, específicamente en bucles-for (más sobre estos en otra sección). La lógica detrás de cómo estructurar los datos JSON sería similar a la utilizada en el ejemplo que se muestra arriba, con algunas adiciones (es decir, matrices JSON).

He aquí un ejemplo sencillo: {{customer.Name}}

Si imaginamos que esta va a ser una variable utilizada en un bucle-for (lo que significa que queremos asignar diferentes valores bajo la misma variable, en este caso, "Name"), podríamos usar una matriz con objetos anidados para lograrlo. Así es como se vería el JSON:

Como puedes ver, tenemos una variable anidada llamada "Name" debajo de la capa llamada "customer", por lo que nuestra estructura JSON debe reflejar eso. Primero definimos "customer" y especificamos que es una matriz abriendo los corchetes. Dentro de los corchetes, podemos usar varios pares de llaves para definir diferentes valores para la variable "Name". Si no estuviéramos usando una matriz multidimensional (que en un escenario de la vida real también se combinaría con un bucle-for), no habríamos podido usar la variable "Name" varias veces con diferentes valores. Habríamos necesitado usar algo como "Name1", "Name2", "Name3", etc. Por lo tanto, utilizar una matriz multidimensional nos ahorra trabajo, hace que nuestro JSON sea más fácil de administrar, al tiempo que nos permite reutilizar el mismo nombre de variable con diferentes valores.

Echaremos un vistazo a otra matriz multidimensional simple en la sección de bucles-for, así como a una más compleja (una con más capas de anidamiento).

 

Declaraciones condicionales-if

Las declaraciones condicionales-if se utilizan para introducir requisitos que determinan si se debe mostrar una información específica. También pueden incluir valores alternativos que se mostrarán si no se cumple el requisito inicial, utilizando declaraciones else. Además, se puede introducir un requisito alternativo utilizando la declaración condicional elseif . Una declaración-if debe cerrarse con un operador endif.

 

Por lo general, las declaraciones condicionales-if se introducen mediante bloques de lenguaje de plantilla en una plantilla de arrastrar y soltar. Sin embargo, también se pueden agregar dentro de los elementos de texto. Estas declaraciones se pueden usar tanto en plantillas de marketing como transaccionales, aunque las plantillas transaccionales brindan más flexibilidad. En una plantilla transaccional, los condicionales-if se pueden crear en función de los valores de las variables var, que se envían a través de la API de envío o SMTP, así como las variables data, que funcionan con valores de propiedad de contacto. En una plantilla de marketing, solo se pueden usar variables data, ya que no hay forma de enviar valores para las variables var.

Aquí hay un ejemplo de una declaración condicional-if simple utilizada en una plantilla de marketing:

Aquí hay un ejemplo del lenguaje de plantilla en uso:

{% if data:firstname %}
PRINT THIS IN THE MARKETING MESSAGE
{% endif %}

 

En este ejemplo, el lenguaje de la plantilla comienza con una cláusula de apertura que contiene la condición misma. Si se cumple la condición (es decir, el destinatario tiene un valor establecido en la propiedad "firstname"), el sistema mostrará el contenido dentro del bloque ("PRINT THIS IN THE MARKETING MESSAGE"). La cláusula de cierre significa el final de la sección condicional-if.

La declaración condicional-if se basa en una propiedad de contacto ("firstname"). El sistema verificará si el destinatario tiene un valor establecido en la propiedad "firstname". Si la respuesta es sí, el sistema incluirá el contenido dentro del bloque en la versión final del correo electrónico. Si la respuesta es no, la cadena específica no se mostrará.

Este es un ejemplo de cómo puede verse la versión final del correo electrónico para un destinatario que tiene una propiedad de "firstname" definida:

 

Este es un ejemplo de cómo puede verse la versión final del correo electrónico para un destinatario que no tiene una propiedad de "firstname" definida:

La condición-if anterior comprueba si la propiedad está definida para el destinatario. Sin embargo, puede introducir un valor específico que debe tener la propiedad para que se imprima el contenido condicional. Por ejemplo:

En este ejemplo, el contenido condicional "PRINT THIS IN THE MARKETING MESSAGE" solo estará presente en la versión del mensaje del destinatario si la propiedad de contacto "firstname" se establece con el valor "Gina". Esta condición garantiza que el contenido se muestre exclusivamente para los destinatarios cuya propiedad "firstname" coincida con el valor especificado de "Gina".

 

Echemos un vistazo más de cerca a un par de ejemplos que involucran plantillas transaccionales. Estos ejemplos demuestran el uso de variables var y elementos de lenguaje de plantilla, y se pueden aplicar dentro de bloques de texto o bloques de lenguaje de plantilla.

 

Ejemplo 1: Utilizar una variable var en una plantilla transaccional

En este ejemplo, estamos comprobando si la variable var "variable" está definida. La condición es verdadera o falsa y actúa como una propiedad booleana.

 

Esto es lo que puedes esperar en los diferentes escenarios:

• Si la variable var "variable" no está definida en la llamada de la API de envíos (SAPI) o en la sesión SMTP, se producirá un error de lenguaje de plantillas. Agregar un valor predeterminado en el condicional-if (var:variable:defaultValueHere) siempre mostrará "PRINT THIS STRING IN THE TRANSACTIONAL EMAIL" para los destinatarios donde la variable no está definida.
• Si la variable se establece como true en la llamada SAPI o en la sesión SMTP, se cumplirá la condición.
• Si la variable se establece como "anyValueYouCanThinkOfOtherThanFalse" en la llamada SAPI o en la sesión SMTP, se cumplirá la condición.
• Si la variable se configura como false en la llamada SAPI o en la sesión SMTP, la condición NO se cumplirá. Ten en cuenta la diferencia entre "variable": "false" (escenario anterior) y "variable": false (escenario actual).

Ejemplo 2: Muestra de otros operadores lógicos y de comparación (else, elseif e ifelse + AND)

Este ejemplo demuestra el uso de diferentes operadores de comparación y operadores lógicos. Incluye las declaraciones if, else y elseif combinadas con el operador lógico AND.

Finalmente, aquí hay una captura de pantalla para proporcionar una referencia visual: 

Estos ejemplos ilustran cómo las variables var y varios operadores se pueden utilizar de manera efectiva dentro de las plantillas transaccionales para personalizar el contenido en función de condiciones específicas.

 

Ahora, examinemos pares de datos JSON junto con los resultados correspondientes que producen para el destinatario final:

JSON 1:

JSON 2:

JSON 3:

JSON 4:

Esencialmente, para que se muestre el valor "I'll consider going out", necesitamos que se cumplan simultáneamente las siguientes condiciones: "weather" no debe ser "bad", el valor "bankAccountBalance" debe ser diferente de 0 y la variable "haveFreeTime" debe ser verdadera (o estar definida). Si alguna de estas tres condiciones no se cumple, se mostrará el valor "I won't be going out" o "I'll stay at home", según qué condición no se cumpla.

 

Ten en cuenta el uso del operador lógico AND, que requiere el uso de paréntesis () para garantizar la agrupación adecuada de las condiciones.

 

Bucles-for

Los bucles-for te permiten recorrer varias iteraciones de una variable o recorrer una lista de variables, lo que proporciona flexibilidad y contenido dinámico. Es importante tener en cuenta que los bucles-for solo deben usarse en plantillas transaccionales y no en plantillas de marketing, ya que los valores o las iteraciones no se pueden introducir en un mensaje de marketing.

 

Echemos un vistazo a una representación simple de un bucle-for:

En este ejemplo, definimos un bucle-for con el nombre de variable "Test" y especificamos el espacio de nombres donde el sistema debe buscarlo (var:Test). Asumimos una variable simple con una iteración. La llamada API o los encabezados SMTP deben incluir la siguiente estructura JSON:

Ten en cuenta que la sección anterior de "matrices multidimensionales" contiene una forma alternativa de presentar el mismo tipo de estructura que también se puede usar con bucles-for.

 

El bucle-for será reemplazado por los valores proporcionados en la estructura JSON. Aquí hay un ejemplo de cómo se vería el mensaje resultante.

Ahora, imaginemos un escenario en el que eres parte del equipo de relaciones públicas de una empresa y necesitas enviar un correo electrónico al departamento financiero. Quieres comunicar los nombres, el país de residencia y los números de teléfono de contacto de tres clientes que ganaron un juego organizado por su empresa y necesitas que el equipo financiero revise su información de contacto.

Para lograr esto, puedes utilizar un bucle-for en tu mensaje para pasar por diferentes iteraciones del mismo nombre de variable (por ejemplo, Name, Phone, etc.) y mostrar diferentes valores cada vez.

Aquí hay un ejemplo del lenguaje de plantilla en uso:

En este caso, usamos el nombre de variable "customer" para recorrer los detalles del cliente proporcionados en la llamada a la API o en los encabezados SMTP. La estructura JSON debe seguir este formato:

Al usar este enfoque, simplificas la estructura JSON y reduces el riesgo de errores. El correo electrónico resultante mostrará los detalles del cliente según las iteraciones proporcionadas.

Por último, exploremos un ejemplo más complejo que implica una estructura de matriz multidimensional. En este caso, supondremos un escenario relacionado con prendas de invierno.

Aquí está la configuración para el bucle-for en la plantilla:

En este ejemplo, usamos la variable "value" ubicada debajo del espacio de nombres "items" en la estructura JSON. Especificamos dos tipos de artículos (coats y hats) con sus respectivas variables anidadas bajo múltiples capas de variables.

Así es como se vería la estructura JSON para este ejemplo:

El mensaje resultante mostraría los valores del abrigo y el sombrero de invierno en función de las iteraciones proporcionadas.

Al utilizar bucles-for, puedes iterar dinámicamente a través de variables y generar contenido personalizado en plantillas transaccionales. Es importante garantizar la estructura JSON adecuada y seguir la sintaxis del lenguaje de plantilla para lograr los resultados deseados.

 

Declaración condicional-if y tabla de puntos clave de bucles-for:

 

Bloques de texto - Bloques HTML - Bloques de lenguaje de plantillas

Cuando se trabaja con plantillas de correo electrónico, existen diferentes enfoques para incorporar estructuras de lenguaje de plantilla. Se pueden introducir a través de bloques de texto, bloques HTML o bloques de lenguaje de plantilla en plantillas transaccionales de arrastrar y soltar. Además, se pueden incrustar directamente en el contenido del correo electrónico.

Por lo general, se recomienda separar el contenido HTML sin procesar de las estructuras del lenguaje de plantilla siempre que sea posible. Cuando es necesario combinarlos, como cuando se crea una tabla con iteraciones variables usando un bucle-for, generalmente es más seguro utilizar un bloque HTML de arrastrar y soltar e incorporar el lenguaje de plantilla en él en lugar de agregar HTML sin procesar a un bloque de lenguaje de plantilla.

Los bloques de lenguaje de plantilla son especialmente útiles cuando se trabaja con declaraciones condicionales-if. Cada operador dentro del condicional-if se puede colocar en un bloque de lenguaje de plantilla separado, con varios otros elementos de arrastrar y soltar sirviendo como el contenido que se mostrará en función de una condición específica. Por ejemplo, puedes mostrar un elemento de imagen, un elemento de video o un botón si se cumplen ciertos criterios. Es posible abrir un bucle-for o un condicional-if en un bloque y cerrarlo en otro, proporcionando flexibilidad y organización.

Para mantener la claridad y la separación, se recomienda colocar estructuras de lenguaje de plantilla en bloques de lenguaje de plantilla dedicados en lugar de mezclarlos con otro contenido. Si bien se puede agregar texto sin formato dentro de un bloque de lenguaje de plantillas, es mejor usar bloques separados para contenido más complejo. Al combinar HTML sin formato con estructuras de lenguaje de plantillas, se recomienda utilizar un bloque de HTML sin formato en el que el código se almacena junto con el lenguaje de plantillas, en lugar de incluir HTML sin formato dentro de un bloque de lenguaje de plantillas.

 

Funciones

Como se mencionó anteriormente, las funciones son una parte esencial del lenguaje de plantillas de Mailjet y ofrecen una variedad de operaciones que el sistema puede realizar. Estas funciones permiten efectos de formato en diferentes áreas, tales como:

• Operaciones matemáticas: Redondeo de valores numéricos.
• Manipulaciones de cadenas de texto: Conversión de cadenas enteras a mayúsculas o minúsculas, o cambiar la primera letra a mayúsculas.
• Formato de números: Formato de números según reglas específicas.
• Codificación de URL: Conversión de una cadena a un formato seguro para URL.
• Escape de cadena: Garantizar que los caracteres especiales en una cadena estén codificados correctamente.

Al combinar estas funciones con variables, declaraciones condicionales y operadores mencionados en la referencia del lenguaje de plantillas de Mailjet, puedes crear contenido altamente personalizable y dinámico.

En esta sección, exploremos dos funciones específicas: la función Set y la función FormatNumberLocale.

 

Función Set

La función Set es una característica poderosa que nos permite asignar un valor directamente a una variable dentro de la plantilla o contenido del correo electrónico, eliminando la necesidad de declarar la variable en la llamada SAPI o sesión SMTP.

Echemos un vistazo a un ejemplo:

En el ejemplo anterior, usamos la función Set para asignar un valor a la variable "testVar" dentro de la propia plantilla. En la siguiente línea, estamos usando la misma variable dentro de una declaración.

 

Al usar la función Set, puedo enviar un mensaje con un objeto Variables vacío como este:

Este enfoque nos permite enviar mensajes sin definir explícitamente la variable en la llamada a la API y el mensaje no se bloqueará. Aquí está el resultado cuando se envía el mensaje:

Uno de los aspectos interesantes de la función Set es que puedes usarla varias veces dentro del mismo contenido para actualizar el valor de la misma variable. Veamos un ejemplo que corrige una declaración:

En el ejemplo anterior, usamos la función Set para asignar un valor a la variable "testVar" dentro de la propia plantilla. La segunda asignación anula el valor inicial, lo que da como resultado el siguiente resultado:

Es importante tener en cuenta que si pasas un valor para la misma variable a través de la llamada API o la sesión SMTP, no anularás el valor establecido mediante la función Set dentro de la plantilla.

 

Función FormatNumberLocale

La función FormatNumberLocale te permite formatear números de coma flotante (números con fracciones decimales) de acuerdo con reglas específicas. Se basa en tres propiedades:

• "Format" (Formato): Especifica el formato deseado del número.
• "Number" (Número): Proporciona el número que se va a formatear.
• "Locale" (Configuración regional): Selecciona la configuración regional para determinar el punto decimal y el separador de miles.

Por ejemplo, considera el siguiente código de plantilla:

En este ejemplo, usamos la configuración regional francesa ("fr_FR") para formatear el número 3500 usando el formato "#,###.00". El resultado será:

Puedes ver que el número ahora incluye separadores de miles y puntos decimales según el formato francés.

La función FormatNumberLocale también admite otras variaciones de formato, como:

Estos ejemplos demuestran cómo ligeras variaciones en el formato pueden afectar el resultado. Si se utiliza la configuración regional "en_GB" para formatear, se obtendrá:

Cuando utilices variables dinámicas con la función FormatNumberLocale, asegúrate de seguir la sintaxis correcta:

Asegúrate de que la variable "var:VarName" se proporciona sin comillas ni corchetes. Además, proporciona el valor de la variable como un número entero en la llamada API o sesión SMTP:

El uso de comillas alrededor del valor provocará errores en el lenguaje de plantillas.

Estas funciones, junto con las amplias capacidades del lenguaje de plantillas de Mailjet, te permiten crear contenido dinámico y altamente personalizado en tus correos electrónicos. 

Notas adicionales

Vale la pena mencionar que las variables se pueden agregar fuera de los cuadros de texto, HTML o bloques de lenguaje de plantilla. Puedes introducir variables en varios otros elementos, como hipervínculos, botones y direcciones URL de imágenes en elementos de imagen de arrastrar y soltar.

Cuando utilices una variable dentro de un hipervínculo o la URL de un botón, puedes utilizar un valor de variable predeterminado. Sin embargo, es importante tener en cuenta que no puedes usar una variable predeterminada dentro de la URL asociada con un elemento de imagen de arrastrar y soltar. El sistema te permitirá guardar la variable en el campo URL con un valor predeterminado, pero lo eliminará de inmediato.

Ten en cuenta que al agregar una variable predeterminada dentro del enlace de un elemento Botón o un hipervínculo, es posible y funciona bien. Sin embargo, puedes encontrarte con una notificación de error en el editor, que puedes ignorar. Asegúrate de que el valor predeterminado se añade sin comillas y sin un protocolo HTTP/HTTPS al principio. Por ejemplo: {{var:Link:www.mailjet.com}}

Otro punto importante a considerar es la declaración de variables en la llamada SAPI/sesión SMTP. Debe coincidir exactamente con la forma en que se agregaron en el contenido del mensaje. La distinción entre mayúsculas y minúsculas juega un papel crucial, así que estate atento a cualquier discrepancia en mayúsculas y minúsculas. Además, cuando se usa un punto (.) en las variables, indica matrices o objetos multidimensionales. Si se necesita un separador en lugar de indicar una estructura multidimensional, un guión bajo (_) es una mejor opción que un punto.

Actualizaciones del Templater: sintaxis más estricta y cambios de comportamiento (octubre de 2025)

Hemos implementado actualizaciones que mejoran la fiabilidad y el rendimiento, y hacen que la validación de sintaxis sea más estricta. Si tus plantillas dependían de un análisis más permisivo, revisa los cambios siguientes.

👉 Manejo más estricto de las etiquetas

Los bloques {% if %} / {% for %} ahora deben cerrarse correctamente. La ausencia de {% endif %} o {% endfor %} genera un error (anteriormente, era posible tolerar bloques incompletos).

{% if var:is_promo %}
  <p>Promo!</p>
{% endif %}

👉 Espacios de nombres de variables: var y data

• Si la variable está declarada/conocida (existe en tu esquema) pero no se incluye en el payload, la renderización ahora es más permisiva (se resuelve como vacío/falso según corresponda).
• Si una variable no está definida en absoluto, se devuelve un error.

{% if var:user.first_name %}Hello {{ var:user.first_name }}!{% endif %}

👉 Identificadores vs. operaciones

Los espacios alrededor de los operadores importan. El analizador distingue entre identificadores y expresiones:

• var:x-1 → interpretado como un único identificador llamado x-1
• var:x - 1 → interpretado como una operación de resta (x menos 1)

{{ var:price - 1 }}   {# subtraction #}
{{ var:price-1 }}     {# key literally named "price-1" #}

👉 Reescritura de enlaces para el seguimiento de clics

Las etiquetas <a> sin un atributo href entre comillas anteriormente eran ignoradas por el reescritor de enlaces. Ahora sí se reescriben y se rastrean.

<a href={{ var:url }}>Open</a>

<a href="{{ var:url }}">Open</a>

👉 Reemplazo del enlace de cancelación de suscripción

[[ UNSUB_LINK ]] ahora se reemplaza correctamente en todas las partes del cuerpo del mensaje (incluidos parciales/bloques donde antes podía omitirse).

<p>To unsubscribe, click [[ UNSUB_LINK ]]</p>

👉 Mejoras de rendimiento

La latencia media de procesamiento de plantillas ha mejorado, lo que resulta en una personalización de correo más rápida en el momento del envío.

👉 Mayor rigurosidad en la sintaxis

El motor de plantillas ahora aplica reglas de sintaxis de forma más estricta. Los errores de validación más comunes incluyen:

• Bloque sin cerrar (falta {% endif %} o {% endfor %})
• Variable no definida (uso de una clave que no está definida en var/data)
• Expresión malformada (espacios incorrectos en operadores o delimitadores no coincidentes)

👉 Lista de comprobación

1. Ejecuta un render de prueba para cada plantilla en producción (usa payloads que incluyan y omitan campos opcionales).
2. Cierra todos los bloques de control con {% endif %} / {% endfor %}.
3. Define tus variables (esquema) o proporciónalas en el payload; evita referencias no definidas.
4. Revisa operaciones aritméticas e identificadores: añade espacios alrededor de operadores que deban evaluarse.
5. Entrecomilla todos los valores href: href="{{ var:url }}".
6. Verifica la presencia y el renderizado de [[ UNSUB_LINK ]] en todos los lugares donde aparezca.

Gestión de errores en plantillas

Explora este completo artículo que te guiará a través del proceso de aprovechamiento de la función de Gestión de errores de plantilla de Mailjet. Esta potente característica automatiza la verificación de tus plantillas, ahorrándote un tiempo valioso y eliminando la necesidad de realizar comprobaciones manuales. Dile adiós a la tediosa tarea de revisar individualmente cada plantilla y dale la bienvenida a un enfoque simplificado para la gestión eficiente de errores.