Tipos de variáveis

 

O Mailjet oferece quatro tipos de variáveis, cada uma atendendo a uma finalidade diferente na linguagem de modelo. Esses tipos de variáveis incluem:

1. Data (estática): essas variáveis são usadas para dados estáticos que não mudam com frequência. Normalmente são valores predefinidos.
2. Var (dinâmica): variáveis var são usadas para dados dinâmicos que podem mudar com base em diferentes condições ou inserções.
3. Variáveis predefinidas do MJ: essas variáveis são predefinidas pelo Mailjet e fornecem informações e funcionalidades úteis na linguagem de modelo.
4. Estruturas de variáveis de segmentação: essas variáveis são usadas para fins de segmentação complexa e não são o foco principal deste artigo.

Enfocaremos principalmente os dois primeiros tipos de variáveis (data e var), mas também abordaremos brevemente as variáveis predefinidas.

Os tipos de variáveis mais usados são data e var. Embora ambos sirvam ao propósito de substituir uma string de espaço reservado por um valor que muda dinamicamente, eles diferem na forma de uso, em como o valor é fornecido ao sistema e nos tipos de mensagens em que podem ser usados.

Além das variáveis autônomas, a linguagem de modelo fornece ferramentas (funções) que permitem aos usuários incorporar variáveis em operações lógicas e aritméticas mais complexas, bem como influenciar a formatação e a codificação. Neste guia, exploraremos especificamente o uso de funções como “set” e “FormatNumberLocale”. Além disso, vamos nos aprofundar em instruções condicionais “if” e loops “for” em detalhes.

 

Data

O tipo de variável data é versátil e pode ser utilizado tanto em mensagens de marketing quanto em mensagens transacionais. É flexível por não exigir nenhuma ação do usuário para fornecer um valor ao espaço reservado da variável. Em vez disso, o sistema substitui automaticamente o valor com base nos objetos da propriedade de contato.

Seja campanha ou e-mail transacional, contanto que a mensagem seja direcionada a um contato existente, e o nome da variável corresponda a uma propriedade de contato, o sistema conseguirá processar a variável data. Se o destinatário tiver um valor atribuído a essa propriedade, ele será exibido no lugar do espaço reservado da variável.

 

Vamos ilustrar com um exemplo. Suponha que eu defina a variável [[data:país]] no conteúdo da minha mensagem e a envie para um de meus contatos. Nesta situação, são possíveis dois resultados:

1. Se o contato tiver um valor definido para a propriedade de contato “country" (país), ele receberá a mensagem com a variável [[data:country]] substituída pelo valor correspondente.
2. Se o contato não tiver um valor definido para a propriedade de contato "country" (país), ele receberá a mensagem sem nenhuma substituição para a variável [[data:country]]. No entanto, a própria variável não será exibida como elemento de linguagem de modelo na versão final da mensagem.

Para fornecer um exemplo concreto, vamos considerar dois contatos: usuario1@dominio.tld, que tem um valor de propriedade “country" (país) igual a “França”, e usuario2@dominio.tld, que não tem valor definido para a propriedade “country" (país).

Se eu enviar aos dois a mesma mensagem contendo a frase:

“Oi, como estão as coisas aí no(a) [[data:country]] agora depois da pandemia?”

 

Cada contato verá um conteúdo diferente:

• usuario1@dominio.tld verá: “Oi, como estão as coisas aí no(a) França agora depois da pandemia?”
• usuario2@dominio.tld verá: “Oi, como estão as coisas aí no(a) agora depois da pandemia?”

No segundo exemplo, o sistema simplesmente não mostra nada porque o usuário não tem um valor definido para a propriedade associada da variável data em uso.

 

Var

É importante observar que o tipo de variável var não deve ser usado em modelos de marketing ou rascunhos de campanha. Embora possa ser adicionada a esses objetos, tentar enviar a mensagem resultará em um evento BLOCKED devido a um erro na linguagem de modelo. Normalmente, a mensagem de erro indicará que não foi fornecido nenhum valor para a variável var, o que é esperado, pois não há como adicionar valor a ela.

 

No entanto, existem maneiras de fazer variáveis var funcionarem num modelo de marketing ou numa campanha. As duas abordagens mais diretas são:

• Adicionar a variável var com um valor-padrão.
• Definir a variável usando uma função set.

