Cómo usar la plantilla con el lenguaje de SendinBlue para crear plantillas de e-mail [NUEVO]

Nuestro lenguaje de plantillas incluye marcadores y expresiones lógicas predefinidas que pueden usarse para insertar contenido dinámico en sus e-mails y modificar cómo ve el contenido el destinatario.

El lenguaje de plantillas proporciona una estructura común y estandarizada para crear plantillas eficientes y potentes opciones de diseño.

Información relevante: El nuevo lenguaje de plantillas remplaza la anterior versión del lenguaje de plantillas de SendinBlue, que utilizaba otros elementos de sintaxis y era menos robusto. En esta guía nos referiremos al nuevo lenguaje de plantillas directamente como «el lenguaje de plantillas».

Antes de empezar

Cuando vaya a crear un e-mail que pretenda enviar a varios destinatarios a la vez, cree su e-mail como una Campaña.

Cuando vaya a crear una plantilla para enviar un e-mail transaccional o para utilizar un escenario de Automation, créela y guárdela como Plantilla.

Los e-mails que utilicen el lenguaje de plantillas pueden activarse mediante las correspondientes llamadas de la API v3 de SendinBlue (para campañas) o (para e-mails transaccionales) siempre que se proporcione el ID de la campaña o la plantilla. También pueden enviarse mediante el relay SMTP proporcionando el encabezado X-SIB-API con los parámetros adecuados.

Información relevante: Si no ha usado nuestra plataforma transaccional (SMTP) anteriormente, puede solicitar su activación. Para comprobarlo, inicie sesión en su cuenta y visite esta página. Si no aparece una ventana que le solicite que active su cuenta SMTP y su límite es superior a 0, eso quiere decir que todo está listo para comenzar con los envíos.

Descripción general

El lenguaje de plantillas utiliza variables y filtros que se remplazan con valores específicos cuando se activa el envío del e-mail, así como etiquetas que aportan expresiones lógicas que controlan si el contenido se muestra y cómo.

Hay dos tipos de delimitadores disponibles:

{{ ... }} «imprime» o muestra el resultado de una variable o filtro en el e-mail.
{% ... %} ejecuta la expresión lógica de una etiqueta, como los bucles «for».

Información relevante: El lenguaje de plantillas puede aplicarse para modificar distintos aspectos de su e-mail, entre los que se incluyen el asunto, el encabezado, el contenido dentro de las etiquetas HTML <body> y el campo del receptor «para». El HTML se omite automáticamente de manera predeterminada en el interior de las plantillas, pero este comportamiento puede cambiarse con la etiqueta autoescape que se describe en detalle más abajo.

Variables

Hay tres tipos de variables disponibles, que describimos a continuación.

Información relevante: Cuando utilice la característica de «Enviar una prueba» para probar su plantilla de e-mail, las variables no se remplazarán por el contenido personalizado para el receptor en el e-mail de prueba. En su lugar, verá las variables exactamente como aparecen codificadas en su plantilla. 

1. Variables predefinidas

Están disponibles para todos los usuarios de SendinBlue:

{{ mirror }}

inserta un enlace para mostrar su e-mail como página web

Esta variable no es obligatoria.

Normalmente se coloca en la parte superior de un e-mail con el siguiente formato de enlace:

<a href={{ mirror }}>Click here to view this message in your browser.</a>

{{ unsubscribe }}

inserta un enlace para cancelar la suscripción a sus e-mails

Cualquier e-mail no transaccional que se envíe a través de SendinBlue debe incluir un enlace para cancelar la suscripción.

Normalmente se coloca en el pie del e-mail y tiene el siguiente formato de enlace:

<a href={{ unsubscribe }}>Click here to unsubscribe.</a>

 

2. Atributos de contacto   

Este tipo de variable contiene dos elementos y se estructura de la siguiente manera:

{{ contact.attributeNAME }}

Attribute = el atributo de nombre de su contacto de SendinBlue tal y como aparece en su Página de contactos de SendinBlue. Los atributos siempre van en mayúsculas y no pueden contener espacios.

Ej.: Para insertar el número de teléfono de un contacto cuando el atributo se llame PHONE, utilice: {{ contact.PHONE }}

Si el atributo de contacto contiene un guion (-), como CELL-PHONE, utilice el siguiente formato para su variable: {{ contact|key:"ATTRIBUTE" }}.  

Ej.: {{ contact|key:"CELL-PHONE" }}

3. Parámetros transaccionales

Las variables de parámetros transaccionales también contienen dos elementos estructurados como:

{{ params.parameterNAME }}

parameterNAME = el nombre del parámetro transaccional, con el mismo formato y mayúsculas que tiene en la API.

