Referência
Linguagem de templates Temple
O Temple preenche variáveis, valores padrão e condicionais nos assuntos, no HTML e no texto dos e-mails no momento do envio. Sintaxe, valores verdadeiros e falsos, escape e onde o Temple é executado.
O Temple é a pequena linguagem de templates do Emailit para linhas de assunto, HTML e texto simples. Ele não é Liquid nem Handlebars: tem suporte a variáveis, caminhos aninhados, valores padrão e blocos if/else, e nada mais. Os templates guardam os placeholders como você os escreve, e o Temple os preenche quando um e-mail é enviado pela API, por uma automação ou por uma campanha.
A sintaxe em resumo
{{first_name}} Variable
{{user.name}} {{items.0.sku}} Nested property and list item
{{first_name|"there"}} Default when the value is missing or null
{{#if plan}} … {{else}} … {{/if}} Conditional, with an optional elseO Temple não tem loops, filtros, helpers, partials nem funções personalizadas. O único operador é o | de valor padrão.
Variáveis
Hello {{first_name}}- O Temple substitui
{{first_name}}pelo valor defirst_nameque você fornece. Os espaços dentro das chaves são ignorados, então{{ first_name }}também funciona. - Os nomes diferenciam maiúsculas de minúsculas:
{{First_Name}}não corresponde afirst_name. - Um valor ausente ou
nullvira uma string vazia. Os placeholders desconhecidos desaparecem em vez de aparecer no e-mail. - Os valores são convertidos em texto. Números e booleanos aparecem como foram escritos (
42,true), e as listas são unidas com vírgulas (["a","b"]viraa,b). Um objeto é renderizado como[object Object], então aponte para um dos campos dele.
Propriedades aninhadas e itens de lista
Use pontos para acessar objetos e números para posições em listas, começando em 0:
{{user.name}}
{{order.items.0.sku}}{
"user": { "name": "Ada" },
"order": { "items": [{ "sku": "A1" }, { "sku": "B7" }] }
}Como o ponto separa os segmentos do caminho, não é possível acessar uma chave que contenha um ponto. Use chaves sem pontos.
Valores padrão
Adicione | e um valor alternativo para usar quando o valor estiver ausente ou for null:
Hi {{first_name|"there"}},
Your company: {{company|'Not set'}}Aspas duplas, aspas simples ou nenhuma aspa funcionam. O valor padrão não é usado para uma string vazia, 0 ou false; esses valores são renderizados como vazio, 0 e false. Um valor padrão não pode conter o caractere }.
Condicionais
{{#if plan}}
Thanks for being on the {{plan}} plan.
{{else}}
You're on the free plan. Upgrade anytime from your dashboard.
{{/if}}{{else}}é opcional.- Uma condição é falsa quando o valor está ausente ou é
null,false,0, uma string vazia""ou uma lista vazia[]. Qualquer outro valor é verdadeiro, incluindo a string"0", a string"false"e um objeto vazio. - Uma condição é um único caminho de variável, como
planouuser.is_admin. Não existem==,and,or,notnemunless. Para criar uma ramificação com base em um valor, calcule um booleano no seu código e passe-o, por exemplo"is_pro": true. - Escreva
{{else}}e{{/if}}exatamente como mostrado, sem espaços dentro das chaves. - O Temple processa primeiro as condicionais e depois as variáveis.
Os blocos podem ser aninhados. O Temple resolve primeiro os blocos mais internos, então cada {{else}} e cada {{/if}} pertencem ao próprio {{#if}}:
{{#if plan}}
{{#if annual}}Billed yearly.{{else}}Billed monthly.{{/if}}
{{else}}
You're on the free plan.
{{/if}}O aninhamento funciona até 10 níveis de profundidade.
Escape e caracteres especiais
Os valores não passam por escape de HTML. O Temple insere os valores exatamente como você os passa. Um valor como Tom & Jerry ou <b>Ada</b> entra no HTML sem alterações, então faça o escape de qualquer texto fornecido por usuários no seu código antes de passá-lo. As mesmas variáveis preenchem o assunto, o HTML e o texto, então um valor com escape como Tom & Jerry também aparece assim no assunto e no texto. Se isso importar, passe uma variável separada, com escape, para o HTML.
Isso também significa que você pode passar HTML pronto, como uma tabela com as linhas de um pedido renderizada pelo seu código, como uma única variável.
Não existe sintaxe de escape para chaves duplas. O Temple trata qualquer coisa entre {{ e }} como um placeholder e a remove se não houver valor. As chaves simples, como as do CSS, não são afetadas. Os valores são inseridos uma vez e não são interpretados de novo, então, para mostrar chaves duplas literais, coloque-as em uma variável:
{
"html": "<p>Write {{example}} in your template to show the first name.</p>",
"variables": { "example": "{{first_name}}" }
}Onde o Temple é executado
| Onde | O Temple é executado? | O que você pode usar |
|---|---|---|
API de e-mail com um template |
Sempre | As variables que você passa, e global |
API de e-mail com subject, html ou text inline |
Quando variables tem pelo menos uma chave, ou o conteúdo usa {{global.…}} |
As variables que você passa, e global |
| Automações, etapa Send email | Em todos os envios | Campos do contato, tags, score, contact, global, unsubscribe_url, manage_subscriptions_url, payload, meta, run, automation e step, além de email nas automações do contexto Email. Consulte E-mails de automações. |
| Campanhas, envios de teste e Preview as contact | Sempre | Campos do contato, cf, custom_fields, tags, score, global, unsubscribe_url, manage_subscriptions_url, webview_url e contact. Consulte Campanhas. |
| SMTP relay | Não | Nada. A mensagem é enviada como você a montou. |
| Editores do painel e as prévias deles | Não | Os editores inserem placeholders, e as prévias deles os mostram sem renderizar. Os editores MJML (alfa) também mostram a prévia do Temple com dados de exemplo. Para ver uma campanha renderizada para um contato, use Preview as contact. |
E-mails da API
Passe o alias de um template ou um ID tem_ e um objeto variables. Os campos que você envia na requisição (subject, html, text) substituem os do template, e depois o Temple renderiza o assunto, o HTML e o texto.
{
"from": "Acme <hello@acme.com>",
"to": "ada@example.com",
"template": "welcome-email",
"variables": {
"first_name": "Ada",
"plan": "Pro",
"activation_url": "https://acme.com/activate?token=8f3k2",
"cf": { "company": "Analytical Engines Ltd" }
}
}Os editores do painel inserem {{cf.<key>}} para os campos personalizados dos contatos. Nos envios pela API, nada é buscado nos seus contatos, então forneça você mesmo esses valores em cf, como no exemplo. O mesmo vale para {{unsubscribe_url}}: passe o seu próprio link de descadastro se o template o usar. Os valores globais são a exceção: {{global.<key>}} é preenchido a partir do workspace, a menos que as suas variables tenham uma chave global própria.
Você também pode enviar conteúdo inline com variables e sem template. Consulte Enviar um e-mail.
E-mails de automações
Em todos os envios, a etapa Send email renderiza o assunto, o HTML e o texto com o Temple, venham eles do template ou de substituições definidas na etapa.
As automações de contatos colocam os campos do contato no nível superior, então estes funcionam:
{{email}},{{first_name}}e{{last_name}}{{cf.<key>}}ou{{custom_fields.<key>}}para os campos personalizados, por exemplo{{cf.plan}}.{{cf.<key>}}é a forma usada pelas campanhas e pelos editores.{{tags}}, as tags do contato comovip, customer, e{{#if tags}}…{{/if}};{{score}}, a pontuação de lead{{unsubscribe_url}}, o link de descadastro do contato, também enviado como cabeçalhosList-Unsubscribede descadastro em um clique nos e-mails de marketing, e{{manage_subscriptions_url}}, a página de gerenciamento de inscrições dele{{contact.*}}, o mesmo contato como objeto, por exemplo{{contact.first_name}}
Todas as automações também recebem {{global.*}}, os valores globais do workspace, {{payload.*}}, os dados do evento que disparou a execução, e {{meta.*}}, os metadados da execução. Elas também recebem {{run.id}}, {{automation.id}}, {{automation.name}} e {{step.key}}, a chave da etapa Send email. As automações de e-mail acrescentam {{email.*}}, o e-mail que iniciou a execução, como {{email.mail_from}}. As automações de e-mail e de evento não têm um contato no nível superior, então use {{payload.*}} ou defina o destinatário e o assunto na etapa.
Campanhas
As campanhas renderizam o assunto, o HTML e o texto com o Temple para cada destinatário, seja qual for o editor usado para criá-las. Os envios de teste e Preview as contact renderizam da mesma forma. As variáveis vêm do contato destinatário:
{{first_name}},{{last_name}}e{{email}}{{unsubscribe_url}}, o link de descadastro do destinatário, e{{manage_subscriptions_url}}, a página de gerenciamento de inscrições dele{{cf.<key>}}ou{{custom_fields.<key>}}para os campos personalizados, por exemplo{{cf.plan}}{{tags}}, as tags do contato comovip, customer, e{{score}}, a pontuação de lead{{global.<key>}}, um valor global, por exemplo{{global.offer_url}}{{contact.*}}, os mesmos campos como objeto, por exemplo{{contact.first_name}}
Os campos vazios do contato contam como ausentes, então os valores padrão se aplicam: {{first_name|"there"}} renderiza there para um contato sem nome. Os envios de teste para um endereço que pertence a um contato do workspace usam os dados desse contato. Nos outros endereços, {{email}} é preenchido com o endereço de teste e os nomes e os campos personalizados ficam vazios.
As tags de mesclagem de campanhas escritas antes de as campanhas usarem o Temple continuam funcionando. Os nomes first_name, last_name, email e unsubscribe_url, e o prefixo cf., não diferenciam maiúsculas de minúsculas, então {{FIRST_NAME}} ainda funciona. As chaves dos campos personalizados precisam corresponder exatamente. Consulte Tags de mesclagem de campanhas.
SMTP
O SMTP relay aceita uma mensagem pronta. Não há busca de template nem passagem pelo Temple, então monte o HTML final antes de enviar, ou use a API ou uma automação se precisar de variáveis.
Conferir os templates antes de publicar
O Emailit não rejeita um template nem um envio por causa de sintaxe do Temple quebrada. Os erros normalmente aparecem como texto faltando ou chaves sobrando no e-mail entregue. Os templates MJML (alfa) são a exceção: ao salvar um deles, o Emailit verifica o Temple e rejeita blocos desbalanceados. Antes de publicar:
- Confira se cada
{{#if …}}tem um{{/if}}correspondente e se cada{{tem um}}de fechamento. - Envie a versão em rascunho para você mesmo pelo ID
tem_dela, comvariablesrealistas, incluindo valores ausentes e vazios, para ver os dois lados de cada condição. Consulte Versões de templates. - Em uma campanha, use Preview as contact com contatos que tenham e que não tenham cada valor e depois envie um teste. Consulte Testar e agendar.
Exemplos
Uma saudação com valor alternativo:
Hi {{first_name|"there"}},Um bloco que depende do plano:
{{#if plan}}
Your plan: {{plan}}
{{else}}
Upgrade anytime from your dashboard.
{{/if}}Um assunto com um valor aninhado:
Order {{order.number}} has shipped, {{user.first_name|"friend"}}