Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Descadastros e marcas

Os descadastros são guardados por domínio de envio, então cada marca tem a própria lista, a própria página de descadastro e o próprio host de links.

Um descadastro quer dizer “chega de e-mail de marketing”. O BillionSend o registra para o domínio de envio cujo e-mail trouxe o link, então uma equipe com várias marcas nunca mistura as listas. Quem sai de uma marca continua ouvindo das outras.

O e-mail transacional (enviado sem tópico e fora de uma transmissão) nunca é afetado por um descadastro.

Três escopos

Escopo Quem define O que interrompe
Domínio O destinatário, com o link de descadastro ou o botão de um clique do cliente de e-mail O e-mail de marketing do domínio que enviou aquele e-mail
Equipe inteira Você, ao definir unsubscribed como true em um contato (API, painel ou importação de CSV) O e-mail de marketing de todos os domínios da sua equipe
Tópico O destinatário, na página de descadastro Os e-mails enviados com aquele tópico

O descadastro feito pelo próprio destinatário nunca altera o indicador unsubscribed do contato. Ele é guardado como um registro do domínio, identificado pelo endereço de e-mail, então sobrevive a excluir e reimportar o contato.

Transmissões e envios por tópico pulam o destinatário que saiu do domínio de envio, da equipe inteira ou do tópico. Um e-mail avulso interrompido assim termina suppressed com o motivo domain_unsubscribed, contact_unsubscribed ou topic_unsubscribed.

Descadastros não são supressões. A lista de supressão guarda os endereços que deram bounce, reclamaram ou que você bloqueou, e interrompe todo e-mail, inclusive o transacional. Um descadastro interrompe só o e-mail de marketing.

A página de descadastro

Toda transmissão e todo e-mail de tópico leva cabeçalhos List-Unsubscribe de um clique (RFC 8058) e um link para uma página de descadastro hospedada. Coloque {{{UNSUBSCRIBE_URL}}} em um corpo e ele vira o mesmo link para cada destinatário. A página abre no idioma do navegador do destinatário (catorze idiomas, com inglês como alternativa). Além de sair de todo o e-mail de marketing do domínio, o destinatário pode ligar e desligar tópicos individuais.

Quem clicou por engano pode apertar Inscrever-me de novo na página de confirmação. Isso desfaz só aquilo de que aquele link o descadastrou. Um scanner de e-mail que abre o link nunca reinscreve ninguém. Quando você mesmo define unsubscribed: true, a página não tem o botão de reinscrição.

Cada domínio tem o próprio visual

A página tem a cara do domínio que enviou o e-mail. Cada domínio pode definir:

  • um nome de marca, um logo e o arredondamento dos cantos do logo,
  • as cores de fundo, de texto e de destaque,
  • o texto acima do botão e o texto mostrado depois que a escolha é salva,
  • uma URL de redirecionamento a abrir depois do descadastro, no lugar da mensagem na página.

No painel, abra o domínio e use a aba Página de descadastro, que mostra uma prévia. Um campo deixado em branco usa os Padrões da marca da equipe (Configurações) e, depois, o visual simples do BillionSend. A página mostra só o que pertence àquele domínio: nunca cita outro domínio da sua equipe e lista apenas os tópicos vinculados a ele mais os tópicos sem domínio.

Pela API, envie os campos em unsubscribe_page em PATCH /domains/{id}. Um null limpa um campo. O logo é enviado pelo painel e é somente leitura na API.

curl -X PATCH "https://api.billionsend.com/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "unsubscribe_page": {
      "brand_name": "Acme",
      "message": "Que pena que você vai embora. Cancelar a inscrição nos e-mails da Acme?",
      "success_message": "Você saiu da lista da Acme.",
      "accent_color": "#0a7d5a",
      "logo_radius": "rounded"
    }
  }'

Um link feito fora de um e-mail, como o de POST /contacts/{id}/preferences-link, abre a página padrão da equipe, e o descadastro ali tira o contato de todos os domínios.

Seu próprio subdomínio de descadastro

