Contatos
As pessoas para quem você envia e-mail de marketing, com o estado de inscrição e propriedades personalizadas.
Um contato é um endereço de e-mail na lista da sua equipe. Cada endereço aparece uma só vez (maiúsculas e minúsculas não contam), e você escolhe quem recebe uma transmissão com segmentos e tópicos. Gerencie os contatos no painel, em Contatos, ou pela API.
O que um contato armazena
email: o endereço. Criar um segundo contato com o mesmo endereço retorna409. Um endereço que nunca pode receber e-mail (por exemploexample.com, um nome.testou um domínio sem servidor de e-mail) retorna422.first_name,last_name.unsubscribed: o descadastro da equipe inteira. Enquanto fortrue, o contato não recebe e-mail de marketing de nenhum dos seus domínios. Só você o define; o descadastro feito pelo próprio destinatário nunca o altera.unsubscribed_domains: somente leitura. Os domínios dos quais o contato saiu por um link de descadastro, cada um comdomain_id,nameeunsubscribed_at. O e-mail desses domínios pula o contato, e seus outros domínios ainda chegam a ele. Veja Descadastros.verification_statuseverified_at: somente leitura. O resultado da última verificação completa do contato,nullaté ele ser verificado. Veja Verificação.properties: valores personalizados comoplan: "pro"oucity: "Berlim". Os valores são texto ou número (objetos aninhados e listas retornam422), com no máximo 100 chaves por contato. As propriedades preenchem campos de mesclagem de modelos e filtros de segmentos. OPATCHmescla chave por chave, e um valornullremove a chave.
Criar e consultar
POST /contacts, GET /contacts, GET /contacts/{id}, PATCH /contacts/{id} e DELETE /contacts/{id}. Em {id} você pode usar o id do contato ou o endereço de e-mail dele.
curl -X POST "https://api.billionsend.com/contacts" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"email": "ana@acme.com",
"first_name": "Ana",
"properties": { "plan": "pro" }
}'
Acrescente include=properties,topics a GET /contacts ou GET /segments/{id}/contacts para receber, na mesma resposta, as propriedades e as escolhas de tópicos de cada contato. POST /contacts/batch/get lê até 1.000 contatos por id ou e-mail em uma chamada, na ordem do pedido; endereços sem correspondência aparecem em missing.
PATCH /contacts/{id}/topics define as escolhas de tópicos de um contato, e GET /contacts/{id}/topics as devolve com os padrões dos tópicos aplicados.
POST /contacts/{id}/preferences-link devolve um link para a página de preferências do contato, para você abri-la a partir de uma tela de configurações do seu produto. O link não expira e permite a quem o tem alterar as escolhas daquele contato, então entregue-o só ao próprio contato. Ele abre a página padrão da equipe e descadastra o contato de todos os domínios.
Criação em lote
POST /contacts/batch recebe de 1 a 1.000 contatos em uma requisição e os grava juntos.
on_conflict define o que acontece quando um endereço já existe ou se repete no lote:
error(padrão): aquele item falha com409(já existe) ou422(repetido).skip: o contato existente fica como está.upsert: o item é mesclado ao contato existente. Nomes só quando você os envia, propriedades chave por chave, segmentos acrescentados, tópicos atualizados.
Um lote nunca reinscreve ninguém: unsubscribed: false em um contato que já está descadastrado é ignorado. Para isso, use PATCH /contacts/{id}.
O cabeçalho x-batch-validation escolhe strict (padrão: um item inválido rejeita o lote todo) ou permissive (os itens válidos são gravados e as falhas vêm em errors).
curl -X POST "https://api.billionsend.com/contacts/batch?on_conflict=upsert" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-H "x-batch-validation: permissive" \
-d '[{ "email": "ana@acme.com", "properties": { "plan": "pro" } }, { "email": "not-an-address" }]'
{
"data": [{ "object": "contact", "index": 0, "id": "9b2f…", "status": "updated" }],
"counts": { "created": 0, "updated": 1, "skipped": 0, "failed": 1 },
"errors": [{ "index": 1, "statusCode": 422, "name": "validation_error", "message": "email: Invalid email address" }]
}
Exclusão em lote
POST /contacts/batch/remove exclui até 1.000 contatos por ids ou por emails (um dos dois) e devolve os que excluiu. Acrescente erase: true para também remover cada endereço do histórico de e-mails, dos payloads de eventos e dos logs da API. DELETE /contacts/{id}?erase=true faz o mesmo para um contato.
Importação e exportação em CSV
No painel, Contatos → Contatos importa um CSV e exporta a visão atual (inclusive com filtro de segmento, tópico ou domínio) de volta para CSV. A exportação tem uma coluna unsubscribed e uma coluna unsubscribed_domains (* significa a equipe inteira). Linhas com um endereço que nunca pode receber e-mail são ignoradas. Em um plano pago, a janela de importação também pode verificar os novos endereços; veja Verificação.
Eventos
Cada alteração publica um evento de webhook: contact.created, contact.updated, contact.deleted, contact.unsubscribed, contact.resubscribed, contact.topic_opt_in e contact.topic_opt_out.
Limites
| Free | Starter, Pro, Scale | |
|---|---|---|
| Contatos por equipe | 1.000 | Sem limite |
Acima do limite, criar um contato retorna 403 plan_limit_reached. Os contatos existentes continuam podendo ser atualizados.