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.

POSThttps://g.sendcorex.com/v1/contactscommand: query_contacts
i

Necesita el scope contact:read en tu API key.

i

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

  • whereobjectopcional

    Las condiciones, combinadas con AND. Omítelo (o envía {}) para obtener todos los contactos. Consulta la referencia de where más abajo.

  • sortstring | objectopcional

    Un nombre de campo o { "field": "<name>" }. Consulta Ordenación más abajo.

    p. ej. "open_rate"

  • limitnumberopcional

    Tamaño de página, de 1 a 1000. Por defecto, 50.

  • cursorstringopcional

    El next_cursor de la página anterior. Envíalo con el mismo where y sort.

  • selectstring[]opcional

    Devuelve solo estas partes de cada contacto, por ejemplo ["status", "fields.plan", "stats.open_count"]. email siempre 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

  • contacts

    Los contactos encontrados. Contactos completos, o solo las partes que pediste con select.

  • has_more / next_cursor

    Paginación. Mientras has_more sea true, envía next_cursor como cursor con el mismo where y sort.

  • plan.driver

    El índice que el servidor eligió recorrer, por ejemplo tag:vip o list:customers.

  • plan.examined

    Cuántas entradas del índice se leyeron para llenar esta página.

  • plan.keys_only

    true cuando la página se respondió solo desde el índice, sin cargar los contactos.

  • plan.ms

    Tiempo 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.

  • sendable

    true. Con list: suscrito a esa lista y con estado subscribed. Sin list: estado subscribed.

  • 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_rate

    Un 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_clicked

    Un 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 campo multi_enum, encuentra contactos que tienen esa opción.

  • in

    { "plan": { "in": ["pro", "business"] } }. Cualquiera de los valores.

  • gte, gt, lte, lt, eq

    Rangos en campos number y date. Las fechas aceptan YYYY-MM-DD o ISO.

  • contains

    Parte de un valor text, ignorando mayúsculas y acentos.

  • exists

    true para contactos que tienen un valor, false para 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.

  • email

    De la A a la Z.

  • fields.<key>

    Ascendente. No disponible para campos multi_enum.

  • sent_count, open_count, click_count, open_rate, click_rate

    De mayor a menor.

  • created_at, last_open_at, last_click_at, last_sent_at

    Má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);
i

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.

  • 401INVALID_API_KEY

    La API key no existe, se revocó o se desactivó en el dashboard.

  • 429RATE_LIMITED

    Más de 15 peticiones/s o 15 simultáneas para la misma IP + API key. Espera los segundos indicados en Retry-After.

  • CMDMISSING_SCOPE

    La API key no tiene el scope que necesita este comando. Los demás comandos de la petición se ejecutan igualmente.

  • CMDINVALID_ARGS

    Falta un argumento obligatorio o no es válido: email, valor de campo, opción de enum, clave del where, id de lista…

  • CMDINVALID_CURSOR

    El cursor tiene un formato incorrecto o pertenece a otra consulta o cuenta.

  • CMDINTERNAL

    Error del servidor. El detalle solo se escribe en el log del servidor.