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.
https://g.sendcorex.com/v1/contactscommand: query_contactsMembutuhkan scope contact:read pada API key Anda.
Server mengukur setiap kondisi terindeks di where, memindai yang paling selektif, dan memeriksa setiap kontak terhadap seluruh where. Anda tidak pernah memilih indeks.
Argumen
whereobjectopsionalKondisi, digabung dengan AND. Kosongkan (atau kirim
{}) untuk mendapatkan semua kontak. Lihat referensiwheredi bawah.sortstring | objectopsionalNama field atau
{ "field": "<name>" }. Lihat Pengurutan di bawah.mis.
"open_rate"limitnumberopsionalUkuran halaman, dari 1 sampai 1000. Default 50.
cursorstringopsionalnext_cursordari halaman sebelumnya. Kirim denganwheredansortyang sama.selectstring[]opsionalHanya kembalikan bagian ini dari setiap kontak, misalnya
["status", "fields.plan", "stats.open_count"].emailselalu 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
contactsKontak yang cocok. Kontak lengkap, atau hanya bagian yang Anda minta dengan
select.has_more / next_cursorPaginasi. Selama
has_morebernilaitrue, kirimnext_cursorsebagaicursordenganwheredansortyang sama.plan.driverIndeks yang dipilih server untuk dipindai, misalnya
tag:vipataulist:customers.plan.examinedJumlah entri indeks yang dibaca untuk mengisi halaman ini.
plan.keys_onlytruejika halaman dijawab hanya dari indeks, tanpa memuat kontak.plan.msWaktu 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.sendabletrue. Denganlist: berlangganan list itu dan berstatussubscribed. Tanpalist: berstatussubscribed.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_rateAngka, 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_clickedId 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 fieldmulti_enum, cocok dengan kontak yang memiliki opsi tersebut.in{ "plan": { "in": ["pro", "business"] } }. Salah satu dari nilai tersebut.gte, gt, lte, lt, eqRentang pada field
numberdandate. Tanggal menerimaYYYY-MM-DDatau ISO.containsBagian dari nilai
text, mengabaikan huruf besar/kecil dan aksen.existstrueuntuk kontak yang memiliki nilai,falseuntuk 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.
emailA sampai Z.
fields.<key>Menaik. Tidak tersedia untuk field
multi_enum.sent_count, open_count, click_count, open_rate, click_rateTertinggi lebih dulu.
created_at, last_open_at, last_click_at, last_sent_atTerbaru 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);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.
- 401
INVALID_API_KEYAPI key tidak ada, sudah dicabut, atau dinonaktifkan di dashboard.
- 429
RATE_LIMITEDLebih dari 15 request/detik atau 15 bersamaan untuk IP + API key yang sama. Tunggu sesuai jumlah detik di Retry-After.
- CMD
MISSING_SCOPEAPI key tidak memiliki scope yang dibutuhkan perintah ini. Perintah lain dalam request tetap berjalan.
- CMD
INVALID_ARGSArgumen wajib tidak ada atau tidak valid: email, nilai field, opsi enum, key where, id list…
- CMD
INVALID_CURSORCursor tidak valid atau milik query atau akun lain.
- CMD
INTERNALError server. Detailnya hanya ditulis ke log server.