Pular para o conteúdo principal

Layouts de e-mail

O layout de e-mail é o envelope HTML que embrulha toda mensagem de cobrança enviada por e-mail: cabeçalho com a sua marca, rodapé com os seus dados, e no meio o conteúdo do template da etapa. Template diz o que a mensagem fala; layout diz como ela se veste.

Os placeholders​

Um layout é um HTML completo com dois pontos de substituição:

  • {{content}} (obrigatório): onde o corpo do template entra. Um layout sem esse placeholder é rejeitado na criação (MISSING_CONTENT_PLACEHOLDER) — sem ele, o e-mail sairia sem a mensagem.
  • {{subject}} (opcional): o assunto da mensagem, útil em títulos internos do HTML.

A cascata: filial → empresa → organização​

Na hora do envio, o sistema resolve qual layout usar do mais específico para o mais geral:

  1. Layout da filial (unidade de negócio) da cobrança, se ela tiver um;
  2. senão, layout da empresa;
  3. senão, o layout padrão da organização (o marcado como default);
  4. senão, o layout embutido do produto: um HTML responsivo neutro (card branco de 600px, rodapé "Mensagem enviada automaticamente pelo sistema de cobrança").

Isso permite que um grupo com várias marcas envie cada cobrança com a identidade da empresa certa, sem duplicar réguas nem templates. A associação empresa/filial → layout é feita na estrutura organizacional.

Layouts inativos ou excluídos nunca são usados: a cascata simplesmente segue para o próximo nível.

Gerenciando layouts​

A gestão é feita pela API (/api/v1/email-layouts), com as permissões email_layouts.* do catálogo:

  • Listar (GET) devolve os layouts da organização, quantas empresas usam cada um e também o HTML do layout embutido, que serve de ponto de partida para o seu.
  • Criar (POST) exige name (2 a 80 caracteres) e htmlBody (mínimo 20 caracteres, contendo {{content}}). Marcar isDefault: true desmarca automaticamente o default anterior: só existe um padrão por organização.

Cada criação fica registrada na auditoria.

Boas práticas​

  • Comece copiando o layout embutido e troque cores, logo e rodapé: ele já é responsivo e testado em clientes de e-mail.
  • Use tabelas HTML e CSS inline: e-mail não é navegador, e os clientes de e-mail mais usados ignoram folhas de estilo externas.
  • Inclua no rodapé a razão social e os dados de contato do credor: além de boa prática, reduz marcação de spam e sustenta a exigência de identificação clara do cobrador.
  • Teste a cascata: envie uma cobrança de teste por uma filial com layout próprio e outra por uma empresa sem layout, e confirme que cada uma sai com a roupa certa.