Templates de Email

Templates permitem criar emails reutilizáveis com variáveis dinâmicas. Crie uma vez, envie milhares de vezes com dados diferentes.

Conceitos

Template: HTML + texto com variáveis (ex: {{ nome }})
Variáveis: Dados inseridos no momento do envio (nome, link, código OTP, etc.)
Categoria: Agrupamento lógico (transacional, marketing, OTP)
Preview: Renderização com dados de teste antes de enviar

Criar um template

Via API

curl -X POST https://app.usenotifica.com.br/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tpl-welcome-v1" \
  -d '{
    "name": "welcome-email",
    "channel": "email",
    "category": "transactional",
    "subject": "Bem-vindo, {{ nome }}!",
    "html_body": "<h1>Olá, {{ nome }}!</h1><p>Sua conta foi criada com sucesso.</p><p><a href=\"{{ confirmation_url }}\">Confirmar email</a></p>",
    "text_body": "Olá, {{ nome }}! Sua conta foi criada. Confirme em: {{ confirmation_url }}",
    "variables": {
      "nome": {
        "type": "string",
        "required": true,
        "example": "Maria"
      },
      "confirmation_url": {
        "type": "string",
        "required": true,
        "example": "https://app.exemplo.com/confirm?token=abc123"
      }
    }
  }'

Resposta:

{
  "id": "tpl_abc123",
  "name": "welcome-email",
  "channel": "email",
  "category": "transactional",
  "subject": "Bem-vindo, {{ nome }}!",
  "html_body": "<h1>Olá, {{ nome }}!</h1>...",
  "text_body": "Olá, {{ nome }}! ...",
  "variables": {
    "nome": { "type": "string", "required": true, "example": "Maria" },
    "confirmation_url": { "type": "string", "required": true, "example": "..." }
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Via Dashboard

Acesse Templates → Criar Template no dashboard
Selecione o canal Email
Preencha nome, assunto, corpo HTML e texto
Defina as variáveis e valores de exemplo
Use o preview ao vivo para validar
Salve

Sintaxe de variáveis

O Notifica usa sintaxe Liquid para variáveis em templates.

Variáveis simples

<p>Olá, {{ nome }}!</p>
<p>Seu pedido #{{ pedido_id }} foi confirmado.</p>

Condicionais

{% if plano == "premium" %}
  <p>Obrigado por ser assinante Premium! 🎉</p>
{% else %}
  <p>Conheça nosso plano Premium para benefícios exclusivos.</p>
{% endif %}

Loops

<h2>Itens do seu pedido:</h2>
<ul>
{% for item in itens %}
  <li>{{ item.nome }} — R$ {{ item.preco }}</li>
{% endfor %}
</ul>

Filtros

<!-- Uppercase -->
<p>{{ nome | upcase }}</p>

<!-- Default value -->
<p>Olá, {{ nome | default: "Cliente" }}!</p>

<!-- Date formatting -->
<p>Data: {{ data_pedido | date: "%d/%m/%Y" }}</p>

<!-- Number formatting -->
<p>Total: R$ {{ total | round: 2 }}</p>

Variáveis disponíveis automaticamente

Além das variáveis que você define, o Notifica injeta automaticamente:

Variável	Descrição
`{{ unsubscribe_url }}`	Link para cancelar inscrição (LGPD)
`{{ preferences_url }}`	Link para gerenciar preferências
`{{ current_year }}`	Ano atual (para rodapé © 2025)

aviso

Sempre inclua {{ unsubscribe_url }} em emails marketing. Isso é obrigatório pela LGPD e melhora a entregabilidade.

Categorias de template

Categoria	Uso	Exemplos
`transactional`	Emails disparados por ação do usuário	Confirmação de conta, reset de senha, recibo de compra
`marketing`	Campanhas e promoções	Newsletter, promoção, lançamento
`otp`	Códigos de verificação	2FA, confirmação de telefone
`system`	Notificações do sistema	Alerta de segurança, fatura disponível

informação

Emails transactional e otp são enviados mesmo se o usuário desativou comunicações marketing. Emails marketing respeitam as preferências de opt-out.

Gerenciar templates

Listar todos

curl https://app.usenotifica.com.br/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY"

Obter detalhes

curl https://app.usenotifica.com.br/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Atualizar

curl -X PUT https://app.usenotifica.com.br/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Bem-vindo ao App, {{ nome }}!",
    "html_body": "<h1>Bem-vindo, {{ nome }}!</h1><p>Novo corpo do email.</p>"
  }'

Excluir

curl -X DELETE https://app.usenotifica.com.br/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

aviso

Excluir um template não afeta emails já enviados, mas workflows que referenciam esse template passarão a falhar.

Preview e validação

Preview com dados de teste

Renderiza o template com variáveis de exemplo, sem enviar nada.

Preview de um template salvo:

curl -X POST https://app.usenotifica.com.br/v1/templates/tpl_abc123/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "nome": "Maria Silva",
      "confirmation_url": "https://app.exemplo.com/confirm?token=test123"
    }
  }'