Embora essas abordagens tecnicamente funcionem, elas podem ser ineficazes e menos úteis. Isso ocorre porque elas exigem que você defina o valor da variável no próprio modelo antes do envio, sem permitir nenhuma variação no valor exibido com base no destinatário. Isso vai contra a finalidade de ter uma variável e anula a flexibilidade dela.

 

A utilização adequada das variáveis var é incluí-las nos modelos transacionais ou diretamente no conteúdo das mensagens transacionais. Os valores usados para substituir essas variáveis são fornecidos pelo usuário por meio da chamada de Send API (como parte do corpo da solicitação) ou durante a sessão de retransmissor de SMTP (como cabeçalho personalizado), dependendo do canal transacional usado.

Para declarar as variáveis e fornecer seus respectivos valores, são usados pares chave-valor JSON. Por exemplo, “name”: “João” ou “testVariable123”: “testValue”, etc.

No contexto da Send API v3, o objeto que contém as variáveis é denominado “Vars”. Na Send API v3.1, o princípio permanece o mesmo, mas o objeto é denominado “Variables”. Para mensagens geradas por retransmissor de SMTP, o cabeçalho personalizado que deve conter as variáveis codificadas em JSON é “X-MJ-Vars”.

 

Observe que, para a linguagem de modelo ser processada corretamente e não como texto simples, o sistema do Mailjet depende de propriedades específicas que indicam se os elementos da linguagem de modelo devem ser tratados como tais. Essas propriedades são do tipo booleano, e você encontrará a seguir o nome da propriedade apropriada para cada canal transacional:

• Send API v3: “Mj-TemplateLanguage”
• Send API v3.1: “TemplateLanguage”
• Retransmissor de SMTP: “X-MJ-TemplateLanguage”

É importante ter em mente que o valor-padrão para cada uma dessas propriedades é “false” ou “0”. Se você descuidar desse detalhe, mesmo que as configurações estejam corretas, as configurações da linguagem de modelo podem não funcionar conforme esperado. Isso ocorre porque, sem habilitar as propriedades acima, o sistema interpreta os elementos de linguagem de modelo na mensagem enviada como strings de texto comuns sem qualquer significado adicional.

Por fim, em uma situação específica em que os usuários criam objetos de rascunho de campanha por meio da API e pretendem usar linguagem de modelo no conteúdo do rascunho da campanha, o objeto “/campaigndraft/$ID/detailcontent” associado ao rascunho precisa incluir a seguinte propriedade no objeto “Headers”:

Ao incluir esta propriedade, o sistema reconhece o uso de linguagem de modelo no conteúdo do rascunho da campanha.

 

Valores-padrão

As variáveis var e data dão suporte ao uso de valores-padrão. Um valor-padrão atua como fallback, ou valor de segurança, que os usuários fornecem ao nosso sistema ao configurar a variável no modelo ou no corpo da mensagem. Atendidas determinadas condições, o valor-padrão será exibido pelo nosso sistema:

• Variáveis data: se o contato que recebe a mensagem não tiver um valor de propriedade de contato definido para essa variável/propriedade de contato específica.
• Variáveis var: se nenhum valor for enviado por meio da chamada de API ou da sessão SMTP.

Nessas situações, o valor-padrão serve como substituto para garantir que sempre haja um valor exibido para a variável, mesmo quando os dados necessários não estiverem disponíveis ou não forem fornecidos.

 

Sintaxe

Pensando nas considerações acima, vamos nos aprofundar na sintaxe adequada para variáveis autônomas (variáveis que não estão sendo usadas em uma função).

 

• Variáveis var

  • Para adicionar uma variável var, use a seguinte sintaxe: {{var:variableName}}
  • Para fornecer um valor-padrão junto com a variável: {{var:variableName:defaultValue}}
    • Sintaxe alternativa: {{var:variableName:"defaultValue"}} (ambas as opções funcionam igualmente bem)
  • Para mostrar um espaço como valor-padrão, coloque-o entre aspas: {{var:variableName:" "}}
  • Para não exibir nada como valor-padrão, use aspas vazias: {{var:variableName:""}}

• Variáveis data

  • Para adicionar uma variável data, use a seguinte sintaxe: [[data:nomeDaPropriedadeDeContato]]
  • Para fornecer um valor-padrão junto com a variável:[[data:nomeDaPropriedadeDeContato:valorPadrão]]
    • Sintaxe alternativa: [[data:nomeDaPropriedadeDeContato:"valorPadrão"]]

