Contatos: busca
Consultar contatos
Encontre contatos com qualquer combinação de lista, status, tags, campos personalizados, engajamento e datas. Você descreve quem quer; o servidor escolhe o índice.
https://g.sendcorex.com/v1/contactscommand: query_contactsPrecisa do scope contact:read na sua API key.
O servidor mede cada condição indexada do where, varre a mais seletiva e confere cada contato contra o where inteiro. Você nunca escolhe um índice.
Argumentos
whereobjectopcionalAs condições, combinadas com AND. Omita (ou envie
{}) para obter todos os contatos. Veja a referência dewhereabaixo.sortstring | objectopcionalUm nome de campo ou
{ "field": "<name>" }. Veja Ordenação abaixo.ex.:
"open_rate"limitnumberopcionalTamanho da página, de 1 a 1000. Padrão: 50.
cursorstringopcionalO
next_cursorda página anterior. Envie com o mesmowhereesort.selectstring[]opcionalRetorna só estas partes de cada contato, por exemplo
["status", "fields.plan", "stats.open_count"].emailsempre volta. Sem isso, você recebe o contato inteiro.
Início rápido
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/contacts',
{
commands: [
{
command: "query_contacts",
args: {
where: {
list: "customers",
sendable: true,
tags: {
has: "vip",
none: [
"churn"
]
},
fields: {
plan: {
in: [
"pro",
"business"
]
},
age: {
gte: 25,
lte: 40
}
},
last_open_at: {
within_days: 30
}
},
sort: "open_rate",
limit: 100
}
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);Resposta
{
"type": "SUCCESS",
"results": [
{
"command": "query_contacts",
"id": "0",
"type": "SUCCESS",
"took_ms": 14,
"data": {
"contacts": [
{
"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"
}
}
],
"has_more": true,
"next_cursor": "eyJkIjoidGFnOnZpcCJ9",
"plan": {
"driver": "tag:vip",
"examined": 412,
"keys_only": false,
"ms": {
"scan": 4,
"fetch": 9,
"filter": 1,
"total": 14
}
}
}
}
]
}Campos da resposta
contactsOs contatos encontrados. Contatos inteiros, ou só as partes que você pediu com
select.has_more / next_cursorPaginação. Enquanto
has_morefortrue, envienext_cursorcomocursorcom o mesmowhereesort.plan.driverO índice que o servidor escolheu varrer, por exemplo
tag:vipoulist:customers.plan.examinedQuantas entradas do índice foram lidas para preencher esta página.
plan.keys_onlytruequando a página foi respondida só pelo índice, sem carregar os contatos.plan.msTempo gasto varrendo, buscando, filtrando e no total, em milissegundos.
O objeto where
Toda chave é opcional e todas precisam corresponder. Texto, opções de enum e tags ignoram maiúsculas e acentos.
email"ana@acme.com". Lê esse contato diretamente.search"jo sil". Cada palavra precisa ser o começo de uma palavra do nome, sobrenome, empresa ou email.status"subscribed", uma lista como["bounced", "complained"],{ "in": [...] }ou{ "not": "subscribed" }.list"customers", ou{ "in": ["a", "b"] }para membros de qualquer uma delas.sendabletrue. Comlist: inscrito nessa lista e com statussubscribed. Semlist: statussubscribed.tags{ "has": "vip" },{ "all": [...] },{ "any": [...] },{ "none": [...] }. Podem ser combinados.domain"gmail.com"ou{ "in": [...] }.fields{ "plan": "pro" },{ "age": { "gte": 25 } },{ "plan": { "in": [...] } },{ "city": { "contains": "paul" } },{ "company": { "exists": true } }. O campo precisa existir.sent_count, open_count, click_count, bounce_count, complaint_count, open_rate, click_rateUm número, ou
{ "gte", "gt", "lte", "lt", "eq" }. As taxas vão de 0 a 1.created_at, first_open_at, last_open_at, last_click_at, last_sent_at{ "within_days": 30 },{ "after": "2026-01-01" },{ "before": "..." },{ "never": true }ou{ "exists": true }.campaign_opened, campaign_clickedUm id de campanha. Contatos que abriram ou clicaram nessa campanha.
Uma chave desconhecida, ou um campo que não existe, faz o comando falhar com INVALID_ARGS em vez de silenciosamente não encontrar nada.
Operadores para campos personalizados
Cada campo personalizado tem seu próprio índice, então esses filtros continuam rápidos em listas grandes.
Igual{ "plan": "pro" }. Valores de texto e enum ignoram maiúsculas e acentos. Em um campomulti_enum, encontra contatos que têm essa opção.in{ "plan": { "in": ["pro", "business"] } }. Qualquer um dos valores.gte, gt, lte, lt, eqIntervalos em campos
numberedate. Datas aceitamYYYY-MM-DDou ISO.containsParte de um valor
text, ignorando maiúsculas e acentos.existstruepara contatos que têm valor,falsepara os que não têm.
Ordenação
Cada campo de ordenação tem uma direção fixa. Ordenar por um campo personalizado ou por uma data só retorna contatos que têm valor: last_open_at retorna só quem abriu ao menos uma vez.
emailDe A a Z.
fields.<key>Crescente. Não disponível para campos
multi_enum.sent_count, open_count, click_count, open_rate, click_rateMaior primeiro.
created_at, last_open_at, last_click_at, last_sent_atMais recente primeiro.
Paginação
Cada chamada lê no máximo 20.000 entradas do índice. Quando atinge esse teto antes de encher a página, retorna menos contatos (às vezes nenhum) com has_more: true. Continue enquanto has_more for true; não pare em uma página vazia.
Node.js
const where = { list: 'customers', sendable: true };
const emails = [];
let cursor;
do {
const [result] = await call({
command: 'query_contacts',
args: { where, select: ['email'], limit: 1000, ...(cursor ? { cursor } : {}) },
});
emails.push(...result.data.contacts.map((c) => c.email));
cursor = result.data.has_more ? result.data.next_cursor : null;
} while (cursor);call é qualquer helper que faz POST de { commands: [...] } para /v1/contacts e retorna results, como em Run Commands.
Mais exemplos
Corpo do request
{
"commands": [
{
"command": "query_contacts",
"id": "inactive",
"args": {
"where": {
"list": "customers",
"last_open_at": {
"never": true
},
"created_at": {
"before": "2026-07-01"
}
}
}
},
{
"command": "query_contacts",
"id": "bounced",
"args": {
"where": {
"status": [
"bounced",
"complained"
]
},
"select": [
"status",
"status_reason"
]
}
},
{
"command": "query_contacts",
"id": "search",
"args": {
"where": {
"search": "ana acme"
},
"limit": 10
}
}
]
}Erros
Erros no nível HTTP retornam type, code e message. Erros marcados com CMD voltam dentro do resultado do comando, com HTTP 200.
- 401
INVALID_API_KEYA API key não existe, foi revogada ou foi desativada no dashboard.
- 429
RATE_LIMITEDMais de 15 requests/s ou 15 simultâneos para o mesmo IP + API key. Espere o número de segundos em Retry-After.
- CMD
MISSING_SCOPEA API key não tem o scope que este comando precisa. Os outros comandos do request rodam mesmo assim.
- CMD
INVALID_ARGSUm argumento obrigatório está faltando ou é inválido: email, valor de campo, opção de enum, chave do where, id de lista…
- CMD
INVALID_CURSORO cursor está malformado ou pertence a outra consulta ou conta.
- CMD
INTERNALErro no servidor. O detalhe só é gravado no log do servidor.