Contactos: búsqueda
Consultar contactos
Encuentra contactos con cualquier combinación de lista, estado, etiquetas, campos personalizados, interacción y fechas. Tú describes a quién quieres; el servidor elige el índice.
https://g.sendcorex.com/v1/contactscommand: query_contactsNecesita el scope contact:read en tu API key.
El servidor mide cada condición indexada del where, recorre la más selectiva y comprueba cada contacto contra todo el where. Nunca eliges un índice.
Argumentos
whereobjectopcionalLas condiciones, combinadas con AND. Omítelo (o envía
{}) para obtener todos los contactos. Consulta la referencia dewheremás abajo.sortstring | objectopcionalUn nombre de campo o
{ "field": "<name>" }. Consulta Ordenación más abajo.p. ej.
"open_rate"limitnumberopcionalTamaño de página, de 1 a 1000. Por defecto, 50.
cursorstringopcionalEl
next_cursorde la página anterior. Envíalo con el mismowhereysort.selectstring[]opcionalDevuelve solo estas partes de cada contacto, por ejemplo
["status", "fields.plan", "stats.open_count"].emailsiempre vuelve. Sin él, recibes el contacto completo.
Inicio 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);Respuesta
{
"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 de la respuesta
contactsLos contactos encontrados. Contactos completos, o solo las partes que pediste con
select.has_more / next_cursorPaginación. Mientras
has_moreseatrue, envíanext_cursorcomocursorcon el mismowhereysort.plan.driverEl índice que el servidor eligió recorrer, por ejemplo
tag:vipolist:customers.plan.examinedCuántas entradas del índice se leyeron para llenar esta página.
plan.keys_onlytruecuando la página se respondió solo desde el índice, sin cargar los contactos.plan.msTiempo dedicado a recorrer, cargar, filtrar y en total, en milisegundos.
El objeto where
Todas las claves son opcionales y todas deben cumplirse. El texto, las opciones de enum y las etiquetas ignoran mayúsculas y acentos.
email"ana@acme.com". Lee ese contacto directamente.search"jo sil". Cada palabra debe ser el inicio de una palabra del nombre, apellido, empresa o email.status"subscribed", una lista como["bounced", "complained"],{ "in": [...] }o{ "not": "subscribed" }.list"customers", o{ "in": ["a", "b"] }para miembros de cualquiera de ellas.sendabletrue. Conlist: suscrito a esa lista y con estadosubscribed. Sinlist: estadosubscribed.tags{ "has": "vip" },{ "all": [...] },{ "any": [...] },{ "none": [...] }. Se pueden combinar.domain"gmail.com"o{ "in": [...] }.fields{ "plan": "pro" },{ "age": { "gte": 25 } },{ "plan": { "in": [...] } },{ "city": { "contains": "paul" } },{ "company": { "exists": true } }. El campo debe existir.sent_count, open_count, click_count, bounce_count, complaint_count, open_rate, click_rateUn número, o
{ "gte", "gt", "lte", "lt", "eq" }. Las tasas van 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 }o{ "exists": true }.campaign_opened, campaign_clickedUn id de campaña. Contactos que abrieron o hicieron clic en esa campaña.
Una clave desconocida, o un campo que no existe, hace fallar el comando con INVALID_ARGS en lugar de no encontrar nada en silencio.
Operadores para campos personalizados
Cada campo personalizado tiene su propio índice, así que estos filtros siguen siendo rápidos en listas grandes.
Igual{ "plan": "pro" }. Los valores de texto y enum ignoran mayúsculas y acentos. En un campomulti_enum, encuentra contactos que tienen esa opción.in{ "plan": { "in": ["pro", "business"] } }. Cualquiera de los valores.gte, gt, lte, lt, eqRangos en campos
numberydate. Las fechas aceptanYYYY-MM-DDo ISO.containsParte de un valor
text, ignorando mayúsculas y acentos.existstruepara contactos que tienen un valor,falsepara los que no.
Ordenación
Cada campo de ordenación tiene una dirección fija. Ordenar por un campo personalizado o por una fecha solo devuelve contactos que tienen valor: last_open_at devuelve solo a quienes abrieron al menos una vez.
emailDe la A a la Z.
fields.<key>Ascendente. No disponible para campos
multi_enum.sent_count, open_count, click_count, open_rate, click_rateDe mayor a menor.
created_at, last_open_at, last_click_at, last_sent_atMás reciente primero.
Paginación
Cada llamada lee como máximo 20.000 entradas del índice. Cuando llega a ese tope antes de llenar la página, devuelve menos contactos (a veces ninguno) con has_more: true. Sigue mientras has_more sea true; no te detengas en una página vacía.
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 es cualquier helper que hace POST de { commands: [...] } a /v1/contacts y devuelve results, como en Run Commands.
Más ejemplos
Cuerpo de la petición
{
"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
}
}
]
}Errores
Los errores a nivel HTTP devuelven type, code y message. Los errores marcados con CMD vuelven dentro del resultado del comando, con HTTP 200.
- 401
INVALID_API_KEYLa API key no existe, se revocó o se desactivó en el dashboard.
- 429
RATE_LIMITEDMás de 15 peticiones/s o 15 simultáneas para la misma IP + API key. Espera los segundos indicados en Retry-After.
- CMD
MISSING_SCOPELa API key no tiene el scope que necesita este comando. Los demás comandos de la petición se ejecutan igualmente.
- CMD
INVALID_ARGSFalta un argumento obligatorio o no es válido: email, valor de campo, opción de enum, clave del where, id de lista…
- CMD
INVALID_CURSOREl cursor tiene un formato incorrecto o pertenece a otra consulta o cuenta.
- CMD
INTERNALError del servidor. El detalle solo se escribe en el log del servidor.