Observação: embora chaves duplas em vez de colchetes duplos também funcionem para variáveis data, é recomendável usar colchetes, a menos que seja necessário para funções específicas que exigem chaves duplas.

 

É importante observar que o comportamento do sistema é diferente quando falta algum valor para uma variável data e quando falta um valor para uma variável var. Se uma variável data não tiver valor-padrão, e o contato não tiver valor definido para a respectiva propriedade, será mostrado um espaço em branco na mensagem. No entanto, não ter valor-padrão para uma variável var e não declará-lo na chamada de API ou na sessão SMTP resultará no bloqueio da mensagem.

 

Os valores-padrão não são obrigatórios, mas podem ser úteis para impedir o bloqueio de mensagens. Por padrão, quando o sistema encontra uma variável var sem um valor fornecido, ele bloqueia a mensagem. Para influenciar esse comportamento, você pode incluir uma propriedade booleana especial em sua chamada de API ou cabeçalho SMTP:

• Send API v3: “Mj-TemplateErrorDeliver”
• Send API v3.1: “TemplateErrorDeliver”
• SMTP: “X-MJ-TemplateErrorDeliver”

O valor-padrão para esta propriedade é “false”, portanto, ativá-la manualmente permite que as mensagens sejam enviadas mesmo se houver erros na linguagem de modelo. Ativar esta propriedade evita que as mensagens sejam bloqueadas.

 

Por fim, os usuários podem escolher se desejam ser notificados por e-mail quando suas mensagens forem bloqueadas devido a erros na linguagem de modelo. Isso pode ser feito por meio de outra propriedade especial:

• Send API v3: “Mj-TemplateErrorReporting” (exemplo: “Mj-TemplateErrorReporting”: “reports@domain.tld”)
• Send API v3.1: “TemplateErrorReporting” (exemplo: {"Email": "reports@domain.tld", "Name": "Recipient Name"})
• SMTP: “X-MJ-TemplateErrorReporting” (exemplo de cabeçalho personalizado: X-MJ-TemplateErrorReporting: “reports@domain.tld”)

 

Variáveis predefinidas

Em nosso sistema, alguns nomes de variáveis são reservados para variáveis estáticas predefinidas. Essas variáveis permitem que os usuários especifiquem uma variável que corresponda a um valor específico baseado no sistema. Algumas variáveis predefinidas comuns incluem:

• ID do contato do destinatário
• Endereço de e-mail do contato do destinatário
• ID do modelo
• Links compartilháveis de redes sociais para a versão on-line do e-mail (Twitter, Facebook, LinkedIn, etc.): aplica-se a newsletters, assim como as versões on-line padrão/PERMALINKS.

Veja aqui uma lista dessas variáveis estáticas predefinidas.

 

A sintaxe para usar qualquer uma dessas variáveis predefinidas é a seguinte: {{predefinedVarHere}}.

Exemplo: {{mj:template.ID}} exibirá a ID do modelo na versão final da mensagem se for usado um modelo para enviar o e-mail.

 

Observe que existem outras variáveis reservadas, como o link Cancelar a assinatura ou a versão on-line, que são introduzidas usando colchetes duplos (p.ex., [[PERMALINK]]). Essas variáveis costumam ser adicionadas automaticamente pelo sistema, mas os usuários também podem introduzi-las manualmente pelo Editor de Arrastar e Soltar, HTML bruto, modelos MJML brutos ou objetos de conteúdo detalhado de rascunho de campanha. É importante lembrar que essas variáveis predefinidas especiais não devem ser introduzidas entre chaves. Introduzi-las com chaves fará com que o sistema as trate como variáveis que precisam ser definidas em uma chamada de API ou durante uma sessão SMTP (como variáveis var) em vez de variáveis que o sistema pode buscar por conta própria.

Portanto, qualquer variável estática predefinida especificada na documentação de referência mencionada acima (que comece com “mj:”) deve ser introduzida usando “{{}}”, enquanto qualquer variável predefinida não listada nessa documentação (que não comece com “mj:”) deve ser introduzida usando “[[]]”.

 

Objetos multidimensionais e matrizes multidimensionais

Nossa linguagem de modelo permite o uso de objetos multidimensionais e matrizes multidimensionais, que são úteis em várias situações, por exemplo, para introduzir valores que seriam usados em um loop “for”.

 

