Kontak: pencarian

Kueri kontak

Temukan kontak dengan kombinasi apa pun dari list, status, tag, custom field, engagement, dan tanggal. Anda menjelaskan siapa yang dicari; server memilih indeksnya.

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

Membutuhkan scope contact:read pada API key Anda.

i

Server mengukur setiap kondisi terindeks di where, memindai yang paling selektif, dan memeriksa setiap kontak terhadap seluruh where. Anda tidak pernah memilih indeks.

Argumen

  • whereobjectopsional

    Kondisi, digabung dengan AND. Kosongkan (atau kirim {}) untuk mendapatkan semua kontak. Lihat referensi where di bawah.

  • sortstring | objectopsional

    Nama field atau { "field": "<name>" }. Lihat Pengurutan di bawah.

    mis. "open_rate"

  • limitnumberopsional

    Ukuran halaman, dari 1 sampai 1000. Default 50.

  • cursorstringopsional

    next_cursor dari halaman sebelumnya. Kirim dengan where dan sort yang sama.

  • selectstring[]opsional

    Hanya kembalikan bagian ini dari setiap kontak, misalnya ["status", "fields.plan", "stats.open_count"]. email selalu dikembalikan. Tanpanya, Anda mendapatkan kontak lengkap.

Mulai cepat

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

Respons

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

Field respons

  • contacts

    Kontak yang cocok. Kontak lengkap, atau hanya bagian yang Anda minta dengan select.

  • has_more / next_cursor

    Paginasi. Selama has_more bernilai true, kirim next_cursor sebagai cursor dengan where dan sort yang sama.

  • plan.driver

    Indeks yang dipilih server untuk dipindai, misalnya tag:vip atau list:customers.

  • plan.examined

    Jumlah entri indeks yang dibaca untuk mengisi halaman ini.

  • plan.keys_only

    true jika halaman dijawab hanya dari indeks, tanpa memuat kontak.

  • plan.ms

    Waktu untuk memindai, mengambil, memfilter, dan total, dalam milidetik.

Objek where

Setiap key bersifat opsional dan semuanya harus cocok. Teks, opsi enum, dan tag mengabaikan huruf besar/kecil dan aksen.

  • email

    "ana@acme.com". Membaca kontak itu secara langsung.

  • search

    "jo sil". Setiap kata harus merupakan awal dari kata pada nama depan, nama belakang, perusahaan, atau email.

  • status

    "subscribed", list seperti ["bounced", "complained"], { "in": [...] }, atau { "not": "subscribed" }.

  • list

    "customers", atau { "in": ["a", "b"] } untuk anggota salah satunya.

  • sendable

    true. Dengan list: berlangganan list itu dan berstatus subscribed. Tanpa list: berstatus subscribed.

  • tags

    { "has": "vip" }, { "all": [...] }, { "any": [...] }, { "none": [...] }. Dapat dikombinasikan.

  • domain

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

  • fields

    { "plan": "pro" }, { "age": { "gte": 25 } }, { "plan": { "in": [...] } }, { "city": { "contains": "paul" } }, { "company": { "exists": true } }. Field harus sudah ada.

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

    Angka, atau { "gte", "gt", "lte", "lt", "eq" }. Rate bernilai 0 sampai 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 }, atau { "exists": true }.

  • campaign_opened, campaign_clicked

    Id kampanye. Kontak yang membuka atau mengklik kampanye tersebut.

!

Key yang tidak dikenal, atau field yang tidak ada, membuat perintah gagal dengan INVALID_ARGS alih-alih diam-diam tidak menemukan apa pun.

Operator untuk custom field

Setiap custom field diindeks sendiri, jadi filter ini tetap cepat pada list besar.

  • Sama dengan

    { "plan": "pro" }. Nilai teks dan enum mengabaikan huruf besar/kecil dan aksen. Pada field multi_enum, cocok dengan kontak yang memiliki opsi tersebut.

  • in

    { "plan": { "in": ["pro", "business"] } }. Salah satu dari nilai tersebut.

  • gte, gt, lte, lt, eq

    Rentang pada field number dan date. Tanggal menerima YYYY-MM-DD atau ISO.

  • contains

    Bagian dari nilai text, mengabaikan huruf besar/kecil dan aksen.

  • exists

    true untuk kontak yang memiliki nilai, false untuk yang tidak.

Pengurutan

Setiap field pengurutan memiliki arah tetap. Mengurutkan berdasarkan custom field atau tanggal hanya mengembalikan kontak yang memiliki nilai: last_open_at hanya mengembalikan orang yang pernah membuka setidaknya sekali.

  • email

    A sampai Z.

  • fields.<key>

    Menaik. Tidak tersedia untuk field multi_enum.

  • sent_count, open_count, click_count, open_rate, click_rate

    Tertinggi lebih dulu.

  • created_at, last_open_at, last_click_at, last_sent_at

    Terbaru lebih dulu.

Paginasi

Setiap panggilan membaca maksimal 20.000 entri indeks. Jika mencapai batas itu sebelum halaman penuh, panggilan mengembalikan lebih sedikit kontak (terkadang tidak ada) dengan has_more: true. Lanjutkan selama has_more bernilai true; jangan berhenti di halaman kosong.

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 adalah helper apa pun yang mengirim POST { commands: [...] } ke /v1/contacts dan mengembalikan results, seperti di Run Commands.

Contoh lainnya

Body 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
      }
    }
  ]
}

Error

Error di level HTTP mengembalikan type, code, dan message. Error yang ditandai CMD dikembalikan di dalam hasil perintah, dengan HTTP 200.

  • 401INVALID_API_KEY

    API key tidak ada, sudah dicabut, atau dinonaktifkan di dashboard.

  • 429RATE_LIMITED

    Lebih dari 15 request/detik atau 15 bersamaan untuk IP + API key yang sama. Tunggu sesuai jumlah detik di Retry-After.

  • CMDMISSING_SCOPE

    API key tidak memiliki scope yang dibutuhkan perintah ini. Perintah lain dalam request tetap berjalan.

  • CMDINVALID_ARGS

    Argumen wajib tidak ada atau tidak valid: email, nilai field, opsi enum, key where, id list…

  • CMDINVALID_CURSOR

    Cursor tidak valid atau milik query atau akun lain.

  • CMDINTERNAL

    Error server. Detailnya hanya ditulis ke log server.