# Rastreio de abertura e clique

> Como o Couryo mede aberturas e cliques com pixel e redirecionamento próprios, por que aberturas são estimadas, como desligar por projeto e o que fica guardado (privacidade).

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

O Couryo mede aberturas e cliques com um rastreio **próprio**, no domínio `t.couryo.com`. Os eventos `opened` e `clicked` aparecem na [linha do tempo](https://couryo.com/docs/events.md), nas [métricas das campanhas](https://couryo.com/docs/campaigns.md#metricas) e das [sequências](https://couryo.com/docs/sequences.md), e nos [webhooks](https://couryo.com/docs/webhooks.md).

## Quando está ligado

| Fluxo | Padrão |
|---|---|
| `marketing` (campanhas, sequências, envios com `stream: "marketing"`) | **ligado** |
| `transactional` (senha, login, cobrança) | **desligado** |

Rastreio no transacional não ajuda quem recebe e pode atrapalhar a entrega, por isso fica desligado. Dá para mudar por projeto no painel (**Configurações > Projetos > Rastreio de abertura e clique**) ou pela API:

```bash title="Desligar o pixel de abertura do projeto"
curl -X PATCH https://api.couryo.com/v1/tracking \
  -H "Authorization: Bearer $COURYO_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "opens": false }'
```

`GET /v1/tracking` devolve `{ "opens": true, "clicks": true, "transactional": false }`. `opens` e `clicks` valem para o marketing; `transactional: true` liga também no transacional. A mudança vale para os e-mails aceitos a partir dela (escopo `admin`).

## Como funciona

- **Abertura:** um pixel transparente de 1x1 (`https://t.couryo.com/o/<token>.gif`) vai no fim da parte HTML. Quando o programa de e-mail carrega as imagens, a abertura é registrada.
- **Clique:** cada link `http` ou `https` da parte HTML vira `https://t.couryo.com/c/<token>`, que responde com um redirecionamento 302 para o endereço original, na hora.
- **Ficam como estão:** `mailto:`, `tel:`, âncoras (`#topo`), links relativos, o link de descadastro e o `List-Unsubscribe`, e links com o atributo `data-couryo-track="off"`.
- **O token é assinado** e carrega o id do e-mail, a posição do link e o endereço original. Um token alterado não redireciona para lugar nenhum: o Couryo nunca vira um redirecionador aberto. Os links continuam funcionando mesmo depois que o registro do e-mail sai da retenção do seu plano.
- A parte em texto não é alterada.

## Aberturas são estimadas

Abertura é um sinal fraco, em qualquer provedor:

- **Proteções de privacidade abrem sozinhas.** O Apple Mail (Mail Privacy Protection) baixa as imagens de todos os e-mails antes de a pessoa abrir. Quando dá para reconhecer, o Couryo marca a abertura como automática (`machine: true` no evento e no webhook, `opened_machine` nas métricas da campanha). Ela conta como abertura estimada, mas **não** conta na condição "abriu" das sequências.
- **Proxies de imagem** (como o do Gmail) buscam a imagem quando a pessoa abre: contam como abertura normal.
- **Quem bloqueia imagens** abre sem ser contado.

Para uma decisão firme (por exemplo, numa sequência), prefira o **clique**.

## O que não conta

- **Robôs e verificadores de link** (pré-visualização de chat, antivírus de e-mail corporativo, rastreadores, `curl`) e requisições `HEAD` não viram evento. O redirecionamento funciona igual para eles.
- **Cliques nos primeiros 2 segundos** depois do envio são de filtros de segurança que seguem os links ao receber o e-mail: não contam. Aberturas nesse intervalo contam como automáticas.
- A mesma abertura ou o mesmo clique repetido em poucos segundos conta uma vez.

## Eventos e webhooks

- `opened`: um evento por e-mail (as aberturas automáticas em outro), com `count` somando as repetições.
- `clicked`: um evento por link, com `url` (o endereço original) e `count`.
- O webhook vai na **primeira** abertura e no **primeiro** clique de cada link; as repetições só aumentam `count`.
- Quando o e-mail tem um único destinatário, o evento traz `recipient`.

```json title="Webhook clicked"
{ "type": "clicked", "timestamp": "2026-10-08T18:40:00Z",
  "data": { "email_id": "msg_...", "event_id": "evt_...", "recipient": "ana@gmail.com", "provider": "gmail",
            "url": "https://loja.com.br/colecao", "tags": { "campaign": "cmp_..." }, "metadata": {} } }
```

## Privacidade

- O Couryo guarda **só o fato** (abriu, clicou, em que link, quando, quantas vezes) ligado ao e-mail. Não guarda IP, navegador nem localização de quem abriu.
- Os eventos seguem a retenção de registros do seu plano e são apagados com o e-mail.
- Pela LGPD, informe o rastreio na sua política de privacidade. Para quem prefere não ser medido, desligue as aberturas, os cliques ou os dois no projeto.