Um objeto ou matriz multidimensional é aquele que envolve variáveis que estão aninhadas uma na outra. Só podem ser usados em modelos/mensagens transacionais, pois exigem que os valores sejam fornecidos pelo usuário, e isso precisa ser feito por meio de uma estrutura JSON específica.

Aqui está um exemplo de uma variável multidimensional que precisaria ser apresentada como objeto multidimensional nos dados JSON em que serão declaradas as variáveis para essa mensagem:

 

{{var:clothes.winter.coat}}

 

Cada ponto (“.”) representa uma “camada” de aninhamento: o valor mais à esquerda indica o nível mais externo; conforme vamos para a direita, mais descemos na estrutura aninhada. Aqui está a estrutura JSON correta que precisa ser usada para que nosso sistema localize corretamente o valor da variável “clothes.winter.coat” (o exemplo inclui a propriedade v3.1 “Variables”, mas isso varia dependendo do canal transacional usado, conforme discutido em uma seção anterior):

A configuração acima resultaria na exibição da palavra “blazer” na posição em que “{{var:clothes.winter.coat}}” foi colocado no modelo/conteúdo do e-mail.

 

Quanto às matrizes multidimensionais, elas são mais comuns, principalmente em loops “for” (mais sobre eles em outra seção). A lógica por trás de como estruturar os dados JSON seria semelhante à usada no exemplo mostrado acima, com alguns acréscimos (matrizes JSON).

Aqui está um exemplo simples: {{customer.Name}}

Se imaginarmos que será uma variável usada em um loop “for” (o que significa que queremos atribuir valores diferentes à mesma variável, neste caso “Name”), podemos usar uma matriz com objetos aninhados. Veja como ficaria o JSON:

Como você pode ver, temos uma variável aninhada chamada “Name” sob a camada chamada “customer”, então nossa estrutura JSON precisa refletir isso. Primeiro definimos “customer” e especificamos que é uma matriz abrindo os colchetes. Dentro dos colchetes, podemos usar vários pares de chaves para definir diferentes valores para a variável “Name”. Se não estivéssemos usando uma matriz multidimensional (que, na vida real, também seria combinada com um loop “for”), não poderíamos usar a variável “Name” várias vezes com valores diferentes. Teríamos que usar algo do tipo “Name1”, “Name2”, “Name3”, etc. Assim, utilizar uma matriz multidimensional nos poupa trabalho, torna nosso JSON mais fácil de gerenciar e nos permite reutilizar a mesma variável Name com valores diferentes.

Vamos dar uma olhada em outra matriz multidimensional simples na seção sobre loops “for” e também em uma mais complexa (com mais camadas de aninhamento).

 

Instruções condicionais “if”

As instruções condicionais “if” são usadas para introduzir requisitos que determinam se deve ser exibida uma informação específica. Elas também podem incluir valores alternativos a serem exibidos se o requisito inicial não for atendido, usando instruções “else”. Além disso, pode ser introduzido um requisito alternativo usando a instrução condicional “elseif”. Uma instrução “if” deve ser fechada com um operador “endif”.

 

Normalmente, as instruções condicionais “if” são introduzidas usando blocos de linguagem de modelo em um modelo de Arrastar e Soltar. No entanto, elas também podem ser adicionados em elementos Texto. Essas instruções podem ser usadas em modelos de marketing e transacionais, embora os modelos transacionais forneçam mais flexibilidade. Em um modelo transacional, condicionais “if” podem ser montadas com base nos valores das variáveis var, que são enviadas por meio da Send API ou SMTP, bem como variáveis data, que operam com valores de propriedade de contato. Em um modelo de marketing, só podem ser usadas variáveis data, pois não há como enviar valores para variáveis var.

Aqui está um exemplo de uma instrução condicional “if” simples usada em um modelo de marketing:

Aqui está um exemplo da linguagem de modelo em uso:

{% if data:firstname %}
PRINT THIS IN THE MARKETING MESSAGE
{% endif %}

 

Neste exemplo, a linguagem de modelo começa com um comando de abertura que contém a própria condição. Se a condição for atendida (ou seja, o destinatário tem um valor definido na propriedade “firstname”), o sistema exibirá o conteúdo dentro do bloco (“PRINT THIS IN THE MARKETING MESSAGE”). O comando de fechamento indica o fim da seção condicional “if”.

