Contacts : recherche

Interroger les contacts

Trouvez des contacts avec n'importe quelle combinaison de liste, statut, tags, champs personnalisés, engagement et dates. Vous décrivez qui vous voulez ; le serveur choisit l'index.

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

Nécessite le scope contact:read sur votre API key.

i

Le serveur évalue chaque condition indexée du where, parcourt la plus sélective et vérifie chaque contact par rapport à tout le where. Vous ne choisissez jamais d'index.

Arguments

  • whereobjectfacultatif

    Les conditions, combinées avec AND. Omettez-le (ou envoyez {}) pour obtenir tous les contacts. Voir la référence where ci-dessous.

  • sortstring | objectfacultatif

    Un nom de champ ou { "field": "<name>" }. Voir Tri ci-dessous.

    ex. : "open_rate"

  • limitnumberfacultatif

    Taille de page, de 1 à 1000. 50 par défaut.

  • cursorstringfacultatif

    Le next_cursor de la page précédente. Envoyez-le avec les mêmes where et sort.

  • selectstring[]facultatif

    Ne renvoie que ces parties de chaque contact, par exemple ["status", "fields.plan", "stats.open_count"]. email revient toujours. Sans lui, vous obtenez le contact complet.

Démarrage rapide

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

Réponse

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

Champs de la réponse

  • contacts

    Les contacts trouvés. Complets, ou uniquement les parties demandées avec select.

  • has_more / next_cursor

    Pagination. Tant que has_more vaut true, envoyez next_cursor comme cursor avec les mêmes where et sort.

  • plan.driver

    L'index que le serveur a choisi de parcourir, par exemple tag:vip ou list:customers.

  • plan.examined

    Combien d'entrées d'index ont été lues pour remplir cette page.

  • plan.keys_only

    true quand la page a été servie uniquement depuis l'index, sans charger les contacts.

  • plan.ms

    Temps passé à parcourir, charger, filtrer et au total, en millisecondes.

L'objet where

Chaque clé est facultative et toutes doivent correspondre. Le texte, les options d'enum et les tags ignorent la casse et les accents.

  • email

    "ana@acme.com". Lit directement ce contact.

  • search

    "jo sil". Chaque mot doit être le début d'un mot du prénom, du nom, de l'entreprise ou de l'email.

  • status

    "subscribed", une liste comme ["bounced", "complained"], { "in": [...] } ou { "not": "subscribed" }.

  • list

    "customers", ou { "in": ["a", "b"] } pour les membres de l'une d'entre elles.

  • sendable

    true. Avec list : abonné à cette liste et avec le statut subscribed. Sans list : statut subscribed.

  • tags

    { "has": "vip" }, { "all": [...] }, { "any": [...] }, { "none": [...] }. Ils peuvent être combinés.

  • domain

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

  • fields

    { "plan": "pro" }, { "age": { "gte": 25 } }, { "plan": { "in": [...] } }, { "city": { "contains": "paul" } }, { "company": { "exists": true } }. Le champ doit exister.

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

    Un nombre, ou { "gte", "gt", "lte", "lt", "eq" }. Les taux vont de 0 à 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 } ou { "exists": true }.

  • campaign_opened, campaign_clicked

    Un id de campagne. Les contacts qui ont ouvert ou cliqué dans cette campagne.

!

Une clé inconnue, ou un champ inexistant, fait échouer la commande avec INVALID_ARGS au lieu de ne rien trouver en silence.

Opérateurs pour les champs personnalisés

Chaque champ personnalisé est indexé séparément : ces filtres restent rapides sur de grandes listes.

  • Égal

    { "plan": "pro" }. Les valeurs texte et enum ignorent la casse et les accents. Sur un champ multi_enum, trouve les contacts qui ont cette option.

  • in

    { "plan": { "in": ["pro", "business"] } }. L'une des valeurs.

  • gte, gt, lte, lt, eq

    Plages sur les champs number et date. Les dates acceptent YYYY-MM-DD ou ISO.

  • contains

    Une partie d'une valeur text, sans tenir compte de la casse ni des accents.

  • exists

    true pour les contacts qui ont une valeur, false pour les autres.

Tri

Chaque champ de tri a un sens fixe. Trier par un champ personnalisé ou une date ne renvoie que les contacts qui ont une valeur : last_open_at ne renvoie que les personnes ayant ouvert au moins une fois.

  • email

    De A à Z.

  • fields.<key>

    Croissant. Non disponible pour les champs multi_enum.

  • sent_count, open_count, click_count, open_rate, click_rate

    Le plus élevé d'abord.

  • created_at, last_open_at, last_click_at, last_sent_at

    Le plus récent d'abord.

Pagination

Chaque appel lit au plus 20 000 entrées d'index. S'il atteint ce plafond avant de remplir la page, il renvoie moins de contacts (parfois aucun) avec has_more: true. Continuez tant que has_more vaut true ; ne vous arrêtez pas sur une page vide.

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 est n'importe quel helper qui envoie { commands: [...] } en POST à /v1/contacts et renvoie results, comme dans Run Commands.

Plus d'exemples

Corps de la requête

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

Erreurs

Les erreurs au niveau HTTP renvoient type, code et message. Les erreurs marquées CMD reviennent dans le résultat de la commande, avec HTTP 200.

  • 401INVALID_API_KEY

    L'API key n'existe pas, a été révoquée ou désactivée dans le dashboard.

  • 429RATE_LIMITED

    Plus de 15 requêtes/s ou 15 simultanées pour la même IP + API key. Attendez le nombre de secondes indiqué dans Retry-After.

  • CMDMISSING_SCOPE

    L'API key n'a pas le scope requis par cette commande. Les autres commandes de la requête s'exécutent quand même.

  • CMDINVALID_ARGS

    Un argument obligatoire est manquant ou invalide : email, valeur de champ, option d'enum, clé de where, id de liste…

  • CMDINVALID_CURSOR

    Le cursor est mal formé ou appartient à une autre requête ou à un autre compte.

  • CMDINTERNAL

    Erreur serveur. Le détail n'est écrit que dans le log du serveur.