API Reference: Emails

Sistema de envio de emails transacionais e manuais via Resend API. Remetente: [email protected]. Variavel de ambiente: RESEND_API_KEY.

MailService

Servico NestJS responsavel por todo envio de email da plataforma via Resend.

Metodo	Descricao
`sendTemplate(tipo, destinatario, dados)`	Envia um email usando template HTML pre-definido pelo tipo
`sendToSegment(tipo, filtros, dados)`	Envia email para um segmento de usuarios filtrado por `cargo` e/ou `plano`
`sendManual(destinatarios, assunto, html)`	Envia email com conteudo HTML livre (usado pela tela de admin e pela IA)
`listLogs(filtros)`	Retorna registros da tabela `email_logs` com paginacao
`getTemplates()`	Retorna lista de templates disponiveis com preview

Branded Templates

Todos os templates sao HTML inline-styled e utilizam as cores e branding do nucleo:

cor_primaria — cor principal do nucleo (usada em headers, botoes e destaques)
logo_url — URL do logo do nucleo no Supabase Storage
nome_nucleo — nome do nucleo para o rodape
nome_usuario — nome do destinatario para personalizacao

Cada nucleo tem seus emails personalizados com suas cores e logo, garantindo identidade visual consistente.

Tipos de Email

Tipo	Descricao	Trigger
`aprovacao`	Membro aprovado no nucleo	Automatico ao aprovar cadastro
`rejeicao`	Membro rejeitado	Automatico ao rejeitar cadastro
`comunicado`	Novo comunicado publicado	Checkbox "Enviar email" ao criar comunicado
`enquete`	Nova enquete criada	Checkbox "Enviar email" ao criar enquete
`pagamento`	Confirmacao de pagamento recebido	Webhook Asaas PAYMENT_RECEIVED
`pagamento_atrasado`	Aviso de pagamento em atraso	Webhook Asaas PAYMENT_OVERDUE
`conquista`	Nova conquista desbloqueada	Automatico ao desbloquear conquista
`manual`	Email livre escrito pelo admin	Tela de admin /dashboard/admin/emails

Endpoints

POST /api/admin/emails/enviar

Envia email manual para lista de destinatarios ou segmento.

Permissao: COORDENADOR / ADMINISTRADOR

Campo	Tipo	Obrigatorio	Descricao
`assunto`	string	Sim	Assunto do email
`html`	string	Sim	Conteudo HTML do email
`destinatarios`	string[]	Condicional	Lista de emails (se nao usar segmento)
`segmento`	object	Condicional	Filtros `{ cargo?, plano? }` para envio por segmento

GET /api/admin/emails/templates

Retorna lista de templates disponiveis com nome, tipo e preview HTML.

Permissao: COORDENADOR / ADMINISTRADOR

GET /api/admin/emails/logs

Retorna logs de emails enviados com paginacao.

Permissao: COORDENADOR / ADMINISTRADOR

Query params

Param	Tipo	Descricao
`page`	number	Pagina (default 1)
`limit`	number	Itens por pagina (default 20)
`tipo`	string	Filtrar por tipo de email
`status`	string	Filtrar por status (sent, failed)

Admin: /dashboard/admin/emails

Pagina administrativa com 3 abas:

Enviar — formulario para envio manual com editor HTML, selecao de destinatarios ou segmento (cargo/plano), e assistente IA
Templates — lista de templates disponiveis com preview visual de cada tipo
Logs — tabela paginada com historico de todos os emails enviados (tipo, destinatario, status, data)

Preview Side-by-Side (Desktop)

A tela de envio de emails possui um preview em tempo real:

Layout desktop: Side-by-side — formulario de edicao a esquerda, preview renderizado a direita
Branding do nucleo: O preview exibe o template com o logo, nome e cor_primaria do nucleo do usuario
Atualizacao em tempo real: Conforme o usuario digita o assunto e conteudo, o preview atualiza instantaneamente
Template fiel: O preview utiliza o mesmo template HTML que sera enviado no email final

Assistente IA para Emails

Na aba de envio (/dashboard/admin/emails), o botao Assistente IA permite criar emails com ajuda da inteligencia artificial:

Clique no botao Assistente IA
Descreva o que deseja comunicar em linguagem natural (ex: "Email convidando para o evento de sabado no centro de Vitoria")
A IA gera automaticamente o assunto e o conteudo HTML do email
O preview em tempo real e exibido ao lado com as cores e branding do nucleo
Edite o assunto ou conteudo gerado conforme necessario
Confirme e envie o email normalmente (selecionando destinatarios ou segmento)

O admin pode regenerar o conteudo quantas vezes quiser antes de enviar. Tambem e possivel criar emails via chat no AI Chat Widget usando as ferramentas prepararEmail e enviarEmail.

Emails Nacional

Emails do nivel Nacional sao enviados para membros de todos os nucleos:

Enviados pelo super admin via painel nacional
Utilizam branding generico (logo e cores da organizacao nacional)
Registrados nos logs com origem "nacional"

Tabela: email_logs

Coluna	Tipo	Descricao
`id`	uuid	PK
`destinatario`	text	Email do destinatario
`assunto`	text	Assunto do email enviado
`tipo`	text	Tipo do template usado
`status`	text	sent ou failed
`remetente_id`	uuid	FK para usuarios (quem disparou, se manual)
`manual`	boolean	Se foi envio manual (true) ou automatico (false)
`origem`	text	Contexto de origem (ex: comunicado, enquete, webhook, nacional)
`nucleo_id`	uuid	FK para nucleos (multi-tenant)
`criado_em`	timestamptz	Data de envio

Segmentacao (sendToSegment)

O metodo sendToSegment aceita filtros para enviar emails apenas para um subconjunto de membros:

cargo — filtra por cargo do membro (ex: COORDENADOR, MEMBRO)
plano — filtra por plano ativo (ex: APOIADOR, MILITANTE)

Os filtros podem ser combinados. Se nenhum filtro for informado, envia para todos os membros ativos do nucleo.

Preferencias do Usuario

Usuarios podem desativar tipos de email nas configuracoes do perfil. A coluna preferencias_notificacao (JSONB) na tabela usuarios armazena as preferencias:

{
  "email_comunicado": true,
  "email_enquete": true,
  "email_pagamento": true,
  "email_conquista": false
}

O MailService consulta as preferencias antes de enviar emails automaticos. Emails manuais enviados por admins ignoram preferencias.