# Relatórios por e-mail

Resumos pessoais com filtros, timezone e controle de envio.

## Criar um relatório

Na Visão geral ou Receita, abra Por e-mail. Escolha um nome e frequência diária, semanal ou mensal. O envio é pessoal, para o e-mail verificado da sua conta; destinatários arbitrários não são aceitos. Leitores também podem configurar seus próprios resumos, mantendo o mesmo acesso de consulta. O limite técnico é de 20 relatórios ativos por conta, igual em todos os planos. Pause um relatório para interromper novos envios.


## Período e timezone

O agendamento é às 8h no timezone IANA do site: diário, segundas-feiras no semanal e dia 1 no mensal. O worker verifica agendamentos a cada minuto; backlog ou falhas podem atrasar a entrega. Diário usa o dia local anterior; semanal os sete dias locais completos anteriores; mensal o mês civil anterior. O fim é exclusivo. Mudanças de horário de verão não são convertidas silenciosamente em dias fixos de 24 horas. Se o timezone mudar depois de enfileirar, o envio é cancelado e o próximo agendamento usa a configuração atual.


## Recorte e conteúdo

Tráfego preserva filtros combinados, dimensão e busca selecionados ao criar; não preserva as datas da tela. O resumo inclui indicadores e até 20 linhas da dimensão, com link autenticado para o recorte completo. Receita preserva ambiente e moeda, separa moedas, apresenta bruto, reembolsos, chargebacks, ajustes totais e receita e não inclui transações ou IDs de clientes. Nenhuma consulta ou e-mail consome unidades de eventos. Alterar os filtros da tela não modifica um relatório já criado.


## Fila, retries e permissões

Enviar último período solicita o mesmo recorte completo da frequência escolhida. Há somente uma execução por relatório e fim de período, inclusive entre scheduler e cliques concorrentes. O conteúdo é persistido antes da entrega e reutilizado nos retries com identificador estável. Antes de gerar e antes de enviar, o worker verifica novamente conta, e-mail, workspace, site e permissões. Perda de acesso, suspensão, pausa ou mudança do e-mail/timezone bloqueiam o envio pendente. Mensagens já entregues ao destinatário não podem ser recolhidas.


## Configuração e diagnóstico

Os envios usam a abstração MAIL_TRANSPORT: smtp para desenvolvimento/Mailpit e resend com credencial/domínio configurados para envio externo. API e worker precisam estar ativos; PostgreSQL mantém execução/outbox e BullMQ entrega ao worker. O modal mostra fila, envio, cancelamento e falha aguardando retry. Operadores autorizados podem localizar email_report na fila e reprocessar com auditoria; isso não ignora permissões nem reenviará uma execução já concluída. SMTP tem semântica de pelo menos uma entrega: uma queda após aceitação e antes do commit pode duplicar a mensagem, apesar do Message-ID estável. Resend usa sua chave de idempotência dentro da janela do provedor; não prometemos entrega exatamente uma vez em todos os transportes.


## Retenção

O corpo HTML/texto do relatório é removido do registro operacional após 30 dias; permanecem IDs, estados e datas para diagnóstico. Envios ainda pendentes após 30 dias expiram, sem entregar um resumo antigo inesperadamente. Essa política não apaga e-mails já recebidos nem substitui a exclusão de dados analíticos. A validação local utiliza um servidor SMTP de teste em loopback; envio externo Resend exige configuração e validação próprias.