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.
- Adicione o CNAME que a aba Registros do domínio mostra, apontando para
cname.billiondns.com, como somente DNS (nuvem cinza no Cloudflare). - O certificado é emitido automaticamente assim que o CNAME resolve, em geral em minutos.
unsubscribe_statuspassa dependingparaactive, eunsubscribe_errordiz por que isso não acontece. - 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 resultadofailed(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}comunsubscribed: falsedesfaz 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.