Contacts : routes
Run Commands
Le point d'entrée unique pour les contacts, listes, champs personnalisés et segments. Envoyez de 1 à 20 commandes dans une requête et recevez un résultat par commande.
https://g.sendcorex.com/v1/contactsChaque action (importer, taguer, interroger, désabonner, créer une liste…) est une commande envoyée à cette route. Les pages suivantes documentent chaque commande et ses arguments.
Les erreurs sont signalées par commande, et les actions groupées par email. Une commande qui échoue n'arrête pas les autres, et le statut HTTP reste 200.
Paramètres du corps
commandsobject[]obligatoireDe 1 à 20 commandes, exécutées dans l'ordre. Le corps entier peut faire jusqu'à 1 Mo.
commands[].commandstringobligatoireLe nom de la commande, par exemple
upsert_contacts.commands[].argsobjectfacultatifLes arguments de la commande. Toute valeur peut être un
$refvers le résultat d'une commande précédente.commands[].idstringfacultatifVotre propre identifiant pour le résultat. Par défaut, l'index (
"0","1"…). Obligatoire si vous voulez utiliser$ref.
Démarrage rapide
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/contacts',
{
commands: [
{
command: "list_lists"
},
{
command: "get_stats"
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
for (const result of response.data.results) {
if (result.type !== 'SUCCESS') console.error(result.id, result.code, result.message);
else console.log(result.id, result.data);
}Réponse
{
"type": "SUCCESS",
"results": [
{
"command": "list_lists",
"id": "0",
"type": "SUCCESS",
"took_ms": 6,
"data": {
"lists": [
{
"list_id": "customers",
"name": "Customers",
"description": "Everyone who bought at least once",
"source": "checkout",
"status": "ready",
"custom": {
"origin": "checkout",
"year": 2026
},
"created_at": "2026-10-01T10:00:00.000Z",
"updated_at": "2026-10-12T15:22:41.000Z",
"stats": {
"total": 1834,
"ok": 1790,
"opened": 912,
"clicked": 233
}
}
]
}
},
{
"command": "get_stats",
"id": "1",
"type": "SUCCESS",
"took_ms": 9,
"data": {
"total": 2040,
"status": {
"subscribed": 1951,
"unsubscribed": 61,
"bounced": 22,
"complained": 3,
"blocked": 3
},
"lists": {
"customers": {
"total": 1834,
"ok": 1790,
"opened": 912,
"clicked": 233
}
},
"tags": {
"customer": 1834,
"vip": 120
}
}
}
]
}Champs de la réponse
typeToujours
SUCCESSquand la requête elle-même a été acceptée.results[].commandLa commande qui a produit ce résultat.
results[].idL'
idque vous avez envoyé, ou l'index de la commande.results[].typeSUCCESSouERROR.results[].took_msTemps passé par la commande dans le serveur. Le reste du temps de la requête correspond au réseau.
results[].dataLa sortie de la commande. Présente uniquement quand
typevautSUCCESS.results[].code / messageL'erreur. Présente uniquement quand
typevautERROR.
Authentification
Les contacts utilisent l'API key que vous créez dans le dashboard, sous Developers → API Keys. C'est le même type de clé que pour l'envoi d'emails, et elle n'expire pas sauf si vous lui fixez une date d'expiration.
AuthorizationEnvoyez
Authorization: <api key>ouAuthorization: Bearer <api key>.Tokens de boîte mailLe token du webmail (
S.C.G.…) ne fonctionne pas ici. Il est refusé avecWRONG_CREDENTIAL_TYPE.IP autoriséesSi la clé a une liste d'IP autorisées, les requêtes venant d'autres IP reçoivent
403 IP_NOT_ALLOWED.RévocationLes clés sont mises en cache 60 secondes : une clé révoquée cesse de fonctionner en moins d'une minute. La date d'expiration est vérifiée à chaque requête.
Gardez la clé sur votre serveur. Quiconque la possède peut lire et modifier vos contacts.
Scopes
Chaque commande nécessite un scope sur la clé. Quand un scope manque, seule cette commande échoue avec MISSING_SCOPE ; le reste de la requête s'exécute normalement. Une clé sans aucun scope contact:* reçoit 403 MISSING_SCOPE avant l'exécution de toute commande.
contact:readget_contacts,query_contacts,count_contacts,list_events,get_stats,list_fields,list_lists,get_list,list_members,list_segments,get_segment,run_segment.contact:createcreate_list,define_field,save_segment.contact:create + updateupsert_contacts, car il crée ou met à jour.contact:updateupdate_contacts,add_tags,remove_tags,add_to_lists,remove_from_lists,set_list_subscription,set_status,set_fields,unset_fields,update_list.contact:deletedelete_contacts,delete_list,delete_field,delete_segment.
Utiliser un résultat précédent avec $ref
Toute valeur dans args peut être {"$ref": "<id>", "path": "<path>"}. Elle est remplacée par la valeur trouvée à path dans le résultat de la commande ayant cet id. Dans path, * parcourt une liste et aplatit le résultat. Cette requête trouve tous les contacts du plan pro ou business et les tague, en un seul aller-retour.
Corps de la requête
{
"commands": [
{
"command": "query_contacts",
"id": "q",
"args": {
"where": {
"fields": {
"plan": {
"in": [
"pro",
"business"
]
}
}
},
"select": [
"email"
]
}
},
{
"command": "add_tags",
"args": {
"emails": {
"$ref": "q",
"path": "contacts/*/email"
},
"tags": [
"premium"
]
}
}
]
}$refL'
idd'une commande précédente dans la même requête.pathChemin séparé par des barres obliques dans ce résultat.
*parcourt chaque élément d'une liste.
Actions groupées
Les actions prennent emails (jusqu'à 500) ou email (un seul) et répondent email par email. Un email invalide échoue seul, sans arrêter les autres.
data d'une action groupée
{
"items": [
{
"id": "ana@acme.com",
"ok": true,
"data": {
"changed": true
}
},
{
"id": "x@y.com",
"ok": false,
"code": "NOT_FOUND",
"message": "contact not found"
}
],
"ok_count": 1,
"failed_count": 1
}changed: false signifie que le contact était déjà ainsi : rien n'a été écrit. Envoyez return_contacts: true pour récupérer le contact complet dans chaque élément.
Ne demandez que ce dont vous avez besoin
Sans select, chaque contact revient complet. Avec, seules les parties nommées reviennent, et email revient toujours. Fonctionne sur get_contacts, query_contacts, run_segment et list_members avec hydrate. Une requête limitée aux emails est servie depuis l'index : c'est la lecture la plus rapide qui soit.
Corps de la requête
{
"commands": [
{
"command": "query_contacts",
"args": {
"where": {
"list": "customers",
"sendable": true
},
"select": [
"first_name",
"status",
"fields.plan",
"stats.open_count"
]
}
}
]
}Niveau supérieuremail,domain,status,status_reason,status_at,created_at,updated_at,tags,lists,fields,statset les champs de profil (first_name,last_name,phone,company,locale,timezone,source).Imbriquésfields.<key>,stats.<key>etlists.<list_id>ne renvoient que cette partie. Demander tout le niveau supérieur (fields) l'emporte sur ses sous-clés.
Rate limits et cache
Les limites s'appliquent par IP + API key. Il n'y a pas de file d'attente : au-delà, la requête est refusée avec HTTP 429 et un header Retry-After.
15 requêtes / secondePic de 15. Les réponses servies depuis le cache comptent aussi.
15 simultanéesAu maximum 15 requêtes traitées en même temps.
Groupez au lieu de bouclerUne requête peut contenir 20 commandes de 500 contacts chacune : 10 000 contacts par requête.
Cache de lecture : 1,5 sLa même lecture (même commande et mêmes args) dans les 1,5 seconde renvoie le même résultat, et les lectures identiques simultanées partagent une seule requête.
Déduplication des écritures : 1,5 sLa même écriture répétée dans les 1,5 seconde renvoie le premier résultat sans réécrire : un double clic n'importe pas deux fois.
Invalidation du cacheToute écriture vide immédiatement votre cache de lecture : la lecture suivante voit le nouvel état.
Limites
Tags50 par contact.
Listes75 par contact.
Champs personnalisés100 par compte.
Données personnalisées de liste50 clés par liste.
TexteUn champ
textcontient jusqu'à 2 000 caractères. Les champs de profil (first_name…) jusqu'à 256.
Conventions
Ces règles s'appliquent à toutes les commandes.
Un contact par emailUn contact appartient à votre compte, pas à une liste. Listes, tags, champs et statut sont des attributs du contact.
EmailsEnregistrés en minuscules et sans espaces.
Ana@Acme.cometana@acme.comsont le même contact.Casse et accentsLes tags, les options d'enum et la comparaison de texte ignorent la casse et les accents :
"são paulo"correspond à"Sao Paulo". Les tags sont enregistrés normalisés.PaginationLes listes susceptibles de grandir renvoient
has_moreetnext_cursor. Envoyeznext_cursorcommecursorà l'appel suivant, avec les mêmes autres arguments.SuppressionsLa suppression d'une liste ou d'un champ prend effet immédiatement ; les valeurs sont retirées des contacts en arrière-plan (
purging: true).
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.
- 400
INVALID_JSONLe corps n'est pas {"commands":[...]} ou dépasse 1 Mo.
- 400
INVALID_ARGSLa requête ne contient aucune commande ou plus de 20.
- 401
MISSING_AUTH_HEADERAucun header Authorization n'a été envoyé.
- 401
INVALID_API_KEYL'API key n'existe pas, a été révoquée ou désactivée dans le dashboard.
- 401
API_KEY_EXPIREDL'API key a dépassé la date d'expiration définie dans le dashboard.
- 401
WRONG_CREDENTIAL_TYPEUn token de boîte mail (S.C.G.…) a été envoyé. Les contacts nécessitent une API key du dashboard.
- 403
IP_NOT_ALLOWEDLa requête provient d'une IP qui ne figure pas parmi les IP autorisées de la clé.
- 403
ACCOUNT_BLOCKEDLe compte est bloqué.
- 403
MISSING_SCOPELa clé n'a aucun scope contact:*, donc aucune commande ne peut s'exécuter. Quand un seul scope manque, seule cette commande échoue, avec HTTP 200.
- 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.
- 503
AUTH_UNAVAILABLEL'authentification est temporairement indisponible. Réessayez.
- CMD
UNKNOWN_COMMANDLe nom de la commande n'existe pas.
- CMD
INTERNALErreur serveur. Le détail n'est écrit que dans le log du serveur.