sistema-de-chamados/docs/AUTOMATIONS_EMAIL.md

Automações ▸ Envio de e-mails (guia de manutenção)

Visão geral

O envio de e-mails via automações funciona como uma ação dentro do motor de automações de tickets.

Por motivos de compatibilidade e segurança:

• O HTML do e-mail é gerado com tabelas + CSS inline (compatível com Gmail/Outlook/Apple Mail).
• O envio (SMTP) acontece em Convex Action ("use node"), porque mutações Convex não devem fazer I/O de rede.

Onde as automações disparam

Os eventos de ticket chamam o motor de automações em convex/tickets.ts:

• Criação do ticket (TICKET_CREATED)
• Alteração de status (STATUS_CHANGED)
• Alteração de prioridade (PRIORITY_CHANGED)
• Alteração de fila (QUEUE_CHANGED)
• Inclusão de comentário (COMMENT_ADDED)
• Finalização/resolução (TICKET_RESOLVED)

Onde a ação é validada e aplicada

Arquivo: convex/automations.ts

Pontos principais:

• Validação/parse da ação SEND_EMAIL em parseAction(...).
• Execução em applyActions(...):
  • Resolve destinatários (solicitante, responsável, usuário interno e e-mails livres).
  • Faz interpolação de variáveis {{...}} em assunto/mensagem.
  • Gera o HTML via React Email em convex/reactEmail.tsx (usando @react-email/render).
  • Agenda o envio via ctx.scheduler.runAfter(1, api.ticketNotifications.sendAutomationEmail, ...).

Onde o e-mail é enviado de fato (SMTP)

Arquivo: convex/ticketNotifications.ts

• A action sendAutomationEmail faz o envio via SMTP e aceita:
  • to: lista de destinatários
  • subject: assunto
  • html: HTML já renderizado

Observação: para não “vazar” destinatários entre si, o envio é feito um-a-um (um e-mail por destinatário).

Templates de e-mail

Templates (React Email) ficam em emails/ e podem ser pré-visualizados localmente.

Templates adicionados:

• emails/automation-email.tsx: usado pela ação SEND_EMAIL (inclui cartão com dados do ticket + CTA).
• emails/simple-notification-email.tsx: usado por notificações simples (comentário público / encerramento).

Renderização para HTML (backend):

• convex/reactEmail.tsx: renderAutomationEmailHtml(...) e renderSimpleNotificationEmailHtml(...).

Variáveis suportadas (interpolação)

Você pode usar estas variáveis em Assunto e Mensagem:

• {{ticket.reference}}
• {{ticket.subject}}
• {{ticket.status}}
• {{ticket.priority}}
• {{company.name}}
• {{requester.name}}
• {{assignee.name}}
• {{ticket.url.portal}}
• {{ticket.url.staff}}
• {{automation.name}}

Link do botão (CTA)

A UI permite escolher:

• Auto (padrão): se houver destinatário interno (responsável/usuário) usa Painel; caso contrário usa Portal.
• Portal (cliente): /portal/tickets/:id
• Painel (agente): /tickets/:id

Se você precisar enviar para cliente e agente no mesmo evento, prefira criar duas ações SEND_EMAIL (uma com link Portal e outra com link Painel).

Variáveis de ambiente (SMTP)

O envio no Convex tenta usar:

• SMTP_ADDRESS ou SMTP_HOST
• SMTP_USERNAME ou SMTP_USER
• SMTP_PASSWORD ou SMTP_PASS
• SMTP_PORT (default 465)
• MAILER_SENDER_EMAIL (legacy) ou SMTP_FROM_EMAIL + SMTP_FROM_NAME

Testes de regressão

Arquivo: tests/automations-engine.test.ts

• Teste adiciona um cenário onde a ação SEND_EMAIL está presente e valida que o envio é agendado via scheduler.runAfter.