mail

O submódulo Mail gerencia templates de e-mail transacional e delega a entrega propriamente dita ao provedor de integração configurado para o canal de e-mail. Separar o gerenciamento de templates do transporte significa que o mesmo sistema de templates funciona com qualquer servidor SMTP, SendGrid, Mailgun ou outro provedor suportado pelas bibliotecas de integração instaladas — trocar de provedor exige alterar um Integration Profile, não implantar novo código.

Um template de e-mail é identificado por um slug e contém uma ou mais traduções específicas por locale, cada uma com um assunto e um corpo em HTML. Os placeholders de variáveis no corpo são substituídos no momento do envio usando um mapa de variáveis. O schema de variáveis declarado em mail_var serve como documentação para os consumidores do template. Esse design mantém o conteúdo do template editável pelo painel de administração em tempo de execução — mudanças de texto, atualizações de localização e ajustes de layout não exigem deploys de código nem reinicializações do servidor.

Quando um e-mail é disparado, o locale é resolvido para o destinatário (a partir das preferências do usuário ou do contexto da requisição) e a tradução correspondente é utilizada. Se não existir tradução para o locale de destino, o sistema recorre ao locale padrão configurado nas configurações. Isso significa que um único slug de template funciona em todos os idiomas suportados, sem lógica condicional no código chamador.

POST /mail/reload faz o serviço de e-mail reler a configuração do provedor sem reiniciar o servidor, permitindo atualizações de credenciais SMTP ou trocas de provedor em produção com zero downtime. POST /mail/test renderiza um template especificado e envia o resultado a um endereço de teste, tornando possível verificar a formatação e a substituição de variáveis antes de uma funcionalidade entrar em produção.

O endpoint de importação em massa aceita um payload JSON estruturado contendo múltiplos templates e faz o upsert deles em uma única requisição. Com overwrite: true, os templates existentes são atualizados; sem ele, os slugs existentes são ignorados. Esse endpoint foi projetado para pipelines de CI/CD que gerenciam templates de e-mail junto com o código da aplicação, garantindo que o conteúdo dos templates permaneça sob controle de versão.

Os registros de e-mails enviados e os metadados de entrega são acompanhados pelo submódulo complementar mail-sent, que mantém o status (received, read, error), os endereços dos destinatários e os detalhes de erro de cada mensagem enviada.