Contatos

Gerencie sua audiência com a API

Mantenha seus contatos sincronizados com sua aplicação. Importe milhares de uma vez, marque com tags, guarde seus próprios campos, organize em listas e encontre exatamente para quem enviar, tudo por um único endpoint.

  • REST
  • JSON
  • Em lote, até 10.000 por request
  • Listas, tags e campos
  • Segmentos
POSThttps://g.sendcorex.com/v1/contacts

Como funciona

Um contato por email

Um contato pertence à sua conta, não a uma lista. Listas, tags, campos personalizados e status são atributos desse único contato, então nada é duplicado.

Um endpoint para tudo

Importar, marcar com tags, consultar, descadastrar, gerenciar listas e segmentos: toda ação é um comando enviado para POST /v1/contacts. Até 20 comandos por request.

Feito para volume

Cada ação aceita até 500 emails e responde email a email. Uma linha ruim falha sozinha; o resto do lote segue.

Primeiros passos

Quatro passos, e só o primeiro é obrigatório antes do seu primeiro request.

  1. 1

    Crie uma API key

    No dashboard, abra Developers → API Keys e crie uma chave. Dê a ela os scopes de contato de que sua aplicação precisa.

    O token do webmail não funciona aqui. Contatos usam a mesma API key do dashboard que você usa para enviar emails.

  2. 2

    Escolha os scopes

    Integrações somente leitura só precisam de contact:read. Uma sincronização que importa e atualiza precisa de contact:create e contact:update.

  3. 3

    Defina seus campos e listas

    Crie os campos personalizados que você quer guardar (plano, cidade, aniversário…) e as listas para as quais envia. Também dá para fazer isso pelo dashboard.

  4. 4

    Importe e consulte

    Envie seus contatos com Upsert Contacts e depois encontre-os com Query Contacts.

Scopes

Cada comando precisa de um scope na chave. Quando falta um, só aquele comando falha com MISSING_SCOPE; o resto do request roda normalmente.

  • contact:read

    Ler contatos, listas, campos, segmentos, eventos e estatísticas.

  • contact:create

    Criar listas, campos e segmentos. Upsert também precisa dele, para criar contatos novos.

  • contact:update

    Atualizar contatos, tags, status, campos e participação em listas.

  • contact:delete

    Excluir contatos, listas, campos e segmentos.

i

A lista completa, comando a comando, está em Run Commands. Toda página de comando também informa qual scope ele precisa.

O contato

Toda leitura retorna contatos neste formato. Você só grava as partes que importam para você.

{
  "email": "ana@acme.com",
  "domain": "acme.com",
  "first_name": "Ana",
  "last_name": "Costa",
  "phone": null,
  "company": "Acme",
  "locale": "pt-BR",
  "timezone": "America/Sao_Paulo",
  "source": "checkout",
  "status": "subscribed",
  "status_reason": null,
  "status_at": "2026-10-13T06:05:08.323Z",
  "created_at": "2026-10-13T06:05:08.323Z",
  "updated_at": "2026-10-14T09:12:40.118Z",
  "tags": [
    "customer",
    "vip"
  ],
  "lists": {
    "customers": {
      "subscribed": true,
      "sendable": true,
      "added_at": "2026-10-13T06:05:08.323Z",
      "unsubscribed_at": null
    }
  },
  "fields": {
    "plan": "pro",
    "age": 31,
    "city": "São Paulo"
  },
  "stats": {
    "sent_count": 12,
    "open_count": 7,
    "click_count": 2,
    "bounce_count": 0,
    "complaint_count": 0,
    "open_rate": 0.58,
    "click_rate": 0.17,
    "first_open_at": "2026-10-13T08:41:02.000Z",
    "last_open_at": "2026-10-14T21:03:55.000Z",
    "last_click_at": "2026-10-14T21:04:10.000Z",
    "last_sent_at": "2026-10-14T20:58:31.000Z"
  }
}
status

Global. Um contato descadastrado, com bounce, que reclamou ou bloqueado não recebe envios em nenhuma lista.

lists

Participação e inscrição por lista. Alguém pode sair de uma lista e continuar nas outras.

sendable

Inscrito na lista e com status subscribed. É para quem as campanhas enviam.

stats

Envios, aberturas e cliques do tracking. Somente leitura, e você pode filtrar e ordenar por eles.

Seu primeiro request

Importe dois contatos e leia-os de volta, em um único request. Substitua SENDCOREX_API_KEY pela sua API key.

curl -X POST 'https://g.sendcorex.com/v1/contacts' \
  -H "Authorization: $SENDCOREX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "commands": [
    { "command": "upsert_contacts", "args": {
        "tags": ["imported"],
        "contacts": [
          { "email": "ana@acme.com", "first_name": "Ana", "company": "Acme" },
          { "email": "bob@gmail.com", "first_name": "Bob" }
        ]
    } },
    { "command": "query_contacts", "args": { "where": { "tags": { "has": "imported" } } } }
  ]
}'

Você recebe um resultado por comando. O primeiro diz quantos contatos foram created; o segundo os retorna. Rode de novo e nada é gravado: as duas linhas voltam com changed: false. O mesmo request em 8 linguagens está em Upsert Contacts.

Tarefas comuns

Sincronize cadastros da sua aplicação

Faça upsert do contato com list_id a cada cadastro. Reenviar os mesmos dados não grava nada, então também é seguro chamar a cada login.

Upsert Contacts

Respeite um link de descadastro

Descadastre de uma lista com Set List Subscription, ou de tudo com Set Status.

Set List Subscription

Encontre clientes engajados

Consulte por lista, tag e last_open_at, ordenado por open_rate. Salve como segmento para reutilizar.

Query Contacts

Exporte uma lista

Percorra List Members com sendable_only e selecione só os campos de que precisa, 5.000 membros por página.

List Members

Referência completa

Tudo marcado como CMD é um comando enviado por POST /v1/contacts, até 20 por request.