# 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 com `renderAutomationEmail(...)` (`convex/emailTemplates.ts`).
  - 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
Arquivo: `convex/emailTemplates.ts`

Templates adicionados:
- `renderAutomationEmail(...)`: usado pela ação `SEND_EMAIL` (inclui cartão com dados do ticket + CTA).
- `renderSimpleNotificationEmail(...)`: utilitário reaproveitado por notificações simples (comentário público / encerramento).

## 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`.