Usando a linguagem de modelo SendinBlue para criar modelos de e-mail [NOVO]

Ao codificar os modelos de e-mail em HTML para uso na plataforma SendinBlue, você pode usar nosso idioma de modelo para adicionar recursos avançados aos seus e-mails Transacionais ou de Automação.

O idioma de modelo fornece uma estrutura padronizada, comum para modelos mais eficientes e opções de design mais poderosos.

Antes de iniciar

Dica: construa e salve seu modelo na área Meus modelos SMTP. Modelos usando esta linguagem de modelo podem ser ativados para enviar via SendinBlue nossa SMTP API v3 ao fazer uso do v3/smtp/email fornecendo o templateid ou via o transmissor SMTP fornecendo o cabeçalho X-SIB-API com os parâmetros corretos. No momento, elas não são compatíveis com a plataforma SendinBlue Automation ou Campanhas para envio de e-mails em massa, no entanto, este recurso estará disponível no futuro.

Caso não tenha usado nossa plataforma Transacional (SMTP) antes, você pode precisar solicitar sua ativação. Para verificar, entre em sua conta e visite esta página. Se você não vir uma tela pedindo para ativar sua conta SMTP e sua cota for maior que 0, então, você está pronto para começar os envios.

Visão geral

A linguagem dos modelos faz uso de tags para controlar a lógica do modelo e de variáveis e filtros, os quais são substituídos por valores quando o modelo é ativado para envio.

Existem dois tipos de delimitadores disponíveis: {% ... %} e {{ ... }}. O primeiro é usado para executar tags declaratórias, tais como for-loops. Esta última “imprime” ou apresenta o resultado de uma variável ou filtro para o modelo.

Dica: a linguagem do modelo pode ser aplicada para modificar diversos aspectos do seu e-mail, incluindo a linha do assunto, cabeçalho, dentro das tags HTML <body>, e o campo destinatário “para”. Por padrão, HTML é automaticamente livre dentro dos modelos, mas este comportamento pode ser mudado usando a tag autoescape, descrita abaixo em detalhes.

Tags

As tags mais comuns disponíveis para uso nos modelos são for, if e autoescape. Orientações e exemplos para cada uma delas estão incluídas abaixo. 

for

Como exploraremos mais adiante neste guia, for é bastante poderoso quando combinado com seus parâmetros transacionais. Isso permite que você realize trabalhos complexos, como inserção de listas dinâmicas de produtos.

A tag {% for %} for permite que você faça loop, ou repita sobre cada item em uma sequência. Isto é particularmente útil quando o número de itens na sequência é desconhecido no momento de criação de um modelo. 

Aqui estão diversas formas comuns de se usar o for:

for, in

exibe uma lista

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

else

renderiza um bloco de substituição se sua sequência estiver vazia

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

Exibiria “nenhum usuário encontrado”.

reversed

inverte a ordem de impressão dos itens em sua sequência

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

Exibiria uma lista de países, mas em ordem inversa, se comparada com a lista original.

 

Variáveis Loop

Dentro de um bloco for-loop você também pode acessar estas variáveis especiais:

forloop.Counter

Sempre define um inteiro que representa o número de vezes que o loop foi inserido. Este é um indexado único, assim, o primeiro tempo através do loop, forloop.Counter será ajustado como 1.

forloop.Counter0

A repetição atual do loop. (0 indexado)

forloop.Revcounter

Sempre define um inteiro que representa o número de itens restantes no loop. O primeiro tempo através do loop, forloop.Revcounter será ajustado para o número total de itens na sequência que você está atravessando. A última vez no loop, forloop.revcounter será ajustada para 1.

forloop.Revcounter0

O número de repetições a partir do final do loop (0 indexado)

forloop.First

Valor booleano ajustado para Verdadeiro se esta for a primeira vez através do loop. Isto é conveniente para blindagem especial do primeiro item em uma lista.

forloop.Last

Valor booleano ajustado para Verdadeiro se esta for a última vez através do loop. Um uso comum para isto é colocar caracteres separadores (como , ou |) em uma lista de itens.

forloop.Parentloop

Referencia o objeto forloop para o parent loop, no caso de loops aninhados. Aqui está um exemplo:

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

 

Dica: nomes de variáveis de loop distinguem entre maiúsculas e minúsculas.

p. ex.: para atribuir um valor numérico (contando a partir do 1) para cada item impresso a partir da sua repetição, use {{ forloop.Counter }}:

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

if

A lógica poderosa oferecida pelo if permite que você adicione ou remova blocos inteiros de conteúdo dentro do seu modelo (ou modifique conteúdos dentro de um bloco). Efetivamente, isso expande a utilidade de um simples modelo para múltiplos cenários.

