# Sequências

> Sequências de e-mail por evento no Couryo, com gatilhos, passos (enviar, esperar, condição, sair), saídas automáticas, horário de silêncio e limite por contato. Sem cobrança por contato.

Fonte: https://couryo.com/docs/sequences

Uma **sequência** manda uma série de e-mails para cada contato que entra nela: boas-vindas no cadastro, lembretes do teste grátis, carrinho abandonado. Você monta os passos em lista no painel (em **Sequências**) ou pela API, e o Couryo cuida do tempo, das condições e das saídas.

**Sem cobrança por contato.** Os e-mails das sequências contam na cota do plano e mais nada.

## Gatilhos

- **Evento:** o contato entra quando chega um [evento](https://couryo.com/docs/contacts.md) com esse nome (`POST /v1/events` ou a ferramenta `track_event` do MCP). Cada contato entra **uma vez** por sequência.
- **Manual:** você coloca o contato pelo painel ou por `POST /v1/sequences/{id}/enrollments`. Um contato que terminou pode entrar de novo assim.
- **Evento de conversão** (opcional): quando ele chega (por exemplo, `order.paid`), o contato sai da sequência como **convertido**.

## Passos

| Passo | O que faz |
|---|---|
| `send` | envia um e-mail: um [template salvo](https://couryo.com/docs/templates.md) (`template_id` + `variables`) ou assunto, HTML e texto próprios, feitos no [editor](https://couryo.com/docs/template-editor.md) |
| `wait` | espera minutos, horas ou dias (`amount`, `unit`); com `until`, depois espera até as HH:mm no fuso da conta ou do contato (`timezone`: `account` ou `contact`) |
| `condition` | confere se o contato abriu ou clicou num e-mail anterior, se um evento aconteceu desde a entrada, ou se um atributo é igual a um valor; `if_true` e `if_false` seguem (`next`), saem (`exit`) ou pulam para um passo mais adiante (`{ "goto": "<id do passo>" }`) |
| `exit` | o contato sai da sequência ali |

Nos e-mails, valem os atributos do contato (`{{nome}}`, também como `{{contact.nome}}`), `{{email}}`, as propriedades do evento que iniciou a sequência (`{{event.plano}}`) e `{{unsubscribe_url}}`.

### Contato sem um atributo

Nem todo contato tem todos os atributos, e isso não derruba a sequência:

- Uma variável com [valor padrão](https://couryo.com/docs/templates.md#valor-padrao-variavelpadrao) usa o padrão: `Oi, {{nome|tudo bem}}!` sai "Oi, tudo bem!" para quem não tem `nome`.
- Uma variável **sem valor e sem padrão sai vazia** e o e-mail é enviado mesmo assim, no conteúdo próprio e no template. A inscrição ganha um aviso em `warning` (por exemplo, "Variáveis sem valor no passo 1: nome"), visível na lista de inscrições do painel, e o contato **continua** na sequência.
- Só um e-mail que fica **vazio de verdade** é erro: assunto vazio depois de preencher as variáveis, ou conteúdo vazio. Aí o contato sai com o motivo `send_failed` e a explicação em `last_error`.
- No construtor, o painel avisa quando um passo usa uma variável sem padrão: "Contatos sem `{{x}}` recebem esse trecho vazio. Use `{{x|padrão}}`."
- O envio pela API (`POST /v1/emails` com `template` ou `variables`) continua estrito: variável sem valor e sem padrão é recusada.

```bash title="Criar uma sequência"
curl https://api.couryo.com/v1/sequences \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding",
    "trigger": { "type": "event", "event": "user.signed_up" },
    "conversion_event": "order.paid",
    "from": "Loja <oi@exemplo.com.br>",
    "steps": [
      { "id": "boas", "type": "send", "template_id": "boas-vindas" },
      { "type": "wait", "amount": 2, "unit": "days", "until": "09:00" },
      { "type": "condition", "check": { "kind": "opened", "step_id": "boas" }, "if_true": "next", "if_false": "exit" },
      { "type": "send", "subject": "Uma dica, {{nome}}", "html": "<p>Oi, {{nome}}!</p>" }
    ]
  }'
```

A sequência nasce como rascunho. Ative com `POST /v1/sequences/{id}/activate`: é preciso um remetente num domínio verificado e pelo menos um e-mail.

## Saídas automáticas

O contato sai da sequência, e nenhum outro e-mail dela sai, quando:

- **descadastra** (link em um clique ou pedido do provedor): motivo `unsubscribed`;
- o endereço entra na **lista de supressão**: `suppressed`;
- há **devolução definitiva**: `bounced`, ou **reclamação de spam**: `complained`;
- chega o **evento de conversão**: o status vira `converted`;
- a sequência é **apagada** (`sequence_deleted`) ou **pausada** com `exit_enrollments: true` (`sequence_paused`). Pausada sem essa opção, ninguém recebe nada e cada contato continua de onde parou quando ela voltar.

Outros motivos: `condition` (a condição mandou sair), `exit_step`, `removed` (você tirou), `contact_deleted` e `send_failed`.

## Regras de envio

- **Horário de silêncio:** por padrão, nenhum e-mail de sequência sai das 21h às 8h no fuso da conta; o e-mail espera o fim do horário. Configurável em `settings.quiet_hours` (ou `null` para desligar).
- **No máximo 1 e-mail de sequência por contato a cada 12 horas**, somando todas as sequências do projeto. Configurável em `settings.min_hours_between_emails`.
- **Fluxo marketing por padrão**, com descadastro em um clique (`List-Unsubscribe`) e um link de descadastro **adicionado no fim do e-mail quando o conteúdo não tem**. O fluxo `transactional` é só para sequências de **onboarding de conta**, que começam por um evento.
- **Tudo passa pelo mesmo caminho do `POST /v1/emails`:** cota do plano, [níveis de confiança](https://couryo.com/docs/limits.md), supressões e checagem de conteúdo. Se um limite do dia ou uma pausa segurar o envio, o Couryo tenta de novo a cada hora por até 3 dias.
- **Sem envio duplicado:** cada passo roda uma vez por contato, mesmo se o servidor reiniciar no meio.

## Planos

| Plano | Sequências |
|---|---|
| Grátis | 1 sequência ativa, com até 3 e-mails |
| Pro | o mesmo do Grátis; com o **complemento Automações**, ilimitadas |
| Escala e Empresa | ilimitadas, incluídas |

Rascunhos não contam. Ativar além do limite devolve `403` [`automations_limit_reached`](https://couryo.com/docs/errors.md#automations_limit_reached), com `upgrade_options` (o complemento e o Escala, com preço). O complemento é ligado e desligado em **Cobrança**, no painel.

## Métricas e inscrições

- `GET /v1/sequences/{id}/metrics` traz, por passo: enviados, entregues, aberturas, cliques, saídas e conversões.
- `GET /v1/sequences/{id}/enrollments` lista quem está ou passou pela sequência (`status`: `active`, `completed`, `exited`, `converted`), com o passo atual, o próximo envio (`next_run_at`), o motivo da saída, o último erro (`last_error`) e o aviso (`warning`), como variáveis que saíram vazias. Filtre por `status` e por parte do e-mail (`q`).

## Endpoints

| Método e caminho | Escopo | O que faz |
|---|---|---|
| `GET` e `POST /v1/sequences` | `read` / `admin` | lista e cria (rascunho) |
| `GET`, `PATCH` e `DELETE /v1/sequences/{id}` | `read` / `admin` | uma sequência, muda (`steps` troca a lista inteira) e apaga |
| `POST /v1/sequences/{id}/activate` | `admin` | ativa ou retoma |
| `POST /v1/sequences/{id}/pause` | `admin` | pausa; `{ "exit_enrollments": true }` também tira todo mundo |
| `POST /v1/sequences/{id}/duplicate` | `admin` | cópia como rascunho |
| `GET /v1/sequences/{id}/metrics` | `read` | métricas por passo |
| `GET` e `POST /v1/sequences/{id}/enrollments` | `read` / `send` | lista e coloca um contato à mão |
| `GET` e `DELETE /v1/sequences/{id}/enrollments/{eid}` | `read` / `admin` | uma inscrição e tirar o contato |

Pelo [MCP](https://couryo.com/docs/mcp.md): `create_sequence` (escopo `admin`, cria como rascunho) e `list_sequences` (`read`).