A instrução condicional “if” depende de uma propriedade de contato (“firstname”). O sistema verificará se o destinatário possui um valor definido na propriedade “firstname”. Se a resposta for sim, o sistema incluirá o conteúdo do bloco na versão final do e-mail. Se a resposta for não, a string específica não será exibida.

Aqui está um exemplo da versão final do e-mail para um destinatário que tenha uma propriedade “firstname” definida:

 

Aqui está um exemplo da versão final do e-mail para um destinatário que não tenha uma propriedade “firstname” definida:

A condição “if” acima verifica se a propriedade está definida para o destinatário. No entanto, você pode introduzir um valor específico que a propriedade deva ter para mostrar o conteúdo condicional. Por exemplo:

Neste exemplo, o conteúdo condicional “PRINT THIS IN THE MARKETING MESSAGE” só estará presente na versão do destinatário da mensagem se a propriedade de contato “firstname” estiver definida com o valor “Gina”. Essa condição garante que o conteúdo seja exibido exclusivamente para destinatários cuja propriedade “firstname” corresponda ao valor especificado de “Gina”.

 

Vamos examinar mais de perto alguns exemplos envolvendo modelos transacionais. Estes exemplos demonstram o uso de variáveis var e elementos de linguagem de modelo e podem ser aplicados em blocos de texto ou blocos de linguagem de modelo.

 

Exemplo 1: usar variável var em um modelo transacional

Neste exemplo, vamos verificar se a var “variable” está definida. A condição é verdadeira ou falsa, atuando como uma propriedade booleana.

 

Aqui está o que esperar em diferentes situações:

• Se a var “variable” não for definida na chamada da Send API (SAPI) ou na sessão SMTP, isso resultará em um erro na linguagem de modelo. Adicionar um valor-padrão na condicional “if” (var:variable:defaultValueHere) sempre mostrará “PRINT THIS STRING IN THE TRANSACTIONAL EMAIL” para destinatários aos quais a variável não está definida.
• Se a variável for definida como true na chamada de SAPI ou na sessão SMTP, a condição será atendida.
• Se a variável for definida como "anyValueYouCanThinkOfOtherThanFalse" na chamada de SAPI ou na sessão SMTP, a condição será atendida.
• Se a variável for definida como false na chamada de SAPI ou na sessão SMTP, a condição NÃO será atendida. Observe a diferença entre “variable”: “false” (situação anterior) e “variable”: false (situação atual).

Exemplo 2: demonstração de outros operadores lógicos e de comparação (else, elseif e ifelse + AND)

Este exemplo demonstra o uso de diferentes operadores de comparação e operadores lógicos. Inclui as instruções “if”, “else” e “elseif” combinadas com o operador lógico “AND”.

Finalmente, aqui está uma captura de tela para fornecer referência visual: 

Esses exemplos ilustram como as variáveis var e diversos operadores podem ser utilizados de forma eficaz nos modelos transacionais para personalizar o conteúdo com base em condições específicas.

 

Agora, vamos examinar pares de dados JSON junto com os resultados correspondentes que eles produzem para o destinatário final:

JSON 1:

JSON 2:

JSON 3:

JSON 4:

Essencialmente, para que o valor “I'll consider going out” (Vou pensar em sair) seja exibido, exigimos que as seguintes condições sejam atendidas simultaneamente: “weather” (tempo) não pode estar “bad” (ruim), o valor de “bankAccountBalance” (saldo da conta bancária) deve ser diferente de 0, e a variável “haveFreeTime” (tem tempo livre) deve ser “true” (verdadeira) ou definida. Caso alguma dessas três condições não seja atendida, será exibido o valor “I won't be going out” (Não vou sair) ou “I'll stay at home” (Vou ficar em casa), dependendo de qual condição não for atendida.

 

Observe o uso do operador lógico AND, que exige o uso de parênteses () para garantir o agrupamento adequado das condições.

 

Loops “for”

Loops “for” permitem percorrer várias iterações de uma variável ou percorrer uma lista de variáveis, fornecendo flexibilidade e conteúdo dinâmico. É importante observar que loops “for” devem ser usados apenas em modelos transacionais, e não em modelos de marketing, pois os valores ou iterações não podem ser introduzidos em uma mensagem de marketing.

 

Vamos dar uma olhada em uma representação simples de um loop “for”:

