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

Cuando programe plantillas de e-mail en HTML para usarlas en la plataforma SendinBlue, puede utilizar nuestro lenguaje de plantillas para agregar funcionalidades avanzadas a sus e-mails transaccionales.

El lenguaje de programación de nuestras plantillas proporciona una estructura estandarizada y habitual para lograr plantillas más eficientes y opciones de diseño más potentes. 

Antes de comenzar

Información relevante: Cree y guarde su plantilla en la sección Mis plantillas SMTP. Las plantillas realizadas con este lenguaje se pueden activar mediante nuestra SMTP API v3 de SendinBlue cuando haga una llamada a v3/smtp/email al mismo tiempo que proporciona el templateid o mediante el relay SMTP proporcionando el encabezado X-SIB-API con los parámetros adecuados. Actualmente no son compatibles con las plataformas de automatización ni de campañas de SendinBlue para enviar correos masivos, sin embargo, esta funcionalidad estará disponible en el futuro.

Si no ha usado nuestra plataforma transaccional (SMTP) anteriormente, puede que necesite solicitar su activación. Para comprobarlo, inicie sesión en su cuenta y visite esta página. Si no aparece un aviso solicitándole que active la cuenta SMTP y el límite es superior a 0 significa que todo está preparado para comenzar con los envíos.

Información general

El lenguaje de la plantilla utiliza etiquetas para controlar la lógica de la plantilla, y variables y filtros que se sustituyen por valores cuando se activa el envío de la plantilla.

Hay dos tipos de delimitadores disponibles: {%... %} y {{... }}. El primero se utiliza para ejecutar etiquetas de orden, como for-loops. El otro «imprime» o muestra el resultado de una variable o filtro en la plantilla.

Información relevante: El lenguaje de la plantilla se puede utilizar para modificar varios aspectos de su e-mail, entre los que se incluyen la línea del asunto, el preencabezado, el contenido entre las etiquetas HTML <body> y el campo del receptor «para». El HTML no se tiene en cuenta de manera predeterminada en las plantillas, pero se puede evitar utilizando la etiqueta autoescape que se describe más abajo.

Etiquetas

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

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.

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 ajustado a Verdadero si es la primera vez pasa por el loop. Esto es útil para el uso especial de la mayúscula para el primer artículo en una lista.

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 %}

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.SUBSCRIBED %}
<b>Thank you for your support!</b>
{% endif %}

 

{% if params.users %}
<ul>
{% for user in params.users %}
<li>{{ user.username }}</li>
{% endfor %}
</ul>
{% 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, 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 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 %}

 

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.

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 }}.

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 un número a una precisión determinada usando la lógica común 

{{ 42.55|floatformat:0 }}

Se mostrará como 43

{{ 42.55|floatformat:1 }}

Se mostrará como 42.5

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.

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

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 %}

slice

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

{% for i in [1, 2, 3, 4, 5]|slice(1, 2) %}
{% endfor %}

Se mostrarán como 2 y 3


{{ '12345'|slice(1, 2) }}
Se mostrará como 23

 

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

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.