> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Layouts de email reutilizáveis e responsivos, montados com componentes MJML para funcionar em todos os clientes de email e personalizados com Liquid.

![O editor visual de email, com a árvore de estrutura, o email e as configurações do botão selecionado](https://www.notifuse.com/docs/assets/screenshots/editor.png)

## Visão geral

Os templates de email são montados em um editor visual de arrastar e soltar. Eles usam o framework MJML, para funcionar em todos os clientes de email e dispositivos, e Liquid para personalizar com variáveis como `{{ contact.first_name }}`.

Cada atualização cria uma nova versão, o que guarda o registro do conteúdo já enviado. As campanhas de broadcast e as notificações transacionais usam templates.

## Recursos do editor de templates

- Edição por arrastar e soltar
- Layouts responsivos que se adaptam a telas de celular
- Blocos prontos: cabeçalhos, rodapés, botões, imagens e seções de conteúdo
- Configurações de marca: cores, fontes, logos e estilos
- Uma pré-visualização ao vivo do email antes do envio

## Começar um novo template

**Novo modelo** abre uma janela onde você escolhe o ponto de partida do template:

- **Galeria**: 15 emails prontos, por caso de uso: código de verificação, redefinição de senha, confirmação de inscrição, convite para a equipe, recibo de pagamento, confirmação de pedido, pedido enviado, carrinho abandonado, promoção, newsletter, anúncio de produto, convite para evento, boas-vindas, reconquista e confirmação de cancelamento de assinatura. Clique em um deles para vê-lo no desktop ou no celular, com a categoria, o assunto e as variáveis que um envio precisa fornecer, e depois em **Usar este modelo**.
- **Seus templates**: uma cópia de um dos seus templates, que mantém o modo de editor dele.
- **Simples**: um logo, um parágrafo e o rodapé.

Um modelo da galeria vem no idioma padrão do workspace, com uma tradução para cada outro idioma do workspace que a galeria cobre (inglês, francês, espanhol, alemão, catalão, português do Brasil, japonês e italiano). O nome, a categoria, o assunto, o texto de pré-visualização e os dados de teste já vêm preenchidos, e o logo e o nome do workspace substituem os do exemplo quando o workspace os tem; escolha o remetente em **Configurações**.

Aberta a partir de uma newsletter, de uma lista ou de uma notificação transacional, a janela mostra só os modelos da categoria necessária.

As imagens da galeria são placeholders servidos pela sua instância do Notifuse, em `https://<your API endpoint>/console/gallery/`. Substitua-as pelas suas antes de enviar: o destinatário só as vê enquanto a sua instância estiver acessível pela Internet nesse endereço.

## Modos do editor

Ao criar um template, você escolhe como o email dele é escrito:

- **Visual**: o editor de arrastar e soltar, onde blocos, estilos e variáveis Liquid são editados no próprio lugar.
- **Código (MJML)**: você mesmo escreve o MJML, com Liquid, em um editor de código com pré-visualização ao vivo.

O modo do editor é definido na criação do template e não pode ser alterado depois. Para levar um design para o outro editor, crie um novo template nesse modo e copie o conteúdo com o menu **Importar / Exportar** de cada editor:

- **Do código para o visual**: no template de código, use **Exportar MJML**; no novo template visual, use **Importar → MJML** com esse arquivo.
- **Do visual para o código**: no template visual, use **Exportar → MJML**; no novo template de código, use **Importar MJML** com esse arquivo.

Confira a pré-visualização depois de copiar. O editor visual recusa os componentes MJML que ele não suporta.

O Liquid colocado entre blocos é mantido. Um arquivo MJML exportado pelo Notifuse devolve seus blocos Liquid e suas condições de exibição. Em qualquer outro arquivo MJML, um trecho com Liquid entre blocos (por exemplo, um loop `{% for %}` em volta de seções) vira um bloco Liquid com esse código tal como foi escrito, que você passa a editar como código.

No sentido inverso, escreva o Liquid dentro de links com aspas simples (`{{ link | append: '?ref=mail' }}`): um texto entre aspas duplas nesse lugar não sobrevive à exportação.

O novo template tem um ID próprio. Aponte para ele seus broadcasts, notificações transacionais e automações, e depois exclua o antigo.

## Títulos

Os blocos de texto do editor visual contêm títulos de verdade, de **Título 1** a **Título 6**, para que os leitores de tela possam listar as seções de um email e pular entre elas (WCAG 2.2, critério de sucesso 1.3.1). Escolha o nível da linha atual no menu **estilo do texto**, no início da barra de ferramentas, ou digite `# ` (ou `## `, `### `…) no início de uma linha. O canvas mostra o nível de cada título ao lado dele; essa marca não faz parte do email.

**Estrutura**: um título deve descer no máximo um nível em relação ao anterior (um H2 depois de um H1, e não um H3). O editor nunca recusa um nível, já que mover ou ocultar um bloco pode mudar a ordem depois, mas marca o nível que pula outro: ao lado do nível no menu, com um selo no bloco Texto e em um quadro **Estrutura de títulos** acima da pré-visualização. Esse quadro lê o email tal como ele é enviado, incluindo os títulos escritos por blocos Liquid.

**Aparência**: o tamanho, o peso, a altura da linha e o espaçamento de cada nível, e opcionalmente a fonte e a cor, são definidos uma vez por template em **Atributos padrão → Títulos**. O Notifuse grava esses valores em cada título no momento do envio, para que todos os clientes de email os exibam. Um título usa a fonte e a cor do seu bloco Texto, a menos que o nível dele defina as próprias.

O editor guarda esses estilos em um bloco `mj-style` do template, adicionado com o primeiro título. Se você editar esse bloco à mão, a seção **Títulos** mostra uma mensagem e deixa de editá-lo. Os templates que já tinham títulos mantêm a aparência até você alterar **Títulos**.

## Biblioteca de blocos salvos

No editor visual, a aba **Biblioteca**, ao lado de **Estrutura**, reúne os blocos salvos no workspace. Eles aparecem como prévias, dos mais recentes para os mais antigos, com uma busca e um filtro para seções e blocos de conteúdo. Abaixo deles ficam os blocos básicos: seção, wrapper, texto, imagem, botão, divisor, espaçador, social, HTML bruto e Liquid.

Para adicionar um bloco ao email:

- **Inserir**: passe o mouse sobre um bloco salvo e clique em **Inserir**, ou clique em um bloco básico. Ele entra depois do bloco selecionado (ou no fim do email, quando nada está selecionado) e passa a ser o bloco selecionado; a confirmação oferece desfazer. Quando a seleção não aceita o bloco, a dica dele diz o que selecionar no lugar, como uma coluna para um texto.
- **Arrastar**: arraste um bloco salvo ou básico para o email. Uma linha mostra onde ele vai ficar, ou um quadro tracejado no caso de uma coluna ou de um wrapper vazio. Sobre um lugar que não o aceita, um rótulo explica o motivo, como "Vai dentro de uma coluna" para um texto solto entre seções. Mantenha o ponteiro perto do topo ou da base do email para rolá-lo, e pressione Escape para cancelar. Os blocos só podem ser arrastados para o email, não para a árvore de estrutura.

Para salvar um bloco, selecione-o e use o botão de salvar na barra de ferramentas dele. A caixa de diálogo sugere um nome a partir do conteúdo do bloco, ou pode substituir um bloco salvo existente do mesmo tipo.

Os blocos salvos ficam disponíveis em todos os templates do workspace. Um template que já contém um bloco salvo mantém a própria cópia, que não muda quando o bloco salvo é substituído ou excluído. Depois que um novo bloco é salvo, a biblioteca abre nele.

Para gerenciar um bloco salvo, abra o menu **…** no cartão dele na biblioteca. O menu aparece no editor aberto pela página Templates, para os membros que podem editar templates:

- **Renomear**: digite o novo nome e pressione Enter, ou Escape para manter o antigo.
- **Substituir pelo bloco selecionado**: antes, selecione no email um bloco do mesmo tipo.
- **Duplicar**: adiciona uma cópia, com o nome do bloco seguido de "(cópia)".
- **Excluir**: remove o bloco da biblioteca, para todos os templates do workspace.

Os templates que já contêm o bloco não mudam.

![A aba Biblioteca do editor visual, com os blocos salvos exibidos como prévias e Inserir ao passar o mouse](https://www.notifuse.com/docs/assets/screenshots/templates_saved_blocks.png)

Os botões **+** da árvore de estrutura também listam todos os blocos salvos, na aba **Blocos salvos**. Os blocos que podem ir naquele lugar aparecem primeiro, com uma prévia ao passar o mouse. Os outros ficam em cinza sob "Não disponível aqui", com o motivo, como "Vai dentro de uma coluna". Os botões **+** abrem na última aba que você usou.

## Uso

Os templates são usados em todo o Notifuse para:

- **Campanhas de broadcast**: campanhas de email em massa enviadas às suas listas de contatos
- **Notificações transacionais**: emails automáticos disparados por ações dos usuários
- **Emails de confirmação dupla**: enviados quando contatos anônimos se inscrevem em listas
- **Emails de boas-vindas**: enviados quando os contatos confirmam a inscrição em listas
- **Confirmações de cancelamento de assinatura**: enviadas quando os contatos cancelam a assinatura

![A página Templates, com a categoria de cada template, onde ele é usado, o remetente e a última versão](https://www.notifuse.com/docs/assets/screenshots/templates.png)

## Excluir um template

Excluir um template o remove da lista de templates e de todos os seletores de template, mas o Notifuse o guarda com todas as versões. As mensagens já enviadas foram renderizadas a partir delas, e o histórico de mensagens e os relatórios de broadcast continuam a exibi-las.

Por isso, um template excluído mantém o ID. A criação de um novo template com o mesmo ID é recusada, e o `templates.update` da API responde `404` para ele. Dê outro ID ao novo template.

Excluir um template tira do ar as [versões web](#view-in-browser) dos emails enviados com ele.

Os templates gerenciados por uma integração, como os emails de autenticação do [Supabase](https://www.notifuse.com/pt/docs/integrations/supabase.md), não podem ser excluídos.

## Versão em texto

Todo email que o Notifuse envia leva duas versões do conteúdo: o HTML e uma versão em texto simples gerada a partir dele, a menos que você escreva a sua. Clientes de email só de texto, alguns relógios e os leitores de tela exibem a versão em texto, e os filtros de spam tratam melhor um email com as duas versões do que um só em HTML.

Por padrão, a versão em texto é gerada a cada envio a partir do HTML final, então não há nada para escrever nem para manter atualizado:

- títulos e parágrafos mantêm as quebras de linha, e as listas viram `- item` ou `1. item`;
- um link vira o rótulo seguido da URL entre parênteses, como `Shop the sale (https://example.com/sale)`; uma imagem com link usa o texto `alt` como rótulo;
- o conteúdo oculto (o texto de pré-visualização da caixa de entrada, os elementos com estilo `display:none`) e os pixels de rastreamento ficam de fora.

Os links são os do HTML, com o mesmo rastreamento de cliques e os mesmos parâmetros UTM, decididos para cada destinatário como no HTML, e um clique na versão em texto conta como qualquer outro. Se o seu provedor de email reescreve os links para o próprio rastreamento de cliques (SendGrid, Mailgun ou Postmark, quando isso está ativado do lado deles), ele também reescreve os da versão em texto.

Um email cujo HTML não tem texto nenhum, como uma única imagem sem `alt`, é enviado só em HTML.

Para ver a versão em texto antes de enviar, abra o modo **Versão em texto** ao lado de **Editar** e **Visualizar** no editor visual, a aba **Versão em texto** do editor MJML ou a aba **Versão em texto** da pré-visualização do template. Eles mostram o texto montado a partir dos seus dados de teste. Pela API, [`templates.compile`](https://www.notifuse.com/docs/api-reference/compile-template.md) o retorna no campo `text`.

### Escrever a sua

A versão automática serve para a maioria dos emails. Para um texto diferente, como um mais curto ou sem os links repetidos do layout, escolha **Personalizado** no modo **Versão em texto** (ou na aba **Versão em texto** do editor MJML) e escreva o texto você mesmo. Ele parte da versão automática, com as variáveis, para que você edite em vez de começar do zero.

- **O Liquid funciona como no assunto.** `{{ contact.first_name }}`, as condições e os loops são renderizados para cada destinatário. Um `{{` literal precisa ficar dentro de `{% raw %}…{% endraw %}`. O texto é verificado quando você salva: um erro de sintaxe Liquid, uma tag `{% include %}` ou `{% render %}` ou um texto acima de 64 KB é recusado com o motivo.
- **Os links são enviados como foram escritos.** Os links de um texto personalizado não recebem rastreamento de cliques nem parâmetros UTM. O texto de um email de marketing deve manter `{{ unsubscribe_url }}`, e o de um email de confirmação dupla, `{{ confirm_subscription_url }}`; o editor lembra você disso e avisa ao salvar quando o link está faltando.
- **Ele não acompanha o email.** Um texto personalizado não é atualizado quando você altera o HTML. **Recomeçar a partir da versão automática** o substitui por um novo ponto de partida; escolher **Automática** o remove.
- **Um texto por idioma.** O texto que você escreve no editor principal é o do idioma padrão. Cada tradução tem o seu, escrito no editor dela, na aba **Traduções**; um idioma sem texto próprio recebe a versão automática do próprio HTML, nunca o texto do idioma padrão.

> [!NOTE]
>
> O ponto de partida mantém o Liquid escrito dentro dos blocos de texto. Ele mantém o texto de um [bloco condicional](#conditional-blocks), mas não a condição, e as condições e os loops colocados entre blocos muitas vezes não são levados, conforme o layout. O editor avisa quando o ponto de partida tem menos tags Liquid do que o email: confira o texto e acrescente à mão o que faltar antes de salvar. Um texto personalizado não tem condições de exibição: o texto de um bloco condicional vai para todos os destinatários, a menos que você mesmo o coloque dentro de um `{% if %}`.

Se um texto personalizado não puder ser renderizado no envio, o email sai com a versão automática, e a pré-visualização do template diz o motivo. Pela API, o texto personalizado é o `email.text` do template (e `translations.<language>.email.text`); `templates.compile` o recebe como `text` e informa em `text_source` se o texto retornado é `custom` ou `auto`.

## Blocos condicionais

Um bloco do editor visual pode ser enviado só para alguns destinatários: dê a ele uma **condição de exibição** sobre os dados do email, como "`order.total` é maior que 100" ou "`contact.custom_string_1` é igual a `vip`". Os destinatários para quem a condição não vale recebem o email sem o bloco.

Selecione um bloco e use **+ Condição** na faixa **Condição de exibição**, no topo das configurações dele. Uma condição é uma lista de regras, cada uma formada por uma variável, um operador e, na maioria dos operadores, um valor. Escolha se devem valer **todas as** regras ou **pelo menos uma das** regras; uma condição tem até 20 regras.

É possível definir condições em seções, wrappers, textos, imagens, botões, divisores, espaçadores, blocos sociais e blocos de HTML bruto. Uma condição em uma seção ou em um wrapper oculta tudo o que está dentro dele.

As colunas e os grupos não podem ter condição, porque remover uma coluna quebraria a largura das outras; coloque a condição na seção ou nos blocos dentro da coluna. Um bloco que contém um bloco Liquid também não pode: ocultá-lo removeria também o bloco Liquid, que pode conter metade de uma tag como `{% if %}` cujo `{% endif %}` está em outro lugar. Antes, tire o bloco Liquid de lá. Pelo mesmo motivo, o editor não deixa você colocar um bloco Liquid dentro de um bloco que tem condição.

### Variáveis

Uma variável é um caminho sem chaves, como você escreveria dentro de `{{ }}`: `contact.first_name`, `order.total`, `order.items.size`. `.empty` e `.to_liquid` não podem ser usados em um caminho; para testar uma lista ou um texto vazio, use **é falso ou vazio**.

Todas as variáveis dos dados do email estão disponíveis: os [campos do contato](#contact-variables), o `data` de uma [chamada da API transacional](https://www.notifuse.com/pt/docs/features/transactional-api.md), os [feeds de dados](https://www.notifuse.com/pt/docs/features/broadcast-campaigns.md#data-feeds). As variáveis atribuídas com Liquid dentro do email (um `{% assign %}` em um bloco Liquid ou bruto) não estão, porque uma condição lê os dados com que o email é enviado, e não o conteúdo dele.

### Operadores

| Operador                                                         | Vale quando a variável                                                                                                                                              |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| é verdadeiro                                                     | é `true`, ou o texto `true`                                                                                                                                         |
| é falso ou vazio                                                 | é `false`, está vazia, só tem espaços ou está ausente                                                                                                               |
| está definido / não está definido                                | tem um valor, ou não tem nenhum: ausente, `null`, um texto ou uma lista vazios, um objeto vazio ou um texto só com espaços (`false` e `0` contam como definidos)    |
| é igual a / não é igual a                                        | é exatamente o texto do valor: `vip` não é igual a `VIP`                                                                                                            |
| contém / não contém                                              | para um texto, contém o valor; para uma lista, tem um elemento igual ao valor; para um objeto, tem um campo com esse nome; um número ou um booleano não contém nada |
| é maior que, é maior ou igual a, é menor que, é menor ou igual a | é um número, ou um texto que representa um número (`"150"`), comparado com o valor                                                                                  |

Alguns detalhes:

- **Variáveis ausentes**: uma regra sobre uma variável que falta nos dados é falsa, exceto **é falso ou vazio**, **não está definido**, **não é igual a** e **não contém**, que valem.
- **Números e booleanos**: **é igual a** `100` também corresponde ao número `100`, e **é igual a** `true` corresponde ao booleano `true`. As comparações (**é maior que** e as outras) precisam, como valor, de um número com no máximo 15 dígitos antes do separador decimal; uma variável que não é um número as torna falsas.
- **Valores de texto** são livres: qualquer caractere serve, exceto os delimitadores Liquid `{{`, `}}`, `{%` e `%}`.

### Verificar uma condição

O editor de condição mostra, para cada regra e para a condição inteira, o resultado com os dados de teste do template, e avisa quando falta uma variável nesses dados. A pré-visualização oculta os blocos que os seus dados de teste ocultariam e diz quantos são. Na árvore de camadas e no canvas, um ícone marca os blocos que têm condição.

### Traduções e exportações

Cada [tradução](#translations) tem o próprio conteúdo e, portanto, as próprias condições: defina-as também na tradução. **Redefinir tradução** copia as condições do conteúdo padrão junto com ele.

**Exportar → MJML** escreve cada condição como Liquid em volta do bloco, para que um template de código feito a partir da exportação envie os mesmos blocos. Uma diferença: no template de código, a condição também enxerga as variáveis que o próprio Liquid do email atribui, como um `{% assign %}` em um bloco Liquid ou a variável de um loop `{% for %}` em volta do bloco.

Importar esse arquivo de volta no editor visual devolve as condições aos blocos: a exportação marca cada condição com um comentário Liquid, que não renderiza nada. Um arquivo exportado antes da versão 44.0 não tem essas marcas: cada condição volta dentro de um bloco Liquid, junto com o bloco.

O MJML de um template de código passa inteiro pelo Liquid, e o Liquid aceita no máximo 100 KB (102.400 bytes) de cada vez. Cada condição exportada acrescenta de algumas centenas a alguns milhares de caracteres de Liquid em volta do bloco, conforme as regras. Por isso, um email com muitas condições pode passar do limite depois de exportado, e o template de código dele deixa de compilar. Mantenha esse tipo de email no editor visual, onde as condições não contam para o limite.

Pela API, um bloco de `visual_editor_tree` leva a condição em `display_condition`:

```json
{
  "type": "mj-section",
  "display_condition": {
    "match": "all",
    "rules": [
      { "variable": "order.has_image", "operator": "is_true" },
      { "variable": "order.total", "operator": "gt", "value": "100" }
    ]
  },
  "children": []
}
```

Os operadores são `is_true`, `is_blank`, `is_present`, `is_absent`, `eq`, `neq`, `contains`, `not_contains`, `gt`, `gte`, `lt` e `lte`, e `match` é `all` ou `any`. Uma condição em um bloco que não pode ter condição, ou uma condição inválida, é recusada com um `400`.

## Traduções

Um template pode ter uma versão do conteúdo por idioma. O Notifuse escolhe a versão no momento do envio a partir do campo `language` do contato. Assim, um único broadcast ou uma única notificação transacional atende a todos os idiomas que você escreveu, sem nenhuma ramificação nas suas automações ou chamadas de API.

### Ativar idiomas no workspace

As traduções só são oferecidas para os idiomas ativados no workspace. Abra **Configurações → Geral**, painel **Idioma e fuso horário**:

- **Idiomas suportados**: os idiomas com que este workspace trabalha. Adicione todos os idiomas para os quais você pretende escrever templates; um idioma que não está nesta lista não pode receber tradução.
- **Idioma padrão**: o idioma do conteúdo principal de um template, e a versão que um contato recebe quando nenhuma outra corresponde melhor. Todo workspace tem exatamente um.

Os códigos de idioma são códigos ISO de duas letras, como `en`, `fr`, `de`, `es`. O idioma padrão precisa ser um dos idiomas suportados, e a lista precisa ter pelo menos um.

> [!NOTE]
>
> Com um único idioma suportado, o editor de templates não mostra nenhum controle de tradução. A aba **Traduções** aparece assim que o workspace suporta mais de um idioma.

### Escrever uma tradução

Ao criar ou editar um template, o editor tem duas abas: **Template**, no idioma padrão do workspace, e **Traduções**, que lista cada um dos outros idiomas suportados. Abra um idioma para escrever o assunto, o texto de pré-visualização e o corpo dele, com o mesmo editor visual, o mesmo modo de código MJML e as mesmas variáveis Liquid do idioma padrão.

O remetente e o reply-to são definidos uma vez, no template, e todas as traduções são enviadas com eles. **Redefinir tradução** copia o conteúdo do idioma padrão para a tradução como ponto de partida, substituindo o que havia lá.

Um idioma sem tradução é ignorado no envio, então você não precisa traduzir um template para todos os idiomas suportados de uma vez.

### Qual versão um contato recebe

No momento do envio, o Notifuse lê o `language` do contato:

1. Se estiver vazio ou for igual ao idioma padrão do workspace, o contato recebe o **conteúdo padrão**.
2. Se o template tiver uma tradução para esse idioma, o contato recebe **essa tradução**.
3. Caso contrário, o contato recebe o **conteúdo padrão**.

O conteúdo padrão é sempre a alternativa, então uma tradução que falta nunca deixa um contato sem email. Defina o idioma de um contato na importação, pela API (`language` em `contacts.upsert`) ou em um formulário de inscrição; veja [Contatos](https://www.notifuse.com/pt/docs/features/contacts.md).

Para conferir um idioma específico antes de enviar, a pré-visualização do template e a caixa de diálogo de envio de teste têm um seletor **Idioma**.

> [!NOTE]
>
> **Self-hosted: adicionar um idioma a um template, ou editar o conteúdo de uma tradução existente, exige uma [chave de licença](https://www.notifuse.com/pt/docs/self-hosting/licence.md).** As traduções já salvas continuam sendo enviadas em qualquer estado da licença, a edição do resto de um template que as contém nunca é recusada, e remover uma tradução é sempre permitido. O Notifuse Cloud inclui as traduções de templates a partir do plano Starter ([detalhes](https://www.notifuse.com/pt/docs/self-hosting/licence.md#on-notifuse-cloud)).

## Sintaxe Liquid

O Notifuse usa Liquid para inserir conteúdo dinâmico nos emails. As variáveis ficam entre chaves duplas e são substituídas pelos dados reais no momento do envio.

> [!NOTE]
>
> O Liquid é avaliado no template que você escreve, e não nos seus dados. Um valor vindo de um campo do contato, de um feed de dados ou de uma chamada de API é inserido como texto: se ele contiver `{{ ... }}` ou `{% ... %}`, esse texto aparece como está e não é executado como Liquid. Coloque as merge tags no template e envie valores simples nos dados.

### O HTML dos seus dados é escapado

No HTML de um email, toda saída (`{{ }}`, `echo` e `cycle`) é escapada: um valor aparece como o texto que contém e nunca é lido como HTML. Um contato que digita `<a href="https://example.com">` como primeiro nome vê esses caracteres no email, e não um link. O assunto e a versão em texto não são HTML, então não são escapados.

Quando um valor é HTML de propósito, como um [feed de dados](https://www.notifuse.com/pt/docs/features/broadcast-campaigns.md#data-feeds) que retorna um bloco de HTML, escreva-o com o filtro `raw`:

```liquid
{{ global_feed.article_html | raw }}
```

Use `raw` só para dados que você controla. Em um campo do contato, ou em qualquer coisa que um formulário ou quem chama a API possa preencher, ele permite que esse valor acrescente links e marcação ao seu email.

Algumas saídas não são escapadas uma segunda vez:

- **Já escapadas**: `{{ name | escape }}` é escapado uma vez, também quando `newline_to_br`, `strip` ou `truncate` vêm depois. `{{ bio | escape | newline_to_br }}` mantém as quebras de linha.
- **HTML capturado**: o texto de um `{% capture %}` é escrito como está, porque as saídas dele foram escapadas na captura e o resto é a marcação do seu template.

O escape vale para o texto e os atributos HTML:

- **CSS e scripts**: um valor escrito em CSS (`mj-style`, um elemento `<style>`) ou em um script precisa de `raw` e deve vir de dados em que você confia, como as configurações da sua marca, nunca de contatos.
- **Atributos entre aspas**: uma saída dentro do valor de um atributo só é segura entre aspas. Escreva `class="{{ value }}"`, e não `class={{ value }}`.

### Um erro de Liquid bloqueia o email

Quando o Liquid não consegue avaliar uma parte de um email, o email não é enviado. O envio falha com o erro, e a pré-visualização e o envio de teste o mostram, para que você corrija o template antes que ele chegue a alguém.

Isso vale para o HTML, para o assunto e para a versão em texto. Antes, o email saía com um texto `Liquid error: ...` dentro.

As causas mais comuns são:

- **Um texto comparado com um número**: `{% if contact.custom_string_1 >= 10 %}` falha quando o campo contém `"12"` (`comparison of String with 10 failed`). Compare um campo numérico, ou compare com um texto entre aspas: `{% if contact.custom_string_1 == "12" %}`.
- **Um operador desconhecido**: `{% if x = 1 %}` falha (`Unknown operator =`). Escreva `==`.
- **Um filtro que falha**: `{{ order.total | divided_by: order.count }}` falha quando `order.count` é 0 (`divided by 0`), assim como um filtro sem um argumento, como `{{ contact.first_name | replace }}` (`wrong number of arguments`). Proteja o valor: `{% if order.count > 0 %}{{ order.total | divided_by: order.count }}{% endif %}`.

Pela API, `transactional.send` e `broadcasts.sendToIndividual` respondem a esse envio com um `422` cujo `error` é o erro de Liquid.

Um campo ausente não é erro: `{{ contact.first_name }}` não mostra nada quando está vazio, e `{% if order.total > 50 %}` é falso quando não há `order`. Os blocos condicionais nunca causam erro. Nos temas de blog, o erro continua aparecendo na página.

### Variáveis do contato

O objeto `contact` contém o perfil completo do contato, então qualquer campo do contato pode ser usado na personalização:

```liquid
Hello {{ contact.first_name }}!

Your account email: {{ contact.email }}
Full name: {{ contact.first_name }} {{ contact.last_name }}
```

**Exemplo de saída:**

```
Hello John!

Your account email: john.doe@example.com
Full name: John Doe
```

### Variáveis da lista

Para usar as informações da lista de emails:

```liquid
You're subscribed to: {{ list.name }}
List ID: {{ list.id }}
```

**Exemplo de saída:**

```
You're subscribed to: Newsletter
List ID: newsletter
```

### URLs do sistema

Use as URLs pré-geradas para as ações comuns:

#### Link de cancelamento de assinatura

```liquid
<a href="{{ unsubscribe_url }}">Unsubscribe from this list</a>
```

Abrir esse link cancela na hora a assinatura do contato na lista e mostra a [central de notificações](https://www.notifuse.com/pt/docs/features/notification-center.md). Os clientes de email também podem mostrar o próprio botão de cancelar a assinatura, a partir do cabeçalho `List-Unsubscribe` que o Notifuse adiciona a todo email enviado para uma lista, exceto aos broadcasts que também vão para os contatos da lista que cancelaram a assinatura.

Para conferir esses links e o cabeçalho antes de enviar, escolha uma **Lista de emails** ao enviar um email de teste; um teste enviado de um broadcast já vem com a lista do broadcast escolhida. O teste então leva os links dessa lista e, como o broadcast, o cabeçalho `List-Unsubscribe`, e eles funcionam: cancelar a assinatura ou confirmar a partir do teste, ou uma rejeição ou reclamação registrada nele, altera a assinatura do destinatário de teste na lista.

O campo **Lista de emails** não é oferecido para as notificações transacionais, cujos envios reais não levam links de lista. Sem lista, os links de cancelamento do teste não levam a nenhuma lista real, e o teste não tem cabeçalho `List-Unsubscribe`.

#### Confirmação de inscrição

```liquid
<a href="{{ confirm_subscription_url }}">Confirm your subscription</a>
```

#### Central de notificações

```liquid
<a href="{{ notification_center_url }}">Manage your preferences</a>
```

#### Preferências de rastreamento de email

```liquid
<a href="{{ tracking_preferences_url }}">Choose what we track</a>
<a href="{{ tracking_optout_url }}">Stop tracking my opens and clicks</a>
```

O primeiro abre a caixa de diálogo de rastreamento de email da central de notificações; o segundo pede que o contato confirme nessa caixa e depois recusa o rastreamento de aberturas e de cliques. Veja [Rastreamento de email](https://www.notifuse.com/pt/docs/features/email-tracking.md#template-links).

#### Ver no navegador

```liquid
{% if view_in_browser_url != blank %}
  <a href="{{ view_in_browser_url }}">View this email in your browser</a>
{% endif %}
```

O link abre a versão web do email, para os destinatários cujo cliente de email o exibe mal. No editor visual, selecione um texto, abra o editor de link e escolha o tipo de link **Versão web do e-mail**.

- **Disponível em broadcasts e automações.** Os emails transacionais e de confirmação dupla deixam a variável vazia, a menos que uma chamada da API transacional defina `view_in_browser_url` nos próprios dados. Proteja o link como acima em um template compartilhado com eles.
- **Só onde é usada.** Só os emails cujo template usa a variável têm versão web. Não existe configuração no workspace.
- **O email tal como foi enviado.** A página é renderizada a partir da versão do template e dos dados daquele envio, no idioma do contato. Editar o template depois não a altera.
- **Nada é rastreado na página.** Visualizá-la não registra abertura, e os links dela não registram clique; eles mantêm os parâmetros UTM do envio. Com o rastreamento de cliques ativado, o clique no link dentro do próprio email conta como clique, como em qualquer outro link.
- **Removida com o template ou com o contato.** [Excluir o template](#deleting-a-template) ou [excluir o contato](https://www.notifuse.com/pt/docs/features/contacts.md#deleting-a-contact) faz a página responder "This email is no longer available".

Qualquer pessoa que tenha o link pode abrir a página, como acontece com um email encaminhado. Ela mostra o que o email mostra, incluindo os links de cancelamento de assinatura e da central de notificações do contato, então quem tiver o link pode cancelar a assinatura desse contato. A versão web de cada email abre no máximo 30 vezes por minuto: ela não foi pensada para servir de link público de arquivo.

O link assina o domínio com que foi enviado, a [URL de endpoint personalizada](https://www.notifuse.com/pt/docs/features/workspaces.md#custom-endpoint-url) do seu workspace ou o endereço `API_ENDPOINT`, e a página só abre nesse domínio e no endereço `API_ENDPOINT`. Isso impede que o domínio personalizado de outro workspace mostre o seu email sob o próprio endereço. O que isso não cobre:

- O endereço `API_ENDPOINT` abre a versão web de todos os workspaces, já que todo link pode recorrer a ele.
- Os workspaces que já compartilhavam um domínio personalizado antes da 44.0 mostram as versões web uns dos outros nesse domínio.
- Qualquer pessoa que tenha o link pode baixar a página e publicar uma cópia em outro lugar, como com qualquer email que receba.
- O Notifuse verifica se um domínio personalizado aponta para ele, e não se o domínio pertence ao workspace que o salva. O workspace que salva um domínio primeiro fica com ele; veja [URL de endpoint personalizada](https://www.notifuse.com/pt/docs/features/workspaces.md#custom-endpoint-url).

Depois que o seu workspace troca de domínio personalizado, os links enviados com o antigo continuam funcionando enquanto o domínio antigo ainda apontar para o Notifuse, até que outro workspace o assuma; eles param de funcionar poucos minutos depois disso. Um redirecionamento a partir do domínio antigo só os mantém funcionando se for para o endereço `API_ENDPOINT`, e não para o novo domínio personalizado.

Atrás de um proxy reverso, repasse o cabeçalho `Host` original ou defina `X-Forwarded-Host` com ele: quando esse cabeçalho está presente, a página é julgada só por ele. Um proxy que substitui o `Host` pelo endereço do upstream, como `notifuse:8080`, faz toda versão web responder "This email is no longer available". Um proxy que o substitui pelo host do `API_ENDPOINT` desativa a regra: todo domínio personalizado passa a mostrar as versões web de todos os workspaces.

A página não executa nenhum script e fica separada do console, embora os dois sejam servidos pelo mesmo domínio.

Na pré-visualização de um template e em um email de teste, o link abre uma página dizendo que a versão web passa a existir quando o email é enviado a um contato.

> [!NOTE]
>
> As versões web são servidas em `/v/`. Em um [blog](https://www.notifuse.com/pt/docs/blog/setup.md) servido a partir de um domínio personalizado, uma categoria cujo slug é `v` não pode ser acessada: dê outro slug a ela.

### Variáveis de automação

Um email enviado por uma automação também recebe:

- `{{ automation_id }}` e `{{ automation_name }}`
- `{{ trigger_event }}`: o evento que iniciou a jornada. `{{ trigger_event.kind }}` é o tipo dele (`custom_event.cart_abandoned`, `list.subscribed`, `email.link_clicked`…) e `{{ trigger_event.occurred_at }}`, o momento em que aconteceu. Para um evento personalizado, também `{{ trigger_event.name }}`, `{{ trigger_event.external_id }}` e as propriedades dele, `{{ trigger_event.properties.<key> }}`.

```liquid
{% if trigger_event.properties.items %}
  {% for item in trigger_event.properties.items %}
    {{ item.name }} × {{ item.quantity }}: {{ item.price }}
  {% endfor %}
{% endif %}
```

Uma jornada iniciada antes da versão 44 não tem `trigger_event`: proteja a variável com `{% if %}`.

### Exemplo completo

```liquid
Welcome {{ contact.first_name }}!

Thank you for subscribing to {{ list.name }}. We're excited to have you on board!

Your registered email: {{ contact.email }}

Manage Preferences: {{ notification_center_url }}

Don't want to receive these emails?
Unsubscribe here: {{ unsubscribe_url }}
```

### Estrutura de dados disponível

Os templates podem usar esta estrutura de dados:

```json
{
  "contact": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "list": {
    "id": "newsletter",
    "name": "Newsletter"
  },
  "unsubscribe_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=unsubscribe&email=john.doe@example.com&lid=newsletter&lname=Newsletter&wid=workspace123&mid=msg_123&email_hmac=abc123",
  "confirm_subscription_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=confirm&email=john.doe@example.com&lid=newsletter&lname=Newsletter&wid=workspace123&mid=msg_123&email_hmac=abc123",
  "notification_center_url": "https://your_notifuse_endpoint.your_website.com/notification-center?email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "tracking_preferences_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=tracking&email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "tracking_optout_url": "https://your_notifuse_endpoint.your_website.com/notification-center?action=tracking_optout&email=john.doe@example.com&email_hmac=abc123&wid=workspace123",
  "view_in_browser_url": "https://your_notifuse_endpoint.your_website.com/v/ODkyY2Q..."
}
```

### Diferenças em relação ao Shopify Liquid

O Notifuse renderiza Liquid com o [liquidgo](https://github.com/Notifuse/liquidgo), que segue o [Shopify Liquid](https://shopify.github.io/liquid/) 5.11. Alguns comportamentos são diferentes de propósito, porque os seus dados vêm de JSON e os seus emails são lidos por pessoas:

- **Texto vazio é falso**: `{% if contact.first_name %}` pula um contato cujo primeiro nome está vazio. No Shopify Liquid, só `nil` e `false` são falsos.
- **Os números dos seus dados são decimais**: com `order.total` igual a `1999`, `{{ order.total | plus: 1 }}` mostra `2000` (e não `2000.0`), e `{{ order.total | divided_by: 100 }}` mantém as casas decimais e mostra `19.99`. Acrescente `| floor` para ficar só com a parte inteira.
- **Em um tema de blog, um erro de filtro não mostra nada**: `{{ 1 | divided_by: 0 }}`, um `base64_decode` inválido ou um filtro com argumentos demais não mostram nada, em vez de `Liquid error: ...`. Em um email, o erro bloqueia o email (veja [Um erro de Liquid bloqueia o email](#a-liquid-error-stops-the-email)).
- **As listas aparecem com colchetes**: `{{ contact.custom_json_1.tags }}` mostra `["vip", "early"]`. Use `{{ contact.custom_json_1.tags | join: ", " }}` para listar os itens.
- **`date`** lê uma data escrita sem fuso horário como UTC, e um número como um timestamp Unix.

Nos temas de blog, que são os únicos templates com partials, `{% render %}` recebe um nome de template entre aspas, como no Shopify Liquid 5.11 (`{% render 'footer' %}`); os emails o recusam. `{% snippet %}` não é suportado.