Neste exemplo, definimos um loop “for” com o nome da variável “Test” e especificamos o namespace onde o sistema deve procurá-lo (var:Test). Supomos uma variável simples com uma só iteração. A chamada de API ou os cabeçalhos SMTP devem incluir a seguinte estrutura JSON:

Observe que a seção anterior, “matrizes multidimensionais”, contém uma maneira alternativa de apresentar o mesmo tipo de estrutura, que também pode ser usada com loops “for”.

 

O loop “for” será substituído pelos valores fornecidos na estrutura JSON. Aqui está um exemplo de como seria a mensagem resultante.

Agora, vamos imaginar uma situação em que você faz parte da equipe de relações públicas de uma empresa e precisa enviar um e-mail para o departamento financeiro. Você deseja comunicar os nomes, país de residência e números de telefone de contato de três clientes que ganharam um jogo realizado por sua empresa e precisa que as informações de contato deles sejam revisadas pela equipe financeira.

Para isso, você pode utilizar um loop “for” em sua mensagem para percorrer diferentes iterações do mesmo nome de variável (p. ex., Name, Phone, etc.) e exibir diferentes valores a cada vez.

Aqui está um exemplo de como você pode definir essa configuração de linguagem de modelo:

Nesse caso, usamos o nome da variável “customer” para percorrer os detalhes do cliente fornecidos na chamada da API ou nos cabeçalhos SMTP. A estrutura JSON deve seguir este formato:

Ao usar essa abordagem, você simplifica a estrutura JSON e reduz o risco de erros. O e-mail resultante exibirá os detalhes do cliente com base nas iterações fornecidas.

Por fim, vamos explorar um exemplo mais complexo que envolve uma estrutura de matriz multidimensional. Neste caso, vamos supor uma situação relacionada a itens de roupas de inverno.

Aqui está a configuração para o loop “for” no modelo:

Neste exemplo, usamos a variável “value”, localizada no namespace “items” na estrutura JSON. Especificamos dois tipos de itens (casacos e chapéus) com suas respectivas variáveis aninhadas em várias camadas de variáveis.

Veja como ficaria a estrutura JSON para este exemplo:

A mensagem resultante exibiria os valores de casaco e chapéu de inverno com base nas iterações fornecidas.

Ao utilizar loops “for”, você pode iterar dinamicamente por meio de variáveis e gerar conteúdo personalizado em modelos transacionais. É importante ter uma estrutura JSON adequada e seguir a sintaxe da linguagem de modelo para obter os resultados desejados.

 

Tabela de resumo das instruções condicionais “if” e loops “for”:

 

Blocos de texto, blocos HTML, blocos de linguagem de modelo

Ao trabalhar com modelos de e-mail, existem diferentes abordagens para incorporar estruturas de linguagem de modelo. Elas podem ser introduzidas por meio de blocos de texto, blocos de HTML ou blocos de linguagem de modelo em modelos transacionais Arrastar e Soltar. Além disso, elas podem ser integradas diretamente no conteúdo do e-mail.

Geralmente, é aconselhável separar o conteúdo de HTML bruto das estruturas de linguagem de modelo sempre que possível. Quando há necessidade de combiná-los, como ao criar uma tabela com iterações variáveis usando um loop “for”, geralmente é mais seguro utilizar um bloco HTML de arrastar e soltar e incorporar a linguagem de modelo dentro dele, em vez de adicionar HTML bruto a um bloco de linguagem de modelo.

Os blocos de linguagem de modelo são especialmente úteis ao trabalhar com instruções condicionais “if”. Cada operador dentro da condicional “if” pode ser colocado em um bloco de linguagem de modelo separado, com vários outros elementos de Arrastar e Soltar servindo como o conteúdo que será exibido com base em uma condição específica. Por exemplo, você pode exibir um elemento de imagem, vídeo ou botão se forem atendidos determinados critérios. É possível abrir um loop “for” condicional “if” em um bloco e fechá-lo em outro, proporcionando flexibilidade e organização.

Para manter a clareza e a separação, é recomendável colocar estruturas de linguagem de modelo em blocos de linguagem de modelo separados, em vez de misturá-los com outro conteúdo. Embora seja possível adicionar texto simples a um bloco de linguagem de modelo, é melhor usar blocos separados para conteúdo mais complexo. Ao combinar HTML bruto com estruturas de linguagem de modelo, é aconselhável utilizar um bloco de HTML bruto em que o código é armazenado junto com a linguagem de modelo, em vez de incluir o HTML bruto em um bloco de linguagem de modelo.

 

