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.
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> |
|
else |
renderiza um bloco de substituição se sua sequência estiver vazia |
<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 %} |
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 %}
{% if params.users %} |
|
== |
verifica se uma expressão é verdadeira |
{% if coupon == “WELCOME” %} |
|
if, in |
verifica se um valor (substring) existe dentro de uma string ou dentro de uma matriz |
{% if “@example.com" in "bob@example.com" %}
{% if "Piano" in params.types %} |
|
not |
procura por valores falsos |
{% if not user.subscribed %} |
|
and / or |
avalia múltiplas condições |
{% if temperature > 10 and temperature < 55 %}
{% if contact.LANG == “FR” and contact.COUNTRY == “Canada” %}
{% if contact.COUNTRY == “United States” or contact.COUNTRY == “Canada” %} |
|
elif, else |
avalia múltiplos ramos |
{% if event.paid %} |
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 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 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 %} |
|
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) %} Repetirá sobre 2 e 3 |
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.