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

Nossa linguagem de modelo inclui placeholders e lógica pré-definidos que podem ser usados para inserir conteúdo dinâmico em seu e-mail e modificar como este conteúdo é exibido para o destinatário.

A linguagem do modelo fornece uma estrutura padronizada e comum para criar modelos eficientes e opções de design poderosos.

Dica: a Nova linguagem de modelo substitui uma antiga versão de Linguagem de modelo SendinBlue que usava diferentes sintaxes e a qual era menos robusta. Neste guia, vamos nos referir à Nova linguagem de modelo simplesmente como "a linguagem de modelo".

Antes de começar

Ao criar um e-mail único para enviar para vários destinatários ao mesmo tempo, crie seu e-mail como uma Campanha.

Ao criar um modelo para enviar como e-mail transacional ou a partir de um fluxo de trabalho de Automation, construa e salve como um Modelo.

E-mails usando a linguagem de modelo podem ser ativados para serem enviados pelos seus SendinBlue API v3 calls respectivos (para campanhas ou para e-mails transacionais), fornecendo a ID da campanha ou do modelo. Eles também podem ser enviados por meio do relé SMTP, fornecendo o cabeçalho X-SIB-API com os parâmetros corretos.

Dica: se você não utilizou nossa plataforma transacional (SMTP) antes, você deve solicitar sua ativação. Para verificar, entre em sua conta e acesse esta página. Se você não vir uma tela pedindo para ativar sua conta SMTP e se sua cota for maior que 0, então você está pronto para começar a enviar.

Visão geral

A linguagem de modelo faz uso de variáveis e filtros, os quais são substituídos por valores específicos quando o e-mail é ativado para ser enviado, além de tags, que adicionam lógica para controlar como e se o conteúdo é exibido.

Existem dois tipos de delimitadores disponíveis:

{{ ... }} - “imprime” ou apresenta o resultado de uma variável ou filtro no e-mail
{% ... %} - executa a lógica de uma tag, tal como loop-for.

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

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

 

Tags

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

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

==

verifica se uma expressão é verdadeira

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

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 contact.GENERO == "Masculino" %} Prezado Sr. {{ contact.SOBRENOME }},
{% elif contact.GENERO == "Feminino" %} Prezada Sra. {{ contact.SOBRENOME }},
{% else %} Olá, {% 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 %}

 

Dica: não recomendamos aplicar a tag de comparação if para variáveis que contenham valores “flutuantes” uma vez que eles podem não produzir resultados precisos (Valores flutuantes são aqueles que contêm um número fracionário ao invés de um número inteiro). No entanto, eles podem ser aplicados se o valor por passado como uma string (entre aspas, “assim”).

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.

Pode ser facilmente usado para itens numéricos em um loop:

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

resultará em uma lista como esta:

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

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 configurado para Verdadeiro se esta for a primeira vez no loop.

Isso é conveniente para casos especiais de primeiro item em uma lista, tal como adicionar o filtro "superior" (descrito na seção "Filtros" abaixo) apenas para o primeiro item na lista de exemplo de produtos.

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

Pode apresentar uma lista de produtos como esta:

1. PRIMEIRO PRODUTO - $5.00
2. Segundo produto - $2.00
3. Terceiro produto - $4.00

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

 

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.

 

verbatim

A tag verbatim permite que você use use chaves duplas {{ like this }} em seu e-mail sem que sejam reconhecidas como um elemento de linguagem de modelo. Para escapar {{ }} e imprimir estes símbolos diretamente em seu e-mail, envolva-os nesta tag:

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

Este texto aparecerá completo em seu e-mail como:

{{ Print variable }}

 

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 o resultado dos valores flutuantes do atributo ou parâmetro de seu contato para a casa decimal especificada. 
Para funcionar corretamente, os valores passados devem ser passados como um número, ao invés de uma string.
(Os valores não devem ser passados entre aspas como “valor”.)

Se seu modelo contém 
{{ contact.BALANCE }} e o valor resultante seria  40,320000, a flutuação pode ser arredondada para a casa decimal “n”, usando:
{{ contact.BALANCE | floatformat: n}}

{{ contact.BALANCE | floatformat: 2}}
Resultará em 40,32 ao invés de 40,320000

{{ contact.BALANCE | floatformat: 0}}
Resultará em 40 ao invés de 40,320000

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

Se seu modelo contém {{params.array|first}}

seu pedido da API contém: 

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

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

safe

marca uma string como não requerendo escape de HTML adicional antes da apresentação

 

{{ params.htmltest | safe }}

"params" :{HtmlTest: "<p>This is my test sentence.</p>"}

Apresentará um parágrafo formatado no e-mail de cliente do destinatário.

 

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

Sem o filtro safe, ele exibirá a tag HTML como uma string normal no e-mail de cliente do destinatário:

<p>This is my test sentence</p>

slice

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

Este filtro pode ser configurado para:

A. Loop entre apenas o primeiro número "n" de elementos em uma matriz

B. Loop entre elementos entre duas posições específicas ("n" e "m") em uma matriz

Em ambos os casos, lembre-se que a elementos em uma matriz são atribuídos número de posição única começando com "0" como a primeira posição (eles são "0 indexado").

C. O filtro também pode ser configurado para fazer loop entre dois elementos específicos em uma matriz.

Em cada exemplo, considere que sua matriz contém o seguinte:

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

A.
{% for product in params.products|slice:’:5’ %}
{{ product.name - {{ product.price }}
{% endfor %}
Fará um loop entre as primeiras 5 posições (0-4), ou seja: ["a","b","c","d","e"}

B.
{% for product in params.products|slice:’2:3’ %}
{{ product.name - {{ product.price }}
{% endfor %}
Fará loop entre as posições  (2-3), as quais são: ["c","d"]

C.
{% for product in params.products|slice:’b:d’ %}
{{ product.name - {{ product.price }}
{% endfor %}
Fará loop entre os elementos específicos, ["b","c","d"]

 

Teste e resolução de problemas em seu modelo

Para testar e resolver quaisquer problemas básicos em seu modelo, consulte este guia ou entre em contato com nossa equipe de atendimento ao cliente.

Dica: ao usar o recurso "Enviar um teste" para enviar uma versão de teste do seu modelo de e-mail, variáveis de atributo do contato serão substituídas com conteúdo específico para o destinatário no e-mail de teste, enquanto variáveis do parâmetro transacional aparecerão em branco.

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  (Referência: https://djangobook.com/builtin-template-tags-filters/) 

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.