Funções

Conforme discutido anteriormente, as funções são uma parte essencial da linguagem de modelo do Mailjet, oferecendo uma variedade de operações que podem ser executadas pelo sistema. Essas funções permitem efeitos de formatação em diferentes áreas, como:

• Operações matemáticas: arredondamento de valores numéricos.
• Manipulação de strings: conversão de strings em maiúsculas ou minúsculas, ou converter a primeira letra para maiúscula.
• Formatação de números: formatação de números com base em regras específicas.
• Codificação de URL: converter uma string em um formato seguro para URL.
• Colocar caracteres de escape na string: garantir que os caracteres especiais em uma string sejam codificados corretamente.

Ao combinar essas funções com variáveis, instruções condicionais “if” e operadores mencionados na referência da linguagem de modelo do Mailjet, você pode criar conteúdo altamente personalizável e dinâmico.

Nesta seção, vamos explorar duas funções específicas: a função set e a função FormatNumberLocale.

 

Função set

A função set é um recurso poderoso que permite atribuir um valor diretamente a uma variável dentro do modelo ou conteúdo do e-mail, eliminando a necessidade de declarar a variável na chamada de SAPI ou na sessão SMTP.

Vejamos um exemplo:

No exemplo acima, usamos a função Set para atribuir um valor à variável “testVar” dentro do próprio modelo. Na linha a seguir, estamos usando a mesma variável dentro de uma frase.

 

Usando a função Set, posso enviar uma mensagem com um objeto “Variables” vazio, da seguinte forma:

Essa abordagem nos permite enviar mensagens sem definir explicitamente a variável na chamada de API, e a mensagem não será bloqueada. Aqui está o resultado quando a mensagem é enviada:

Um dos aspectos interessantes da função Set é que você pode usá-la várias vezes dentro do mesmo conteúdo para atualizar o valor da mesma variável. Vejamos um exemplo que corrige uma instrução:

No exemplo acima, atualizamos o valor da variável “testVar” dentro do modelo. A segunda atribuição substitui o valor inicial, retornando o seguinte:

É importante observar que, se você passar um valor para a mesma variável por meio da chamada de API ou sessão SMTP, ele não substituirá o valor definido usando a função set no modelo.

 

Função FormatNumberLocale

A função FormatNumberLocale permite formatar números de ponto flutuante (números com frações decimais) de acordo com regras específicas. Ela depende de três propriedades:

• Format: especifica o formato desejado do número.
• Number: fornece o número a ser formatado.
• Locale: seleciona a localidade para determinar a vírgula decimal e o separador de milhar.

Por exemplo, considere o seguinte código de modelo:

Neste exemplo, usamos a configuração regional francesa (“fr_FR”) para formatar o número 3500 usando o formato “#,###.00”. O resultado será:

Você pode ver que o número agora inclui separadores de milhar e pontos decimais de acordo com o formato francês.

A função FormatNumberLocale também oferece suporte a outras variações de formato, como:

Esses exemplos demonstram como pequenas variações no formato podem afetar o resultado. A localidade “en_GB” é usada para formatação. Será retornado o seguinte:

Ao usar variáveis dinâmicas com a função FormatNumberLocale, lembre-se de seguir a sintaxe correta:

Forneça a variável “var:VarName” sem aspas ou colchetes. Além disso, forneça o valor da variável como um número inteiro na chamada de API ou na sessão SMTP:

O uso de aspas ao redor do valor causará erros na linguagem de modelo.

Essas funções, juntamente com os amplos recursos da linguagem de modelo do Mailjet, permitem que você crie conteúdo altamente personalizado e dinâmico em seus e-mails. 

Observações adicionais

Vale mencionar que é possível adicionar as variáveis fora das caixas de texto, HTML ou blocos de linguagem de modelo. Você pode introduzir variáveis em vários outros elementos, como hiperlinks, botões e URLs de imagem em elementos de imagem de arrastar e soltar.

Ao usar uma variável dentro de um hiperlink ou URL de um botão, você pode utilizar um valor-padrão. No entanto, é importante observar que você não pode usar uma variável-padrão dentro da URL associada a um elemento de imagem de arrastar e soltar. O sistema permitirá que você salve a variável no campo URL com um valor-padrão, mas a removerá imediatamente.

