Documentação

Português

English
Español

Português

English
Español

Appearance

Envio de e-mail ​

Pré-requisitos de acesso

  • Permissão (módulo): acesso liberado pelo guard administrativo da rota (admin). Não há módulo dinâmico específico para esta tela — qualquer operador com acesso ao BackOffice e ao grupo de Comunicação consegue abri-la.
  • Licença/Feature: Nenhuma.
  • Contêiner do menu: GERAL → grupo Comunicação (ícone campaign) → Envio de e-mail.

O que é / quando usar ​

Tela para criar e agendar disparos de e-mail em massa (ou para uma lista de destinatários específicos) a partir do BackOffice. Use para comunicados, campanhas promocionais, avisos operacionais e mensagens de relacionamento, sem precisar de deploy ou ferramenta externa. Cada disparo criado vira uma "ação em massa" (entidade MassActions, action = 'EMAIL') que fica numa fila e é processada por um scheduler do CommunicationGateway — não há envio síncrono no momento do "Confirmar".

Pré-condições ​

  • Permissão: o item está sob o guard admin da rota. Lembre que no Axia a permissão é dupla (enum CPM no backend + módulo dinâmico no DB); aqui o gate efetivo é o guard de rota, então valide que o operador tem perfil administrativo.
  • Licença/Feature: nenhuma feature de licença é exigida para abrir a tela.
  • Dependências de outras telas: no modo single (destinatário individual), o e-mail digitado é validado contra a base de usuários — só entra na lista quem possui conta/carteira cadastrada. Para o conteúdo visual final dos e-mails, o Template Master define o "envelope" HTML aplicado aos disparos.

Passo a passo ​

  1. Acesse o menu Comunicação → Envio de e-mail.
  2. A tela lista os disparos já criados, com as colunas Quando, Assunto, Status e ações de editar/excluir.
  3. Clique em Novo / Criar para abrir o modal de criação.
  4. Escolha o público no seletor superior: Todos (all) ou Individual (single).
  5. No modo Individual, digite cada e-mail e clique no botão + para validá-lo e adicioná-lo como chip; repita para cada destinatário.
  6. Preencha Assunto, Mensagem e Data de agendamento.
  7. Clique em Confirmar. O disparo é criado com status inicial e entra na fila do scheduler.

Campos ​

Listagem ​

ColunaO que mostraOrigem do dado
Quando (when)Data de criação/agendamento do disparoCampo when/scheduleTo da MassActions
Assunto (subject)Assunto do e-mailCampo subject
Status (status)Estado do disparo: CREATED/PENDING (na fila), EXECUTED (enviado), CANCELLED (cancelado)Campo status, atualizado pelo scheduler
EditarReabre o modal em modo edição—
ExcluirCancela o disparo (não apaga: marca status = 'CANCELLED')—
CampoO que éObrigatório?Efeito no sistema/backend
Público (Todos / Individual)Define se o disparo vai para toda a base ou para uma listaSimNo backend, all = true faz o handler buscar todos os usuários (getAllUsers) e criar um registro mass_actions_users PENDING por usuário; all = false cria um registro por e-mail da lista. No modo edição, o toggle fica bloqueado (não dá para trocar o público de um disparo existente).
E-mail (só no modo Individual)Destinatário a ser adicionadoCondicional (≥1 no modo Individual)Ao clicar +, o e-mail é validado contra a base via getUserByEmailWallet: só é aceito se existir usuário/carteira correspondente. Vira um chip; o disparo não confirma com a lista vazia no modo Individual.
Assunto (subject)Linha de assunto do e-mailSimGravado em MassActions.subject (máx. 100 caracteres). Usado como subject no envio real.
Mensagem (message)Corpo do e-mailSimGravado em MassActions.message. Suporta HTML e o token de personalização @user.name (ver Regras). É injetado tanto em bodyData quanto em htmlData no envio.
Data (when)Data a partir da qual o disparo pode ser processadoSimMínimo = hoje (não permite passado). O scheduler roda a cada 30 minutos e processa a fila; a data baliza o agendamento do disparo.

Ações e modais ​

  • Criar (Confirmar): cria a MassActions (action = 'EMAIL', status = 'CREATED') e os registros de destinatário PENDING. Após salvar, a tela recarrega.
  • Editar: permite ajustar Assunto, Mensagem e Data de um disparo existente; o público (Todos/Individual) e a lista de e-mails ficam somente leitura. Ao salvar, o disparo volta para status = 'CREATED'.
  • Excluir: não remove fisicamente — marca o disparo como CANCELLED, retirando-o do processamento.
  • Step-up / MFA: esta tela não dispara re-autenticação por padrão. Trate o disparo em massa como ação sensível na operação (público amplo, irreversível após envio).

Regras de negócio / cuidados ​

Atenção

  • O e-mail individual só é aceito se já existir na base (validação getUserByEmailWallet). Endereços externos/desconhecidos não entram na lista.
  • O envio não é imediato: o CommunicationScheduler roda no cron */30 * * * * (a cada 30 min). Após "Confirmar", há latência até o disparo sair.
  • A mensagem aceita HTML. Como o corpo é injetado em bodyData e htmlData, HTML mal formado pode quebrar a renderização em provedores como Mailgun/Brevo/SendGrid (no SES o problema fica mascarado).
  • Personalização: se a mensagem contiver @user.name, o scheduler busca o primeiro nome do usuário e substitui o token por destinatário. Sem o token, a mensagem é enviada literal.

Irreversível

  • Depois que o scheduler processa o disparo, não há rollback do e-mail enviado. Excluir/cancelar só impede disparos ainda PENDING — e-mails já EXECUTED permanecem entregues. Revise público, assunto e corpo antes de confirmar, especialmente no modo Todos (atinge a base inteira).
  • Idempotência: o processamento é idempotente por destinatário — cada mass_actions_users só é enviado quando está PENDING e passa a EXECUTED após o envio. Reexecuções do scheduler não reenviam quem já recebeu. Ao final, a MassActions também vai para EXECUTED.
  • Observação sobre o estado: disparos CANCELLED são ignorados pelo scheduler.

Exemplos ​

Cenário 1 — Comunicado para toda a base
  1. Novo → público Todos.
  2. Assunto: Manutenção programada no fim de semana.
  3. Mensagem (HTML simples): <p>Olá @user.name, faremos manutenção no sábado das 2h às 5h.</p>.
  4. Data: hoje.
  5. Confirmar. O handler cria um registro PENDING para cada usuário da base; no próximo ciclo do scheduler (≤ 30 min) cada um recebe o e-mail com seu primeiro nome no lugar de @user.name. Status do disparo passa a EXECUTED.
Cenário 2 — Disparo individual para uma lista curta
  1. Novo → público Individual.
  2. Digite joao@cliente.com, clique + (validado contra a base → vira chip). Repita para maria@cliente.com.
  3. Assunto e mensagem normais; Data: hoje.
  4. Confirmar. Apenas os 2 destinatários recebem registros PENDING. Se um e-mail não existir na base, o + não o adiciona e ele fica de fora.
Cenário 3 — Corrigir o assunto de um disparo ainda não enviado
  1. Na listagem, clique em Editar de um disparo CREATED/PENDING.
  2. O seletor de público e a lista de e-mails aparecem bloqueados; ajuste apenas Assunto ou Mensagem.
  3. Confirmar. O disparo volta para CREATED e será reprocessado pelo scheduler. Destinatários que ainda estão PENDING recebem a versão corrigida; quem já está EXECUTED não é afetado.

Telas relacionadas ​