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.

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

Precisa do scope contact:read na sua API key.

i

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

  • whereobjectopcional

    As condições, combinadas com AND. Omita (ou envie {}) para obter todos os contatos. Veja a referência de where abaixo.

  • sortstring | objectopcional

    Um nome de campo ou { "field": "<name>" }. Veja Ordenação abaixo.

    ex.: "open_rate"

  • limitnumberopcional

    Tamanho da página, de 1 a 1000. Padrão: 50.

  • cursorstringopcional

    O next_cursor da página anterior. Envie com o mesmo where e sort.

  • selectstring[]opcional

    Retorna só estas partes de cada contato, por exemplo ["status", "fields.plan", "stats.open_count"]. email sempre 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

  • contacts

    Os contatos encontrados. Contatos inteiros, ou só as partes que você pediu com select.

  • has_more / next_cursor

    Paginação. Enquanto has_more for true, envie next_cursor como cursor com o mesmo where e sort.

  • plan.driver

    O índice que o servidor escolheu varrer, por exemplo tag:vip ou list:customers.

  • plan.examined

    Quantas entradas do índice foram lidas para preencher esta página.

  • plan.keys_only

    true quando a página foi respondida só pelo índice, sem carregar os contatos.

  • plan.ms

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

  • sendable

    true. Com list: inscrito nessa lista e com status subscribed. Sem list: status subscribed.

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

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

    Um 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 campo multi_enum, encontra contatos que têm essa opção.

  • in

    { "plan": { "in": ["pro", "business"] } }. Qualquer um dos valores.

  • gte, gt, lte, lt, eq

    Intervalos em campos number e date. Datas aceitam YYYY-MM-DD ou ISO.

  • contains

    Parte de um valor text, ignorando maiúsculas e acentos.

  • exists

    true para contatos que têm valor, false para 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.

  • email

    De A a Z.

  • fields.<key>

    Crescente. Não disponível para campos multi_enum.

  • sent_count, open_count, click_count, open_rate, click_rate

    Maior primeiro.

  • created_at, last_open_at, last_click_at, last_sent_at

    Mais 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);
i

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.

  • 401INVALID_API_KEY

    A API key não existe, foi revogada ou foi desativada no dashboard.

  • 429RATE_LIMITED

    Mais de 15 requests/s ou 15 simultâneos para o mesmo IP + API key. Espere o número de segundos em Retry-After.

  • CMDMISSING_SCOPE

    A API key não tem o scope que este comando precisa. Os outros comandos do request rodam mesmo assim.

  • CMDINVALID_ARGS

    Um argumento obrigatório está faltando ou é inválido: email, valor de campo, opção de enum, chave do where, id de lista…

  • CMDINVALID_CURSOR

    O cursor está malformado ou pertence a outra consulta ou conta.

  • CMDINTERNAL

    Erro no servidor. O detalhe só é gravado no log do servidor.