Contacts: Search

Count Contacts

Count the contacts that match a where, without bringing them back. Use it to show "1,834 people will receive this" before a send.

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

Needs the contact:read scope on your API key.

Arguments

  • whereobjectoptional

    Same where as Query Contacts. Leave it out to count every contact.

  • maxnumberoptional

    Stop counting at this number, from 1 to 1,000,000. Defaults to 100,000.

Quick start

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/contacts',
  {
    commands: [
      {
        command: "count_contacts",
        args: {
          where: {
            list: "customers",
            sendable: true
          }
        }
      }
    ]
  },
  { 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": "count_contacts",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 14,
      "data": {
        "count": 1790,
        "exact": true
      }
    }
  ]
}

Response fields

  • count

    How many contacts matched.

  • exact

    false when counting stopped early, at max or at the request time limit. The real number is then at least count.

Totals without counting

For totals per status, list or tag, Get Stats is cheaper: it reads counters that are kept up to date on every change, instead of walking the contacts.

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…

  • CMDINTERNAL

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