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

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 retorna 409. Um endereço que nunca pode receber e-mail (por exemplo example.com, um nome .test ou um domínio sem servidor de e-mail) retorna 422.
  • first_name, last_name.
  • unsubscribed: o descadastro da equipe inteira. Enquanto for true, 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 com domain_id, name e unsubscribed_at. O e-mail desses domínios pula o contato, e seus outros domínios ainda chegam a ele. Veja Descadastros.
  • verification_status e verified_at: somente leitura. O resultado da última verificação completa do contato, null até ele ser verificado. Veja Verificação.
  • properties: valores personalizados como plan: "pro" ou city: "Berlim". Os valores são texto ou número (objetos aninhados e listas retornam 422), com no máximo 100 chaves por contato. As propriedades preenchem campos de mesclagem de modelos e filtros de segmentos. O PATCH mescla chave por chave, e um valor null remove 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 com 409 (já existe) ou 422 (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.

Esta página foi útil?