Sequências

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

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

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, 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#

Rascunhos não contam. Ativar além do limite devolve 403 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#

Pelo MCP: create_sequence (escopo admin, cria como rascunho) e list_sequences (read).