Lembre-se de que é possível (e funciona bem) adicionar uma variável-padrão no link de um elemento de botão ou hiperlink. No entanto, você pode encontrar uma notificação de erro no Editor, que você pode ignorar. Adicione o valor-padrão sem aspas e sem protocolo HTTP/HTTPS no início. Por exemplo: {{var:Link:www.mailjet.com}}

Outro item importante a considerar é a declaração de variáveis na chamada de SAPI/sessão SMTP. Ela deve corresponder exatamente a como foi adicionada no conteúdo da mensagem. A distinção entre maiúsculas e minúsculas desempenha um papel crucial, portanto, preste atenção a quaisquer discrepâncias nas maiúsculas e minúsculas. Além disso, ao usar um ponto (.) em variáveis, você indica objetos ou matrizes multidimensionais. Se for necessário um separador em vez de indicar uma estrutura multidimensional, o underline (_) é melhor que ponto.

Atualizações do Templater: sintaxe mais rigorosa e mudanças de comportamento (outubro de 2025)

Implementamos atualizações que melhoram a confiabilidade e o desempenho, e tornam a validação de sintaxe mais rígida. Se seus templates dependiam de uma interpretação mais permissiva, revise as mudanças abaixo.

👉 Tratamento mais rigoroso de tags

Blocos {% if %} / {% for %} agora devem ser fechados corretamente. A ausência de {% endif %} ou {% endfor %} gera um erro (antes, blocos incompletos podiam ser tolerados).

{% if var:is_promo %}
  <p>Promo!</p>
{% endif %}

👉 Namespaces de variáveis: var e data

• Se a variável é declarada/conhecida (existe no seu esquema) mas não é fornecida no payload, o rendering agora é mais permissivo (resolve como vazio/falso conforme aplicável).
• Se uma variável não está definida de forma alguma, um erro será retornado.

{% if var:user.first_name %}Hello {{ var:user.first_name }}!{% endif %}

👉 Identificadores vs. operações

Espaços ao redor de operadores são importantes. O parser distingue identificadores de expressões:

• var:x-1 → interpretado como um identificador único chamado x-1
• var:x - 1 → interpretado como uma operação de subtração (x menos 1)

{{ var:price - 1 }}   {# subtraction #}
{{ var:price-1 }}     {# key literally named "price-1" #}

👉 Reescrita de links para rastreamento de cliques

Tags <a> sem um atributo href entre aspas anteriormente eram ignoradas pelo reescritor de links. Agora elas são reescritas e rastreadas.

<a href={{ var:url }}>Open</a>

<a href="{{ var:url }}">Open</a>

👉 Substituição do link de descadastramento

[[ UNSUB_LINK ]] agora é substituído corretamente em todas as partes do corpo da mensagem (incluindo parciais/blocos onde anteriormente podia ser ignorado).

<p>To unsubscribe, click [[ UNSUB_LINK ]]</p>

👉 Melhorias de desempenho

A latência média de processamento de templates foi reduzida, resultando em personalização mais rápida dos e-mails no momento do envio.

👉 Rigor sintático geral

O Templater agora aplica regras de sintaxe de forma mais rigorosa. Entre os erros de validação mais comuns estão:

• Bloco não fechado (faltando {% endif %} ou {% endfor %})
• Variável indefinida (referência a uma chave que não existe em var/data)
• Expressão malformada (espaçamento incorreto ou delimitadores incompatíveis)

👉 Checklist

1. Execute um teste de renderização para cada template de produção (use payloads que incluam e omitam campos opcionais).
2. Feche todos os blocos de controle com {% endif %} / {% endfor %}.
3. Defina suas variáveis (schema) ou forneça-as no payload; evite referências realmente indefinidas.
4. Revise operações aritméticas e identificadores: adicione espaços ao redor de operadores que precisam ser avaliados.
5. Coloque entre aspas todos os valores de href: href="{{ var:url }}".
6. Verifique a presença e o rendering de [[ UNSUB_LINK ]] em todos os lugares onde aparecer.

Gerenciamento de erros nos modelos

Explore este artigo abrangente que o guiará pelo processo de uso do recurso de gerenciamento de erros nos modelos do Mailjet. Esse recurso poderoso automatiza a verificação de seus modelos, poupando tempo valioso e eliminando a necessidade de verificações manuais. Diga adeus à tediosa tarefa de revisar individualmente cada modelo e adote uma abordagem simplificada para o gerenciamento eficiente de erros.