Resposta:

{
  "subject": "Bem-vindo, Maria Silva!",
  "html_body": "<h1>Olá, Maria Silva!</h1><p>Sua conta foi criada com sucesso.</p><p><a href=\"https://app.exemplo.com/confirm?token=test123\">Confirmar email</a></p>",
  "text_body": "Olá, Maria Silva! Sua conta foi criada. Confirme em: https://app.exemplo.com/confirm?token=test123"
}

Preview de conteúdo avulso (sem salvar):

curl -X POST https://app.usenotifica.com.br/v1/templates/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Código: {{ codigo }}",
    "html_body": "<p>Seu código é: <strong>{{ codigo }}</strong></p>",
    "variables": {
      "codigo": "123456"
    }
  }'

Validação

Verifica se o template é válido (sintaxe Liquid correta, variáveis definidas).

Validar um template salvo:

curl -X POST https://app.usenotifica.com.br/v1/templates/tpl_abc123/validate \
  -H "Authorization: Bearer YOUR_API_KEY"

Validar conteúdo avulso:

curl -X POST https://app.usenotifica.com.br/v1/templates/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Olá {{ nome }",
    "html_body": "<p>{% if %}</p>"
  }'

Resposta com erros:

{
  "valid": false,
  "errors": [
    {
      "field": "subject",
      "message": "Liquid syntax error: missing closing braces '}}'"
    },
    {
      "field": "html_body",
      "message": "Liquid syntax error: 'if' tag requires a condition"
    }
  ]
}

Enviar email usando template

curl -X POST https://app.usenotifica.com.br/v1/notifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-maria-001" \
  -d '{
    "channel": "email",
    "recipient": "[email protected]",
    "template_id": "tpl_abc123",
    "payload": {
      "from": "[email protected]",
      "variables": {
        "nome": "Maria Silva",
        "confirmation_url": "https://app.suaempresa.com.br/confirm?token=xyz789"
      }
    }
  }'

dica

Use a header Idempotency-Key para evitar envios duplicados em caso de retry. O mesmo idempotency key retorna a mesma resposta sem reenviar.

Boas práticas para entregabilidade

Estrutura do HTML

Use tabelas para layout — Email clients não suportam flexbox/grid de forma confiável
Inline CSS — Evite <style> tags; muitos clients removem o <head>
Largura máxima: 600px — Padrão para boa visualização em desktop e mobile
Sempre inclua versão texto — Melhora score de spam e acessibilidade

Conteúdo

Proporção texto/imagem — Mínimo 60% texto. Emails só com imagens são classificados como spam
Evite palavras de spam — "GRÁTIS!!!", "CLIQUE AQUI", texto TODO EM CAPS
Assunto curto — Máximo 50 caracteres. Inclua contexto, não clickbait

Preheader — Adicione texto de preview logo no início do HTML:

<div style="display:none;max-height:0;overflow:hidden;">
  Sua conta foi criada com sucesso. Confirme seu email para começar.
</div>

LGPD e compliance

Link de unsubscribe visível — Use {{ unsubscribe_url }} no rodapé
Identifique-se — Inclua nome da empresa e CNPJ no rodapé
Endereço físico — Obrigatório para emails marketing (LGPD + CAN-SPAM)
Respeite opt-out — Use categorias corretamente. Emails marketing são automaticamente filtrados para quem optou por não receber

Template de rodapé recomendado

<table width="100%" style="margin-top:32px;border-top:1px solid #eee;padding-top:16px;">
  <tr>
    <td style="color:#666;font-size:12px;line-height:1.5;">
      <p>{{ empresa_nome }} — CNPJ {{ empresa_cnpj }}</p>
      <p>{{ empresa_endereco }}</p>
      <p>
        <a href="{{ unsubscribe_url }}">Cancelar inscrição</a> |
        <a href="{{ preferences_url }}">Gerenciar preferências</a>
      </p>
      <p>© {{ current_year }} {{ empresa_nome }}. Todos os direitos reservados.</p>
    </td>
  </tr>
</table>

Próximos passos

Configuração de Domínio — Verifique seu domínio antes de enviar
Configuração SMTP — Envie emails via relay SMTP
Quickstart Email — Envie seu primeiro email em 5 minutos

Conceitos​

Criar um template​

Via API​

Via Dashboard​

Sintaxe de variáveis​

Variáveis simples​

Condicionais​

Loops​

Filtros​

Variáveis disponíveis automaticamente​

Categorias de template​

Gerenciar templates​

Listar todos​

Obter detalhes​

Atualizar​

Excluir​

Preview e validação​

Preview com dados de teste​

Validação​

Enviar email usando template​

Boas práticas para entregabilidade​

Estrutura do HTML​

Conteúdo​

LGPD e compliance​

Template de rodapé recomendado​

Próximos passos​