Tópicos
Categorias de inscrição que deixam o destinatário escolher o que recebe.
Um tópico é uma categoria de e-mail, como “Novidades do produto”, “Newsletter” ou “Promoções”. O destinatário pode sair de um tópico e continuar inscrito nos outros. Gerencie os tópicos no painel, em Contatos → Tópicos, ou pela API.
Cada tópico tem um default_subscription, definido na criação e que não muda depois:
opt_in: todo contato está inscrito, a menos que opte por sair.opt_out: o contato só está inscrito depois de optar por entrar.
Um tópico também tem uma visibility. Um tópico public aparece na página de descadastro, e um private só aparece pelo link próprio dele.
Como os tópicos se aplicam
- Transmissões. Uma transmissão pode ter um tópico como alvo. Ela vai para os contatos inscritos naquele tópico (a escolha do próprio contato ou o padrão do tópico). Contatos descadastrados na equipe inteira, ou que saíram do domínio de envio, ficam sempre de fora.
- E-mails avulsos. Envie um e-mail com
topic_ide ele respeita aquele tópico. Se todos os endereços detotiverem optado por sair, o envio retorna422 all_recipients_suppressed. - Página de descadastro. A página lista os tópicos públicos, então o destinatário pode desativar um deles ou sair de todo o e-mail de marketing daquele domínio. O e-mail enviado sem
topic_ide fora de uma transmissão nunca é afetado. Veja Descadastros.
Um tópico usado por uma transmissão, ou por um e-mail ainda à espera de envio, não pode ser excluído: a chamada retorna 409 conflict até que eles tenham saído ou sido cancelados.
curl -X POST "https://api.billionsend.com/topics" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{ "name": "Novidades do produto", "default_subscription": "opt_in" }'
Você define as escolhas de um contato com PATCH /contacts/{id}/topics, enviando entradas como { "id": "<topic-id>", "subscription": "opt_in" }. GET /contacts/{id}/topics lista todos os tópicos com a subscription do contato e um indicador explicit (falso quando é o padrão do tópico).
Um tópico por marca
Se cada um dos seus domínios é uma marca própria, vincule o tópico ao domínio a que ele pertence definindo domain_id, ao criá-lo ou depois com PATCH /topics/{id}, ou escolhendo o domínio no painel.
- Um tópico vinculado aparece só na página de descadastro desse domínio. A página de nenhum outro domínio mostra o nome dele.
- Um envio com esse
topic_iddeve sair desse domínio. De qualquer outro,POST /emailse as chamadas de transmissão retornam422. - Um tópico sem domínio aparece na página de todos os domínios e pode ser enviado de qualquer um.
"domain_id": nulltorna o tópico vinculado válido para a equipe inteira de novo. - Um domínio não pode ser excluído enquanto houver tópicos vinculados a ele (
409).
Os segmentos podem ser vinculados da mesma forma.
Chaves de API limitadas a um domínio
Uma chave de API limitada a um domínio só cria tópicos vinculados a esse domínio e não pode torná-los válidos para a equipe inteira.