Ej.: Para insertar una lista de productos en la que el parámetro se llame PRODUCTS, use: {{ params.PRODUCTS }}.

Veamos un ejemplo de un uso frecuente: generar una lista de productos comprados por un cliente. Dado que el número de productos comprados varía para cada cliente, podemos combinar un for-loop o «bucle for» con su parámetro transaccional PRODUCTS, como en este ejemplo:  

<ul> 
{% for product in params.products %}

   <li><strong>{{ product.NAME }}</strong> - {{ product.PRICE }}</li>
{% endfor %}
</ul>

Esta sería una lista de productos por puntos sin ordenar que incluye el producto y el precio, de este modo la lista de cada destinatario puede incluir un número concreto de productos:  

  • Producto 1 - 10 $
  • Producto 2 - 10 $
  • Producto 3 - 10 $

Información relevante: Recomendamos que se evite el uso de guiones o cualquier tipo de caracteres especiales en los nombres de sus variables/parámetros. Si no le queda más remedio, puede utilizar {{ params|key:”parameter-NAME” }}. Puede anidar el filtro varias veces, por ejemplo {{ params|key:”my-product”|key:”my-product-name” }}.

Arrays

Al usar un array puede acceder a todos los elementos individuales. Especifique su ID de la siguiente manera: params.parameterARRAY.ID.parameterNAME. Por ejemplo: {{ params.PRODUCTS.1.NAME }}.

 

Etiquetas

Las etiquetas que se utilizan con más frecuencia en las plantillas son iffor y autoescape. A continuación, se describe cómo usarlas y se ofrecen ejemplos para cada una de ellas.

if

La potente lógica ofrecida por  if le permite añadir o eliminar bloques de contenido completos de su plantilla (o modificar el contenido de un bloque). Esto amplía con creces la utilidad de una plantilla para varios escenarios.

La etiqueta {% if %} le permite probar si una expresión es verdadera (o si un conjunto o array está vacío), y modificar el contenido del e-mail en función del resultado. También puede comprobar si hay valores falsos, condiciones múltiples y ramas múltiples.

Estas son algunas de las maneras de usar if:

if

comprueba si un valor es verdadero o si un array está vacío

{% if contact.ACTIVE %}
Congrats! You achieved your goal this month.
{% endif %}
{% endif %}

---

{% if params.tutors %}

{% for tutor in params.tutors %}
The following tutors are available to help you:
<ol>
<li>{{ tutor.name }}</li>
{% endfor %}
</ol>
{% endif %}

 

==

comprueba si una expresión es verdadera

{% if coupon == “WELCOME” %}
<p>Welcome to our list! Here’s your first coupon: WELCOME25</p>
{% endif %}

---

{% if contact.DONOR == true %}
<b>Thank you for your support!</b>
{% endif %}

if, in

comprueba si un valor (subcadena) existe en una cadena o si una variable existe en un array

