> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weve.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Campanhas e automações

> O e-mail que o club manda aos alunos: disparos únicos e réguas que reagem ao que o aluno faz.

Uma **campanha** é um e-mail que sai uma vez, para uma lista. Uma **automação** é uma
sequência de passos que começa quando algo acontece com um aluno — ganhou acesso, comprou,
concluiu uma aula. As duas usam o mesmo conteúdo, o mesmo envio e o mesmo descadastro.

## O conteúdo

O corpo do e-mail é uma **lista de blocos**, e quem escreve o HTML é a API. O club manda só o
que vai dentro de cada bloco:

| kind        | o que é                                                                     |
| ----------- | --------------------------------------------------------------------------- |
| `heading`   | título, nível 1 ou 2                                                        |
| `paragraph` | texto com `**negrito**`, `*itálico*`, `[link](https://…)` e quebra de linha |
| `button`    | rótulo e destino                                                            |
| `image`     | uma mídia **pública** da biblioteca                                         |
| `divider`   | separador                                                                   |

A imagem precisa ser pública porque o e-mail fica na caixa de entrada por tempo
indeterminado, e a URL assinada de uma mídia privada venceria lá dentro.

### Variáveis

Toda campanha e todo passo de automação aceitam:

| variável            | valor                         |
| ------------------- | ----------------------------- |
| `{{name}}`          | nome do aluno                 |
| `{{first_name}}`    | primeiro nome                 |
| `{{club_name}}`     | nome do club                  |
| `{{classroom_url}}` | endereço do classroom do club |

`{{first_name|aluna}}` usa o texto depois da barra quando o valor está vazio. Os valores saem
**sempre escapados**: um nome com marcação aparece como texto, nunca como HTML.

A automação acrescenta as variáveis do gatilho:

| gatilho                            | variáveis                      |
| ---------------------------------- | ------------------------------ |
| `access_granted`, `access_revoked` | `delivery_name`                |
| `purchase_*`, `subscription_*`     | `product_name`                 |
| `lesson_completed`                 | `course_title`, `lesson_title` |
| `course_completed`                 | `course_title`                 |

Variável desconhecida — ou que o gatilho não oferece — é recusada com `422` ao agendar a
campanha ou publicar a automação. O rascunho aceita, porque pode estar pela metade.

## Campanhas

```text theme={null}
draft → scheduled → sending ⇄ paused
                        ↓
                       sent
```

`scheduled`, `sending` e `paused` podem ir para `canceled`.

* **Agendar** confere o conteúdo inteiro e a audiência. Sem data, a campanha sai em instantes.
  `unschedule` a devolve ao rascunho enquanto o horário não chegou.
* **No horário, a lista congela**, uma vez, com cada pessoa no máximo uma vez. Daí em diante o
  envio segue em lotes e a campanha não muda mais: o e-mail que metade da lista recebeu é o que
  a outra metade recebe.
* **Pausar** vale no lote seguinte — o que já está com o provedor termina.
* **Retomar** continua a mesma lista, sem reavaliar a audiência: quem entrou no club depois do
  disparo não recebe.
* **Cancelar** não se desfaz. O que não saiu fica como `canceled`, e os números de quem já recebeu
  continuam valendo.

### Audiência

A audiência tem `include` e `exclude`, cada um com entregas, turmas, produtos e cursos
concluídos. Dentro de cada um, **qualquer regra casa**. Sem `include`, a campanha vai para o club
inteiro; `exclude` tira quem casar com qualquer regra dele. Um id que deixou de existir não casa
com ninguém — a audiência nunca se alarga sozinha.

Só recebe quem é **alcançável**: conta não removida e com o e-mail confirmado — ou criada por
compra, importação ou convite, em que o endereço veio de quem vendeu ou de quem administra.
`GET …/audience` conta essa mesma regra antes do disparo.

## Automações

O **rascunho** é conferido só na forma: tipos conhecidos, ids de passo únicos, tamanho e
profundidade. Ele pode estar incompleto, e nada dispara a partir dele.

**Publicar** confere tudo e grava uma **versão imutável**, que passa a abrir as execuções novas.
As execuções em curso continuam na versão em que entraram — editar a régua não muda o caminho
de quem já está nela.

### Passos

Os passos formam uma árvore:

| kind         | faz                                                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `send_email` | envia o e-mail do passo                                                                                                        |
| `wait`       | `delay` espera um tempo a partir da chegada ao passo; `before_expiry` espera até N dias antes do fim da matrícula que disparou |
| `condition`  | segue por `then` ou `else`, e depois continua no passo seguinte                                                                |
| `exit`       | encerra a execução                                                                                                             |

As regras da condição são avaliadas **no momento do passo**, contra o estado atual: se o aluno
concluiu a aula ontem, a condição de hoje já vê.

O `id` de cada passo precisa ser estável entre versões: é por ele que os números somam e que uma
regra de "abriu o e-mail" cita o envio.

### Quem entra, e quando sai

* `reentry`: `once` (uma vez na vida, o padrão), `one_at_a_time` (a cada evento, mas nunca duas em
  curso) ou `always` (uma execução por evento).
* `exit_on_access_lost`: encerra a execução quando a matrícula que disparou é revogada ou vence.
* `exit_when`: a meta. Conferida antes de cada passo; atingida, a execução termina — quem já
  comprou não recebe o resto da régua de venda.

### Pausar e arquivar

**Pausar** para de abrir execuções e **retém** as que estão em curso; ao retomar, elas continuam de
onde pararam. Os fatos que aconteceram durante a pausa **não** abrem execução: pausar é parar de
ouvir. **Arquivar** encerra as execuções em curso e não se desfaz; a trilha e os números ficam.

## Entrega

O envio sai em **lotes**, com um **teto diário por club** — 10.000 e-mails por dia, por padrão. O
que passa do teto sai no dia seguinte. Os e-mails de automação têm **prioridade** sobre os de
campanha: o boas-vindas de quem acabou de comprar não espera o fim de um disparo grande.

## Descadastro e supressão

Todo e-mail de campanha e automação leva:

* os cabeçalhos `List-Unsubscribe` e `List-Unsubscribe-Post` — o descadastro de **um clique**
  (RFC 8058) que o Gmail e o Yahoo mostram ao lado do remetente;
* o link no rodapé para a tela do classroom,
  `<slug>.weve.studio/email-preferences?token=…`.

O descadastro vale para as campanhas e automações **daquele club**. Os e-mails de conta
(confirmar endereço, redefinir senha, código de entrada) e os avisos de acesso continuam: sem eles
a pessoa não entra.

| motivo             | alcance            | desfaz                            |
| ------------------ | ------------------ | --------------------------------- |
| descadastro        | o club             | a própria pessoa, pela mesma tela |
| reclamação de spam | o club             | não se desfaz                     |
| bounce permanente  | **todos** os clubs | não se desfaz                     |

Quem administra **não remove** supressão. O endereço que voltou com bounce não existe, e quem
reclamou disse ao provedor que não quer — reenviar nos dois casos derruba a reputação do envio de
todos os clubs.

## Métricas

Em cada envio, `status` é o **envio** (`pending`, `sending`, `sent`, `skipped`, `failed`). Entrega,
bounce, reclamação, abertura e clique são carimbos à parte, preenchidos **uma vez** — os números
contam **pessoas**, não batidas: abrir dez vezes é uma abertura.

<Warning>
  A abertura é aproximada: clientes de e-mail que baixam as imagens sozinhos contam como abertos.
  O clique é o sinal confiável.
</Warning>

## Configuração do ambiente

Para quem opera a API:

| variável                | para quê                                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `MARKETING_MAIL_FROM`   | remetente, num subdomínio usado **só** para marketing — a reclamação de uma campanha não pode afetar a entrega do e-mail de redefinir senha |
| `RESEND_WEBHOOK_SECRET` | segredo do webhook `POST /webhooks/email`                                                                                                   |
| `MARKETING_DAILY_LIMIT` | teto diário por club (padrão 10.000; `0` desliga)                                                                                           |

O webhook é configurado no painel do Resend, apontando para `POST /webhooks/email`, com os eventos
`email.delivered`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked` e
`email.suppressed`.

Sem `RESEND_API_KEY` e `MARKETING_MAIL_FROM`, ou sem `SECRETS_KEY` — que assina o link de descadastro —, agendar uma
campanha e publicar uma automação respondem `501`: nada entra numa fila que não vai andar.


## Related topics

- [Descadastrar](/api-reference/email/unsubscribe.md)
- [Campanha](/api-reference/campaigns/get.md)
- [Campanhas](/api-reference/campaigns/list.md)
- [Automações](/api-reference/workflows/list.md)
- [Enviar teste do passo](/api-reference/workflows/email-test.md)