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.
https://g.sendcorex.com/v1/contactscommand: query_contactsNécessite le scope contact:read sur votre API key.
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
whereobjectfacultatifLes conditions, combinées avec AND. Omettez-le (ou envoyez
{}) pour obtenir tous les contacts. Voir la référencewhereci-dessous.sortstring | objectfacultatifUn nom de champ ou
{ "field": "<name>" }. Voir Tri ci-dessous.ex. :
"open_rate"limitnumberfacultatifTaille de page, de 1 à 1000. 50 par défaut.
cursorstringfacultatifLe
next_cursorde la page précédente. Envoyez-le avec les mêmeswhereetsort.selectstring[]facultatifNe renvoie que ces parties de chaque contact, par exemple
["status", "fields.plan", "stats.open_count"].emailrevient 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
contactsLes contacts trouvés. Complets, ou uniquement les parties demandées avec
select.has_more / next_cursorPagination. Tant que
has_morevauttrue, envoyeznext_cursorcommecursoravec les mêmeswhereetsort.plan.driverL'index que le serveur a choisi de parcourir, par exemple
tag:vipoulist:customers.plan.examinedCombien d'entrées d'index ont été lues pour remplir cette page.
plan.keys_onlytruequand la page a été servie uniquement depuis l'index, sans charger les contacts.plan.msTemps 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.sendabletrue. Aveclist: abonné à cette liste et avec le statutsubscribed. Sanslist: statutsubscribed.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_rateUn 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_clickedUn 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 champmulti_enum, trouve les contacts qui ont cette option.in{ "plan": { "in": ["pro", "business"] } }. L'une des valeurs.gte, gt, lte, lt, eqPlages sur les champs
numberetdate. Les dates acceptentYYYY-MM-DDou ISO.containsUne partie d'une valeur
text, sans tenir compte de la casse ni des accents.existstruepour les contacts qui ont une valeur,falsepour 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.
emailDe A à Z.
fields.<key>Croissant. Non disponible pour les champs
multi_enum.sent_count, open_count, click_count, open_rate, click_rateLe plus élevé d'abord.
created_at, last_open_at, last_click_at, last_sent_atLe 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);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.
- 401
INVALID_API_KEYL'API key n'existe pas, a été révoquée ou désactivée dans le dashboard.
- 429
RATE_LIMITEDPlus 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.
- CMD
MISSING_SCOPEL'API key n'a pas le scope requis par cette commande. Les autres commandes de la requête s'exécutent quand même.
- CMD
INVALID_ARGSUn argument obligatoire est manquant ou invalide : email, valeur de champ, option d'enum, clé de where, id de liste…
- CMD
INVALID_CURSORLe cursor est mal formé ou appartient à une autre requête ou à un autre compte.
- CMD
INTERNALErreur serveur. Le détail n'est écrit que dans le log du serveur.