Por padrão, os links abrem em um host do BillionSend. Para abri-los no seu domínio, dê ao domínio um subdomínio de descadastro na aba Configuração dele, ou com unsubscribe_subdomain em POST /domains ou PATCH /domains/{id} (um rótulo como unsubscribe para unsubscribe.seudominio.com; null o limpa). Funciona como o subdomínio de rastreamento, veja Domínios.

  1. Adicione o CNAME que a aba Registros do domínio mostra, apontando para cname.billiondns.com, como somente DNS (nuvem cinza no Cloudflare).
  2. O certificado é emitido automaticamente assim que o CNAME resolve, em geral em minutos. unsubscribe_status passa de pending para active, e unsubscribe_error diz por que isso não acontece.
  3. Daí em diante, os e-mails novos usam o seu host no link e no cabeçalho List-Unsubscribe. Enquanto ele não estiver ativo, e depois de um resultado failed (72 horas sem ativar), usa-se o host compartilhado.

Um link já enviado mantém o host com que foi enviado, então para de funcionar se você remover o CNAME depois. Um subdomínio seu abre só os links do próprio domínio; qualquer outro link responde 404.

Você pode usar o mesmo rótulo para rastreamento e descadastro, mas nomes separados são mais seguros: bloqueadores de anúncios bloqueiam os hosts de rastreamento, e um nome compartilhado derrubaria junto o link de descadastro.

Ler e alterar descadastros

GET /contacts/{id} devolve unsubscribed (o indicador da equipe inteira) e unsubscribed_domains. No painel, a página de um contato lista os dois e permite remover o descadastro de um domínio. A aba Descadastros, em Contatos, lista todos os registros.

# Listar, do mais novo ao mais antigo. domain_id restringe a um domínio.
curl "https://api.billionsend.com/unsubscribes?domain_id=$DOMAIN_ID" \
  -H "Authorization: Bearer bs_..."

# Registrar um descadastro de um domínio (sem domain_id, vale para todos os domínios)
curl -X POST "https://api.billionsend.com/unsubscribes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.org", "domain_id": "'"$DOMAIN_ID"'" }'

# Remover um registro
curl -X DELETE "https://api.billionsend.com/unsubscribes/$UNSUBSCRIBE_ID" \
  -H "Authorization: Bearer bs_..."

Um registro com domain_id e domain ambos null descadastra o endereço de todos os domínios. O POST é idempotente: um registro existente volta sem alteração. As mesmas chamadas existem como as ferramentas MCP list_unsubscribes, add_unsubscribe e delete_unsubscribe.

O que desfaz o quê:

  • PATCH /contacts/{id} com unsubscribed: false desfaz só o descadastro da equipe inteira. Os descadastros de domínios específicos permanecem.
  • DELETE /unsubscribes/{id} remove aquele registro.

Se você excluir um domínio e o adicionar de novo com o mesmo nome, os descadastros dos destinatários voltam a valer.

Quem pode alterá-los

Proprietários, administradores e membros de marketing, e chaves de API de acesso total, podem registrar descadastros. Só proprietários e administradores podem desfazer um. Veja Funções da equipe.

Uma chave de API limitada a um domínio gerencia só os descadastros desse domínio: os outros domínios retornam 403 restricted_api_key.

Importar uma lista de um CSV

Para trazer uma lista de descadastros de outro provedor, abra Contatos → Descadastros no painel e escolha Importar CSV.

email,domain
ada@example.com,
grace@example.com,news.example.org
alan@example.com,*
  • email é obrigatório. domain é opcional. A linha de cabeçalho também é opcional.
  • domain é um dos seus domínios e limita o descadastro ao e-mail dele. * significa todos os domínios. Uma célula vazia usa o Domínio padrão que você escolhe na janela.
  • Uma linha com domínio desconhecido ou endereço inválido é ignorada.

A janela mostra quantos descadastros foram adicionados, quantos já existiam e por que linhas foram ignoradas. Importar o mesmo arquivo duas vezes é seguro.

Eventos

O descadastro de um destinatário dispara contact.unsubscribed com source igual a hosted_page ou one_click, mais domain_id e domain_name (ambos null para um descadastro da equipe inteira). Desfazê-lo dispara contact.resubscribed. Veja Webhooks.

Limites

Free Starter, Pro, Scale
Visual da página de descadastro (logo, cores, fonte, arredondamento do logo) Visual padrão Visual próprio por domínio
Subdomínio de descadastro próprio Não (host compartilhado) Sim
“Powered by BillionSend” na página Exibido Oculto

No Free, definir um subdomínio retorna 403 plan_limit_reached. Você pode salvar um visual para a página, mas os destinatários veem o visual padrão até você fazer upgrade. Depois de um downgrade, os visuais salvos são mantidos e voltam a valer no upgrade, e os subdomínios que você já definiu continuam funcionando.

Esta página foi útil?