unsubscribes

Fluxo público de descadastramento baseado em token mais uma listagem administrativa de todos os registros de descadastramento.

Caminho de origem: libraries/campaign/src/services/campaign-unsubscribe.service.ts

Arquivo do módulo: campaign.module.ts

Introdução

O submódulo Unsubscribes implementa a metade de opt-out da conformidade de e-mail: um token assinado, confirmável em uso único, embutido no placeholder `{{unsubscribeUrl}}` de cada e-mail de campanha enviado, e o fluxo público de landing page que o resolve. O `CampaignUnsubscribeService.generateUnsubscribeToken` é chamado pelo CampaignEmailWorkerService ao montar o conteúdo de cada mensagem, criando uma linha `campaign_unsubscribe` indexada por um token aleatório e vinculada à campanha, ao destinatário e à mensagem para os quais foi gerado, com um `scope` (por padrão `all_campaigns`) que determina a abrangência do eventual opt-out.

O `GET /campaign/unsubscribe/:token` é o endpoint público e não autenticado que a landing page chama para renderizar uma tela de confirmação — ele retorna apenas campos não sensíveis (e-mail, escopo, se já foi processado) e nunca os IDs subjacentes do destinatário ou da campanha. O `POST /campaign/unsubscribe/:token` é a ação de confirmação de fato, também pública, e é totalmente idempotente: chamá-lo novamente após um descadastramento bem-sucedido simplesmente retorna `alreadyUnsubscribed: true` sem efeitos colaterais. Na primeira confirmação, ele faz cinco coisas em sequência: marca o registro de descadastramento como confirmado (armazenando o IP e o user-agent do solicitante), muda o(s) destinatário(s) vinculado(s) para `status: unsubscribed`, marca a mensagem específica (ou qualquer mensagem ainda ativa daquele e-mail naquela campanha) como `unsubscribed`, incrementa o contador `total_unsubscribed` da campanha, grava um evento de campanha `unsubscribed` e — apenas quando o `scope` é `all_campaigns` — adiciona o e-mail à lista global de Suppression com `reason: unsubscribe`, que é o que de fato impede campanhas futuras de enviar e-mail para aquele endereço novamente.

O `GET /campaign/unsubscribes` é a contraparte voltada ao admin: uma simples lista paginada e filtrável por busca de todo registro de descadastramento já gerado, independentemente de ter sido confirmado — útil para auditar quantos destinatários receberam um link de descadastramento versus quantos realmente o usaram.

Endpoints HTTP

3 endpoints

Lista administrativa paginada de todos os registros de descadastramento, confirmados ou não.

Query: page, pageSize, search

Obtém os dados da landing page de descadastramento a partir de um token assinado. Retorna o e-mail, o escopo e o estado de confirmação para a UI de confirmação.

Params: token (string)

Confirma um descadastramento. Idempotente. Registra IP e user-agent, marca o(s) destinatário(s) e a mensagem como descadastrados, incrementa os contadores da campanha e — para o escopo "all_campaigns" — adiciona o e-mail à lista global de supressão.

Params: token (string)