Contacts: Search

Query Contacts

Find contacts with any mix of list, status, tags, custom fields, engagement and dates. You describe who you want; the server picks the index.

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

Needs the contact:read scope on your API key.

i

The server measures every indexed condition in where, scans the most selective one and checks each contact against the whole where. You never choose an index.

Arguments

  • whereobjectoptional

    The conditions, combined with AND. Leave it out (or send {}) to get every contact. See the where reference below.

  • sortstring | objectoptional

    A field name or { "field": "<name>" }. See Sorting below.

    e.g. "open_rate"

  • limitnumberoptional

    Page size, from 1 to 1000. Defaults to 50.

  • cursorstringoptional

    The next_cursor of the previous page. Send it with the same where and sort.

  • selectstring[]optional

    Return only these parts of each contact, for example ["status", "fields.plan", "stats.open_count"]. email always comes back. Without it you get the whole contact.

Quick start

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

Response

{
  "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
          }
        }
      }
    }
  ]
}

Response fields

  • contacts

    The matching contacts. Whole contacts, or only the parts you asked for with select.

  • has_more / next_cursor

    Pagination. While has_more is true, send next_cursor as cursor with the same where and sort.

  • plan.driver

    The index the server picked to scan, for example tag:vip or list:customers.

  • plan.examined

    How many index entries were read to fill this page.

  • plan.keys_only

    true when the page was answered from the index alone, without loading the contacts.

  • plan.ms

    Time spent scanning, fetching, filtering and in total, in milliseconds.

The where object

Every key is optional and they all have to match. Text, enum options and tags ignore case and accents.

  • email

    "ana@acme.com". Reads that one contact directly.

  • search

    "jo sil". Every word must be the start of a first name, last name, company or email word.

  • status

    "subscribed", a list like ["bounced", "complained"], { "in": [...] } or { "not": "subscribed" }.

  • list

    "customers", or { "in": ["a", "b"] } for members of any of them.

  • sendable

    true. With list: subscribed to that list and with status subscribed. Without list: status subscribed.

  • tags

    { "has": "vip" }, { "all": [...] }, { "any": [...] }, { "none": [...] }. They can be combined.

  • domain

    "gmail.com" or { "in": [...] }.

  • fields

    { "plan": "pro" }, { "age": { "gte": 25 } }, { "plan": { "in": [...] } }, { "city": { "contains": "paul" } }, { "company": { "exists": true } }. The field must exist.

  • sent_count, open_count, click_count, bounce_count, complaint_count, open_rate, click_rate

    A number, or { "gte", "gt", "lte", "lt", "eq" }. Rates go from 0 to 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 } or { "exists": true }.

  • campaign_opened, campaign_clicked

    A campaign id. Contacts who opened or clicked that campaign.

!

An unknown key, or a field that does not exist, fails the command with INVALID_ARGS instead of silently matching nothing.

Operators for custom fields

Every custom field is indexed on its own, so these filters stay fast on large lists.

  • Equal

    { "plan": "pro" }. Text and enum values ignore case and accents. On a multi_enum field, it matches contacts that have that option.

  • in

    { "plan": { "in": ["pro", "business"] } }. Any of the values.

  • gte, gt, lte, lt, eq

    Ranges on number and date fields. Dates accept YYYY-MM-DD or ISO.

  • contains

    Part of a text value, ignoring case and accents.

  • exists

    true for contacts that have a value, false for those that do not.

Sorting

Each sort field has a fixed direction. Sorting by a custom field or a date only returns contacts that have a value: last_open_at returns only people who opened at least once.

  • email

    A to Z.

  • fields.<key>

    Ascending. Not available for multi_enum fields.

  • sent_count, open_count, click_count, open_rate, click_rate

    Highest first.

  • created_at, last_open_at, last_click_at, last_sent_at

    Most recent first.

Pagination

Each call reads at most 20,000 index entries. When it hits that ceiling before filling the page, it returns fewer contacts (sometimes none) with has_more: true. Keep going while has_more is true; do not stop on an empty page.

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 is any helper that posts { commands: [...] } to /v1/contacts and returns results, as in Run Commands.

More examples

Request body

{
  "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
      }
    }
  ]
}

Errors

HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.

  • 401INVALID_API_KEY

    The API key does not exist, was revoked or was disabled in the dashboard.

  • 429RATE_LIMITED

    More than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.

  • CMDMISSING_SCOPE

    The API key does not have the scope this command needs. The other commands in the request still run.

  • CMDINVALID_ARGS

    A required argument is missing or invalid: email, field value, enum option, where key, list id…

  • CMDINVALID_CURSOR

    The cursor is malformed or belongs to another query or account.

  • CMDINTERNAL

    Server error. The detail is only written to the server log.