A tag {% if %} permite que você teste se uma expressão é verdadeira (ou se uma matriz está vazia), e modifique o conteúdo do e-mail com base no resultado. Você também pode testar por valores falsos, múltiplas condições e múltiplos ramos.

Aqui estão diversas formas comuns de se usar o if:

if

Verifica se um valor é verdadeiro ou se uma matriz não está vazia

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

==

verifica se uma expressão é verdadeira

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

if, in

verifica se um valor (substring) existe dentro de uma string ou dentro de uma matriz

{% if “@example.com" in "bob@example.com" %}
This appears since "@example.com" is a substring of "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

procura por valores falsos

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

and / or

avalia múltiplas condições

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

avalia múltiplos ramos

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

Dica: por padrão, a SendinBlue libera o conteúdo HTML (e JS) de todas as variáveis. Isso significa que qualquer HTML dentro de uma variável será executado e impresso como texto. Por exemplo, se o conteúdo da sua variável for <h1>Meu título</h1>, então seu modelo resultaria exatamente neste texto dentro do seu e-mail: <h1>Meu título</h1>, em vez de resultar na frase “Meu título” formatada como um título H1.

A tag autoescape controla o comportamento atual do auto-escaping. Uma vez que os modelos SendinBlue realizam o autoescape do HTML por padrão, você precisará aplicar esta tag normalmente para desabilitar o auto-escaping dentro de um bloco específico. O bloco deve ser fechado com uma tag de encerramento endautoescape.

Vamos rever um exemplo comum quando desabilitar o autoescape pode ser útil. Vamos dizer que você transmita produtos em uma variável, mas que cada produto requeira formatação única.

Se autoescape for usada desta forma:

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

Então o auto-escaping será desabilitado para a variável {{ params.my_html }}. Agora, se o conteúdo da sua variável for <h1>Meu título</h1>, ele será exibido como um título H1.

As únicas exceções são variáveis já marcadas como seguras do escaping, seja pelo código que faz parte da variável ou porque o filtro safe foi aplicado.

Variáveis

Existem três tipos de variáveis disponíveis e cada uma delas está descrita abaixo.  

Dica: ao usar o recurso "Enviar um teste" para enviar uma versão de teste do seu modelo de e-mail, as variáveis não serão substituídas por conteúdo específico do destinatário neste e-mail de teste. Em vez disso, você verá as variáveis exatamente como elas foram codificadas no seu modelo.

1. Variáveis pré-definidas  

Estão disponíveis para todos os usuários SendinBlue:

{{ mirror }}

insere um link para visualizar seu  e-mail como uma página de internet

Esta variável não é obrigatória.

Normalmente colocada na parte de cima de um e-mail e formatada como um link deste tipo:

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

{{ unsubscribe }}

insere um link para cancelar a inscrição a partir dos seus e-mails

Qualquer e-mail não-transacional enviado via SendinBlue deve incluir um link de cancelamento de inscrição.

Normalmente colocada no rodapé e formatada como um link deste tipo:

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

 

2. Atributos de contato   

Este tipo de variável contém dois elementos e é estruturada da seguinte forma:

{{ contact.attributeNAME }}

Atributo = nome do seu atributo de contato SendinBlue como aparece em sua Página de contatos na SendinBlue. Atributos são sempre escritos em MAIÚSCULAS e nunca contém espaços.

P. ex.:, para inserir o telefone de um contato, onde o atributo é chamado PHONE, use: {{ contact.PHONE }}

Se o nome do atributo de contato contiver um hífen, por exemplo, CELL-PHONE, formate sua variável da seguinte forma, então: {{ contact|key:"ATTRIBUTE" }}.  

p. ex.: {{ contact|key:"CELL-PHONE" }}

3. Parâmetros transacionais

As variáveis dos parâmetros transacionais também contém dois elementos e são estruturadas da seguinte forma:

{{ params.parameterNAME }}

parameterNAME = nome do seu parâmetro transacional, formatado e escrito exatamente como transmitido via o API.

P. ex.: para inserir uma lista de produtos onde o parâmetro é chamado de PRODUCTS, use: {{ params.PRODUCTS }}.

Agora, vamos considerar um caso comum de uso: a geração de uma lista de produtos comprados por um cliente. Uma vez que o número de produtos comprados varia de acordo com o cliente, podemos combinar um for-loop com seu parâmetro transacional PRODUCTS, como neste exemplo:  

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

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

Isto produziria uma lista desordenada, em tópicos de produtos, incluindo nome e preço, como esta e a lista de cada destinatário poderia incluir um número único de produtos:  

  • Product 1 - $10
  • Product 2 - $10
  • Product 3 - $10

Dica: recomendamos evitar o uso de hífens ou de quaisquer caracteres especiais no nome de sua variável/parâmetro. Se não puder evitar, você pode usar {{ params|key:”parameter-NAME” }}. Você pode aninhar filtros diversas vezes, como em {{ params|key:”my-product”|key:”my-product-name” }}.

Matrizes

Ao usar uma matriz, você pode acessar todos os elementos individualmente. Especifique suas IDs da seguinte forma: params.parameterARRAY.ID.parameterNAME. Por exemplo: {{ params.PRODUCTS.1.NAME }}.

Filtros

Variáveis podem ser modificadas por filtros. Filtros são separados da variável por um símbolo de barra vertical (|) e pode apresentar argumentos opcionais entre parênteses. Diversos filtros podem ser encadeados. O resultado de um filtro é aplicado ao próximo.

Filtros mais usados

Alterando e formatando a capitalização das palavras

capfirst

capitaliza um valor

O primeiro caractere será colocado em maiúscula, todos os outros ficarão em minúsculas.

{{ contact.NAME|capfirst }}

john doe resultará em John doe.

title

retorna uma versão título do valor

As palavras começarão com letras maiúsculas, todos os outros caracteres permanecendo em minúsculas.

{{ contact.NAME|title }}

john doe resultará em John Doe.

upper

converte um valor para maiúsculas

{{ contact.NAME|upper }}

john doe resultará em JOHN DOE.

lower

converte um valor para minúsculas

{{ contact.NAME|lower }}

JOHN DOE resultará em john doe.

trunchars

Trunca uma string se ela for maior que o número específico de caracteres. Strings trucadas terminarão com uma sequência de reticências (…).

{{ value|truncatechars:9 }}

If value = congratulations, it would output as congratul…

Formatando números

floatformat

arredonda um número para uma precisão dada, usando a lógica comum 

{{ 42.55|floatformat:0 }}

Será apresentado como 43

{{ 42.55|floatformat:1 }}

Será apresentado como 42.5

Formatando datas

time_parse

Converte seu formato de data (transmitido como uma string) para um formato de data padrão, o qual pode ser usado com outros filtros

Transforma o formato da sua data atual como em um argumento: formata exatamente data/hora como Monday, January 2 15:04:05 -0700 MST 2006 seria exibido se este fosse o valor.

Se sua string for formatada usando RFC3339, você pode usar o parser dedicado time_parse_rfc3339 sem um argumento.

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

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

Observação: apenas as palavras em inglês para dia e mês são reconhecidas.

date

Imprime a data no formato especificado
Para definir seu próprio formato, escreva como seria a hora de referência, definida para Mon Jan 2 15:04:05 -0700 MST 2006, formatada da sua forma.

Observe que você deve transmitir uma data para este filtro.

Você vai obter uma data a partir de uma string usando o filtro time_parse.

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

Resultará em:

Fri Jun 1 14:01:00 2018

Observação: apenas as palavras em inglês para dia e mês são reconhecidas.

 

Atenção:

  • Abreviações e nomes completos de dia e mês só são reconhecidos em inglês
  • Se um valor não for transmitido, ele será considerado igual a 0
  • O fuso-horário padrão (se não transmitido) é o UTC
  • Você pode usar as palavras-chave am/pm
  • As formas mais comuns de definir o fuso-horário são: palavras-chave dedicadas (MST, CET, UTC, Asian/Kolkata etc.), ou como números, +0100 ou -0100, para UTC.

Outros filtros

first

retorna o primeiro "elemento" de uma sequência, um mapeamento ou uma string

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

Resultará em 1

join

retorna uma string que é a concatenação dos itens de uma sequência

Por padrão, o separador entre elementos é uma string vazia. Você pode definir isso com o primeiro parâmetro opcional.

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

Resultará em 123  


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

Resultará em 1|2|3

last

retorna o último "elemento" de uma sequência, um mapeamento ou uma string

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

Resultará em 4

length

retorna o número de itens de uma sequência de mapeamento ou o comprimento de uma string

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

slice

extrai um pedaço de uma sequência, um mapeamento ou uma string

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

Repetirá sobre 2 e 3

{{ '12345'|slice(1, 2) }}
Resultará em 23

Fontes adicionais de documentação

A linguagem de modelo usada pela SendinBlue é baseada na Linguagem de modelo Django.

Este guia engloba as estruturas e elementos mais relevantes e frequentemente usadas em linguagem de modelos. Abaixo, você encontra uma lista exaustiva de todas as tags e filtros suportados. Consulte esta documentação Django para mais detalhes.

Todas as tags reconhecidas

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

Todos os filtros compatíveis

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

Observação: caso identifique um elemento desejável ainda não compatível, entre em contato com nossa equipe de atendimento ao cliente por meio do contact@sendinblue.com para fazer sua solicitação.