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
https://g.sendcorex.com/v1/contactsComo 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
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
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
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
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:readLer contatos, listas, campos, segmentos, eventos e estatísticas.
contact:createCriar listas, campos e segmentos. Upsert também precisa dele, para criar contatos novos.
contact:updateAtualizar contatos, tags, status, campos e participação em listas.
contact:deleteExcluir contatos, listas, campos e segmentos.
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"
}
}statusGlobal. Um contato descadastrado, com bounce, que reclamou ou bloqueado não recebe envios em nenhuma lista.
listsParticipação e inscrição por lista. Alguém pode sair de uma lista e continuar nas outras.
sendableInscrito na lista e com status subscribed. É para quem as campanhas enviam.
statsEnvios, 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 ContactsRespeite um link de descadastro
Descadastre de uma lista com Set List Subscription, ou de tudo com Set Status.
Set List SubscriptionEncontre clientes engajados
Consulte por lista, tag e last_open_at, ordenado por open_rate. Salve como segmento para reutilizar.
Query ContactsExporte uma lista
Percorra List Members com sendable_only e selecione só os campos de que precisa, 5.000 membros por página.
List MembersReferência completa
Tudo marcado como CMD é um comando enviado por POST /v1/contacts, até 20 por request.
Rotas
1Contatos
4Busca
2Tags, status e campos
5Listas
9- CMDList ListsTodas as listas, com contadores
- CMDGet ListUma lista e seus contadores
- CMDCreate ListSeu próprio id ou um gerado
- CMDUpdate ListNome, descrição, dados personalizados
- CMDDelete ListOs contatos são mantidos
- CMDList MembersPercorre uma lista, só sendable
- CMDAdd To ListsEntra em uma ou mais listas
- CMDRemove From ListsSai de uma ou mais listas
- CMDSet List SubscriptionDescadastra de uma lista