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.

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

Erfordert den Scope contact:read auf Ihrem API Key.

i

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

  • whereobjectoptional

    Die Bedingungen, mit AND verknüpft. Weglassen (oder {} senden), um alle Kontakte zu erhalten. Siehe die where-Referenz unten.

  • sortstring | objectoptional

    Ein Feldname oder { "field": "<name>" }. Siehe Sortierung unten.

    z. B. "open_rate"

  • limitnumberoptional

    Seitengröße, von 1 bis 1000. Standard: 50.

  • cursorstringoptional

    Der next_cursor der vorherigen Seite. Senden Sie ihn mit demselben where und sort.

  • selectstring[]optional

    Gibt nur diese Teile jedes Kontakts zurück, zum Beispiel ["status", "fields.plan", "stats.open_count"]. email kommt 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

  • contacts

    Die passenden Kontakte. Vollständig oder nur die mit select angefragten Teile.

  • has_more / next_cursor

    Paginierung. Solange has_more true ist, senden Sie next_cursor als cursor mit demselben where und sort.

  • plan.driver

    Der Index, den der Server zum Durchsuchen gewählt hat, zum Beispiel tag:vip oder list:customers.

  • plan.examined

    Wie viele Indexeinträge gelesen wurden, um diese Seite zu füllen.

  • plan.keys_only

    true, wenn die Seite allein aus dem Index beantwortet wurde, ohne die Kontakte zu laden.

  • plan.ms

    Zeit 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.

  • sendable

    true. Mit list: für diese Liste angemeldet und mit Status subscribed. Ohne list: Status subscribed.

  • 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_rate

    Eine 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_clicked

    Eine 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 einem multi_enum-Feld passt es auf Kontakte mit dieser Option.

  • in

    { "plan": { "in": ["pro", "business"] } }. Einer der Werte.

  • gte, gt, lte, lt, eq

    Bereiche auf number- und date-Feldern. Daten akzeptieren YYYY-MM-DD oder ISO.

  • contains

    Teil eines text-Werts, ohne Groß-/Kleinschreibung und Akzente.

  • exists

    true für Kontakte mit Wert, false fü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.

  • email

    Von A bis Z.

  • fields.<key>

    Aufsteigend. Nicht verfügbar für multi_enum-Felder.

  • sent_count, open_count, click_count, open_rate, click_rate

    Höchster Wert zuerst.

  • created_at, last_open_at, last_click_at, last_sent_at

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

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.

  • 401INVALID_API_KEY

    Der API Key existiert nicht, wurde widerrufen oder im Dashboard deaktiviert.

  • 429RATE_LIMITED

    Mehr als 15 Requests/s oder 15 gleichzeitig für dieselbe IP + API Key. Warten Sie die Sekunden aus Retry-After ab.

  • CMDMISSING_SCOPE

    Dem API Key fehlt der Scope, den dieser Befehl braucht. Die anderen Befehle im Request laufen trotzdem.

  • CMDINVALID_ARGS

    Ein Pflichtargument fehlt oder ist ungültig: E-Mail, Feldwert, Enum-Option, where-Schlüssel, Listen-ID …

  • CMDINVALID_CURSOR

    Der Cursor ist fehlerhaft oder gehört zu einer anderen Abfrage oder einem anderen Konto.

  • CMDINTERNAL

    Serverfehler. Details werden nur ins Server-Log geschrieben.