{% if “@example.com" in "bob@example.com" %}
Esto aparece cuando "@example.com" forma parte de "bob@example.com"
{% endif %}

 

{% if "Piano" in params.types %}
Be careful! There are heavy items in your order. You must be present to receive this delivery.
{% endif %}

not

comprueba valores que sean falsos

{% if not user.subscribed %}
   <p>You are not subscribed to our secret sale alerts. Sign up here.</p>
{% endif %}

and / or

evalúa distintas condiciones

{% if temperature > 10 and temperature < 55 %}
   <p>Brr. It’s cold! Here’s a coupon for 20% off of any hot beverage, today only.</p>
{% endif %}

 

{% if contact.LANG == “FR” and contact.COUNTRY == “Canada” %}
{% endif %}

 

{% if contact.COUNTRY == “United States” or contact.COUNTRY == “Canada” %}
{% endif %}

elif, else

evalúa varias ramas

{% if contact.GENERO == “Masculino” %} Hola Sr. {{ contact.APELLIDO }},
{% elif contact.GENERO == “Femenino” %} Hola Sra. {{ contact.APELLIDO }},
{% else %} Hola, {% endif %}

---

{% if event.paid %}
  Your spot is reserved. Thanks for submitting your payment.
{% elif event.registered %}
    Your spot is reserved but will be released without payment by January 2.
{% else %}
    There’s still time to sign up! Click here.{% endif %}

 

Información relevante: No recomendamos aplicar etiquetas de comparación if a las variables que contienen valores en comas flotantes, ya que puede que los resultados no sean exactos. (Los valores en comas flotantes son aquellos que contienen un número fraccionario en lugar de un número entero). Sin embargo, se pueden aplicar si el valor se escribe como una cadena (entre comillas, "así").

for

Como veremos más adelante en esta guía, for es una etiqueta muy potente cuando se combina con los parámetros transaccionales. Permite realizar acciones complejas fácilmente, como insertar listas dinámicas de productos.

La etiqueta {% for %} le permite crear un loop o bucle para cada artículo en una secuencia. Esto resulta especialmente útil cuando se desconoce la cantidad de elementos de la secuencia durante la creación de la plantilla.

Estas son algunas de las maneras de usar for:

for, in

muestra una lista

<ul>
   {% for user in params.USERS %}
       <li>{{ user.username }}</li>
   {% endfor %}
</ul>

else

produce un bloque de sustitución
si su secuencia está vacía

<ul>
   {% for user in params.USERS %}
       <li>{{ user.username }}</li>
   {% else %}
       <li><em>no se encuentra ningún usuario</em></li>
   {% endfor %}
</ul>

Mostrará «no se encuentra ningún usuario».

reversed

invierte el orden en el que se muestran los elementos de su secuencia

{% for country in params.countries reversed %} {% end for %}

Mostrará una lista de países, pero en el orden contrario al de la lista original.

 

Variables de loop

En un bloque de for-loop, puede acceder a estas variables especiales:

forloop.Counter

Configure siempre un número entero que represente el número de veces que se ha introducido el loop. Está indexado en uno, así que la primera vez que se utilice el loop, forloop.Counter comenzará a partir del 1.

Puede utilizarse para numerar elementos de un bucle:

{% for product in params.products %}
{{ forloop.Counter }}. {{ product.name }} {% endfor %}

se mostrará así:

1. Producto a
2. Producto b
3. Producto c, etc.

forloop.Counter0

La iteración actual del loop. (Indexado a 0)

forloop.Revcounter

Establezca siempre un número entero que represente el número de elementos restantes en el loop. La primera vez que pase por el loop, forloop.Revcounter se ajustará al número total de elementos en la secuencia que esté recorriendo. La última vez que pase por el loop, forloop.Revcounter aparecerá el 1.

forloop.Revcounter0

El número de iteraciones desde el final del loop (0 indexado)

forloop.First

Valor booleano establecido en True si es la primera vez que pasa por el bucle.

Esto es útil para poner el primer elemento de una lista en mayúsculas o en minúsculas, como añadir el filtro «upper» (descrito en la sección de «Filtros» más abajo) solo para el primer elemento de esta lista de productos.

{% for product in params.products %}
{{ forloop.Counter }}. {% if forloop.First %} {{ product.name|upper }} {% else %} {{ product.name }} {% endif %} - {{ product.price }}
{% endfor %}

Permite mostrar una lista de productos así:

1. PRIMER PRODUCTO: 5,00 €
2. Segundo producto: 2,00 €
3. Tercer producto: 4,00 €

forloop.Last

Valor booleano ajustado a Verdadero si es la última vez que pasa por el loop. Un uso frecuente para esta función es poner caracteres separados (como «,» o «|») en una lista de elementos.

forloop.Parentloop

Hace referencia al objeto forloop para el loop principal, en caso de loops anidados. Aquí tiene un ejemplo:

{% for country in countries %}
<table>
{% for city in country.city_list %}
<tr>
<td>Country #{{ forloop.Parentloop.counter }}</td>
<td>City #{{ forloop.Counter }}</td>
<td>{{ city }}</td>
</tr>
{% endfor %}
</table>
{% endfor %}

 

Información relevante: Los nombres de las variables loop distinguen las mayúsculas.

Ej.: Para asignar un valor numérico (a partir de 1) para cada artículo que se muestre en su iteración, utilice {{ forloop.Counter }}:

{% for user in users %}
   {{ forloop.Counter }} - {{ user.username }}
{% endfor %}

 

autoescape

Información relevante: De manera predeterminada, SendinBlue no tiene en cuenta el lenguaje HTML (y JS) de todas las variables. Esto quiere decir que no se tendrá en cuenta ningún HTML de las variables y se mostrará como texto. Por ejemplo, si el contenido de su variable es <h1>Mi título</h1>, su plantilla mostrará exactamente este texto en su e-mail: <h1>Mi título</h1>, en lugar de mostrar la frase «Mi título» con formato de título H1.

La etiqueta autoescape controla este comportamiento. Como SendinBlue utiliza plantillas HTML autoescape de manera predeterminada, normalmente deberá utilizar esta etiqueta para desactivar el autoescape para un bloque concreto. El bloque debería cerrarse con una etiqueta final de endautoescape.

Veremos un ejemplo habitual en el que puede resultar útil desactivar el autoescape. Imaginemos que incluye productos dentro de una variable, pero que cada producto necesita un formato especial.

Si utiliza autoescape así:

{% autoescape off %}{{ params.my_html }}{% endautoescape %}

Se desactivará el autoescape para la variable {{ params.my_html }}. Si el contenido de su variable es <h1>Mi título</h1>, se mostrará como un título en formato H1. 

Las únicas excepciones son las variables que ya están marcadas como seguras, ya sea por el código de la variable o porque se ha aplicado un filtro seguro.

verbatim

La etiqueta verbatim le permite usar corchetes dobles {{ así }} en su correo electrónico sin que se reconozcan como un elemento de lenguaje de plantilla. Para omitir los {{ }} y mostrar estos símbolos directamente en su correo electrónico, use las siguientes etiquetas:

{% verbatim %}
{{ Print variable }}
{% endverbatim %}

Este texto aparecerá completamente en su e-mail como:

{{ Print variable }}

 

Filtros

Las variables pueden ser modificadas por los filtros. Los filtros se separan de las variables mediante una pleca (|) y pueden tener argumentos opcionales entre paréntesis. Se pueden encadenar varios filtros. El resultado de un filtro se aplica al resto.

Filtros más frecuentes

Modificar y cambiar el formato de las mayúsculas y minúsculas

capfirst

pone un valor en mayúsculas

La primera letra estará en mayúsculas, el resto en minúsculas. 

{{ contact.NAME|capfirst }}

juan pérez será Juan pérez.

title

devuelve una versión con la primera letra del valor en mayúsculas

Las palabras empiezan con mayúsculas, el resto de caracteres queda en minúsculas.

{{ contact.NAME|title }}

juan pérez será Juan Pérez.

upper

pone un valor en mayúsculas

{{ contact.NAME|upper }}

juan pérez será JUAN PÉREZ.

lower

pone un valor en minúsculas

{{ contact.NAME|lower }}

JUAN PÉREZ será juan pérez.

trunchars

Interrumpe una cadena si es más larga que el número de caracteres especificados. Las cadenas truncadas terminarán con una secuencia de puntos suspensivos (…).

{{ value|truncatechars:8 }}

Si el valor = felicidades, se mostrará Felicida…

Formato de los números

floatformat

Redondea cómo se muestran los valores en coma flotante de su atributo de contacto o parámetro hasta el decimal especificado.

Para que funcionen correctamente, los valores deben escribirse como un número, en lugar de como una cadena. (Los valores no deben escribirse entre comillas como "valor").

Si su plantilla contiene
{{ contact.BALANCE }} y el resultado sería 40,320000, el valor en coma flotante se redondeará a un "n" decimal concreto utilizando:
{{ contact.BALANCE | floatformat: n}}

{{ contact.BALANCE | floatformat: 2}}
Mostrará el número como 40,32, en lugar de 40,320000

{{ contact.BALANCE | floatformat: 0}}
Mostrará el número como 40, en lugar de como 40,320000

Formato de las fechas

time_parse

Convierte el formato de su fecha (introducido como cadena) a un formato de fecha estándar que puede utilizarse con otros filtros

Introduzca el formato de fecha que utilice como un argumento: formatee la fecha/hora exactas para que se mostrara Monday January 2 15:04:05 -0700 MST 2006 si este fuera un valor.

Si su cadena está formateada usando RFC3339 puede utilizar el parámetro dedicado time_parse_rfc3339 sin un argumento.

{{ params.my_date|time_parse:"15:04 02/01/2006” }}

{ params.my_date|time_parse:"Monday 02 January 2006” }}

Nota: Solo se reconocen las palabras para mes y para día en inglés.

date

Muestra la fecha en el formato especificado


Para definir su propio formato, escriba cómo quiere que aparezca el tiempo de referencia formateado según su preferencia y definido para que sea Mon Jan 2 15:04:05 -0700 MST 2006.

Tenga en cuenta que debe añadir una fecha a este filtro.

Obtendrá una fecha de una cadena usando el filtro time_parse.

{{ "14:01 01/06/2018"|time_parse:"15:04 02/01/2006"|date:"Mon Jan 2 15:04:05 2006"}}

Se mostrará como:

Friday June 1 14:01:00 2018

Note: Solo se reconocen las palabras para día y mes en inglés.

 

Tenga en cuenta que:

  • Las abreviaturas y los nombres completos solo son compatibles en inglés
  • Si no se añade un valor se considerará 0
  • La zona horaria predeterminada (si no se añade) es UTC
  • Puede usar las palabras clave am/pm
  • Las maneras más habituales para definir la zona horaria son: las palabras clave específicas (MST, CET, UTC, Asian/Kolkata etc.), o mediante números, +0100 o -0100, para el formato UTC.

Otros filtros

first

devuelve el primer «elemento» de una secuencia, un mapeo o una cadena.

Si su plantilla contiene {{params.array|first}}

y su pedido de la API contiene:

“params” :
{
“array” : [ 1,2,3,4 ]
}

Se mostrará como 1

join

devuelve una cadena que es la concatenación de los elementos de una secuencia

El separador entre elementos es una cadena vacía por defecto. Se puede definir con el primer parámetro opcional.

{{ [1, 2, 3]|join }}

Se mostrará como 123  


{{ [1, 2, 3]|join('|') }}

Se mostrará como 1|2|3

last

devuelve el último «elemento» de una secuencia, un mapeo o una cadena

{{ [1, 2, 3, 4]|last }}

Se mostrará como 4

length

devuelve el número de posiciones de una secuencia o mapeo, o la longitud de una cadena

{% if users|length > 10 %}
   ...
{% endif %}

safe

indica que una cadena no requiere más omisiones de HTML antes del resultado

 

 {{ params.htmltest | safe }}

"params" :{HtmlTest: "<p>Esta es mi frase de prueba.</p>"}

Mostrará un párrafo con formato en el cliente de e-mail del destinatario.

 

{{ params.html }}
"params" :{HtmlTest: "<p>html para</p>"}

Sin el filtro safe, mostrará la etiqueta HTML en el cliente de e-mail del destinatario:

<p>Esta es mi frase de prueba</p>

slice

extrae una fracción de una secuencia, mapeo o cadena

Este filtro puede configurarse para:

A. Hacer un bucle solo con el primer número «n» de elementos de un array.

B. Hacer un bucle con los elementos entre dos posiciones específicas («n» y «m») en el array.

En ambos casos, recuerde que a los elementos de un array se les asigna un número de posición único que comienza con «0» como primera posición (son «índice cero»). 

C. El filtro también puede configurarse para que haga un bucle con los elementos entre dos elementos especificados en un array.

En cada ejemplo, supongamos que su array contiene lo siguiente: 

["a","b","c","d","e","f","g","h",...]

A.
{% for product in params.products|slice:’:5’ %}
{{ product.name - {{ product.price }}
{% endfor %}
Realizará un bucle por las 5 primeras posiciones (0-4) que son: ["a","b","c","d","e"}

B.
{% for product in params.products|slice:’2:3’ %}
{{ product.name - {{ product.price }}
{% endfor %}
Realizará un bucle por las posiciones (2-3) que son: ["c","d"]

C.
{% for product in params.products|slice:’b:d’ %}
{{ product.name - {{ product.price }}
{% endfor %}
El bucle pasará por los elementos especificados, ["b","c","d"]

Probar y solucionar problemas de la plantilla

Para probar y solucionar problemas de su plantilla, consulte esta guía o contacte con nuestro equipo de atención al cliente.

Información relevante: Cuando utilice la característica de «Enviar una prueba» para enviar una versión de prueba de su plantilla de e-mail, las variables de atributos del contacto serán remplazadas con contenido específico para el destinatario en el e-mail de prueba, mientras que las variables de los parámetros transaccionales se quedarán en blanco.

 

Fuentes adicionales de información

El lenguaje de las plantillas de SendinBlue se basa en el lenguaje de programación de plantillas Django.

Esta guía cubre la estructura y los elementos más utilizados del lenguaje de programación de plantillas. A continuación, encontrará una lista exhaustiva de todas las etiquetas y filtros compatibles. Consulte la documentación de Django para obtener más información.

Todas las etiquetas compatibles

autoescape, comment, cycle, filter, firstof, for, if, ifchanged, now, set, spaceless, templatetag, with

Todos los filtros compatibles

escape, safe, escapejs, add, addslashes, capfirst, center, cut, date, default, default_if_none, divisibleby, first, floatformat, get_digit, iriencode, join, last, length, length_is, linebreaks, linebreaksbr, linenumbers, ljust, lower, make_list, phone2numeric, pluralize, random, removetags, rjust, slice, stringformat, striptags, time, title, truncatechars, truncatechars_html, truncatewords, truncatewords_html, upper, urlencode, urlize, urlizetrunc, wordcount, wordwrap, yesno  (Referencia: https://djangobook.com/builtin-template-tags-filters/)

Atención: Si identifica un elemento deseable que aún no se admite, contacte con nuestro equipo de atención al cliente en contact@sendinblue.com para solicitarlo.