Kontakte: Suche
Kontakte abfragen
Finden Sie Kontakte mit jeder Kombination aus Liste, Status, Tags, benutzerdefinierten Feldern, Engagement und Daten. Sie beschreiben, wen Sie suchen; der Server wählt den Index.
https://g.sendcorex.com/v1/contactscommand: query_contactsErfordert den Scope contact:read auf Ihrem API Key.
Der Server misst jede indexierte Bedingung im where, durchsucht die selektivste und prüft jeden Kontakt gegen das gesamte where. Sie wählen nie einen Index.
Argumente
whereobjectoptionalDie Bedingungen, mit AND verknüpft. Weglassen (oder
{}senden), um alle Kontakte zu erhalten. Siehe diewhere-Referenz unten.sortstring | objectoptionalEin Feldname oder
{ "field": "<name>" }. Siehe Sortierung unten.z. B.
"open_rate"limitnumberoptionalSeitengröße, von 1 bis 1000. Standard: 50.
cursorstringoptionalDer
next_cursorder vorherigen Seite. Senden Sie ihn mit demselbenwhereundsort.selectstring[]optionalGibt nur diese Teile jedes Kontakts zurück, zum Beispiel
["status", "fields.plan", "stats.open_count"].emailkommt immer zurück. Ohne diesen Parameter erhalten Sie den vollständigen Kontakt.
Schnellstart
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);Antwort
{
"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
}
}
}
}
]
}Antwortfelder
contactsDie passenden Kontakte. Vollständig oder nur die mit
selectangefragten Teile.has_more / next_cursorPaginierung. Solange
has_moretrueist, senden Sienext_cursoralscursormit demselbenwhereundsort.plan.driverDer Index, den der Server zum Durchsuchen gewählt hat, zum Beispiel
tag:vipoderlist:customers.plan.examinedWie viele Indexeinträge gelesen wurden, um diese Seite zu füllen.
plan.keys_onlytrue, wenn die Seite allein aus dem Index beantwortet wurde, ohne die Kontakte zu laden.plan.msZeit für Scannen, Laden, Filtern und insgesamt, in Millisekunden.
Das where-Objekt
Jeder Schlüssel ist optional, und alle müssen zutreffen. Text, Enum-Optionen und Tags ignorieren Groß-/Kleinschreibung und Akzente.
email"ana@acme.com". Liest diesen einen Kontakt direkt.search"jo sil". Jedes Wort muss der Anfang eines Worts in Vorname, Nachname, Firma oder E-Mail sein.status"subscribed", eine Liste wie["bounced", "complained"],{ "in": [...] }oder{ "not": "subscribed" }.list"customers"oder{ "in": ["a", "b"] }für Mitglieder einer davon.sendabletrue. Mitlist: für diese Liste angemeldet und mit Statussubscribed. Ohnelist: Statussubscribed.tags{ "has": "vip" },{ "all": [...] },{ "any": [...] },{ "none": [...] }. Sie lassen sich kombinieren.domain"gmail.com"oder{ "in": [...] }.fields{ "plan": "pro" },{ "age": { "gte": 25 } },{ "plan": { "in": [...] } },{ "city": { "contains": "paul" } },{ "company": { "exists": true } }. Das Feld muss existieren.sent_count, open_count, click_count, bounce_count, complaint_count, open_rate, click_rateEine Zahl oder
{ "gte", "gt", "lte", "lt", "eq" }. Raten gehen von 0 bis 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 }oder{ "exists": true }.campaign_opened, campaign_clickedEine Kampagnen-ID. Kontakte, die diese Kampagne geöffnet oder geklickt haben.
Ein unbekannter Schlüssel oder ein nicht existierendes Feld lässt den Befehl mit INVALID_ARGS fehlschlagen, statt stillschweigend nichts zu finden.
Operatoren für benutzerdefinierte Felder
Jedes benutzerdefinierte Feld wird einzeln indexiert, daher bleiben diese Filter auch bei großen Listen schnell.
Gleich{ "plan": "pro" }. Text- und Enum-Werte ignorieren Groß-/Kleinschreibung und Akzente. Bei einemmulti_enum-Feld passt es auf Kontakte mit dieser Option.in{ "plan": { "in": ["pro", "business"] } }. Einer der Werte.gte, gt, lte, lt, eqBereiche auf
number- unddate-Feldern. Daten akzeptierenYYYY-MM-DDoder ISO.containsTeil eines
text-Werts, ohne Groß-/Kleinschreibung und Akzente.existstruefür Kontakte mit Wert,falsefür Kontakte ohne.
Sortierung
Jedes Sortierfeld hat eine feste Richtung. Sortieren nach einem benutzerdefinierten Feld oder Datum liefert nur Kontakte mit Wert: last_open_at liefert nur Personen, die mindestens einmal geöffnet haben.
emailVon A bis Z.
fields.<key>Aufsteigend. Nicht verfügbar für
multi_enum-Felder.sent_count, open_count, click_count, open_rate, click_rateHöchster Wert zuerst.
created_at, last_open_at, last_click_at, last_sent_atNeueste zuerst.
Paginierung
Jeder Aufruf liest höchstens 20.000 Indexeinträge. Erreicht er diese Grenze, bevor die Seite voll ist, liefert er weniger Kontakte (manchmal keine) mit has_more: true. Machen Sie weiter, solange has_more true ist; hören Sie nicht bei einer leeren Seite auf.
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 ist ein beliebiger Helper, der { commands: [...] } per POST an /v1/contacts sendet und results zurückgibt, wie in Run Commands.
Weitere Beispiele
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
}
}
]
}Fehler
Fehler auf HTTP-Ebene liefern type, code und message. Mit CMD markierte Fehler kommen im Befehlsergebnis zurück, mit HTTP 200.
- 401
INVALID_API_KEYDer API Key existiert nicht, wurde widerrufen oder im Dashboard deaktiviert.
- 429
RATE_LIMITEDMehr als 15 Requests/s oder 15 gleichzeitig für dieselbe IP + API Key. Warten Sie die Sekunden aus Retry-After ab.
- CMD
MISSING_SCOPEDem API Key fehlt der Scope, den dieser Befehl braucht. Die anderen Befehle im Request laufen trotzdem.
- CMD
INVALID_ARGSEin Pflichtargument fehlt oder ist ungültig: E-Mail, Feldwert, Enum-Option, where-Schlüssel, Listen-ID …
- CMD
INVALID_CURSORDer Cursor ist fehlerhaft oder gehört zu einer anderen Abfrage oder einem anderen Konto.
- CMD
INTERNALServerfehler. Details werden nur ins Server-Log geschrieben.