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.

POSThttps://g.sendcorex.com/v1/contacts
i

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

i

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[]obligatoire

    De 1 à 20 commandes, exécutées dans l'ordre. Le corps entier peut faire jusqu'à 1 Mo.

  • commands[].commandstringobligatoire

    Le nom de la commande, par exemple upsert_contacts.

  • commands[].argsobjectfacultatif

    Les arguments de la commande. Toute valeur peut être un $ref vers le résultat d'une commande précédente.

  • commands[].idstringfacultatif

    Votre 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

  • type

    Toujours SUCCESS quand la requête elle-même a été acceptée.

  • results[].command

    La commande qui a produit ce résultat.

  • results[].id

    L'id que vous avez envoyé, ou l'index de la commande.

  • results[].type

    SUCCESS ou ERROR.

  • results[].took_ms

    Temps passé par la commande dans le serveur. Le reste du temps de la requête correspond au réseau.

  • results[].data

    La sortie de la commande. Présente uniquement quand type vaut SUCCESS.

  • results[].code / message

    L'erreur. Présente uniquement quand type vaut ERROR.

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.

  • Authorization

    Envoyez Authorization: <api key> ou Authorization: Bearer <api key>.

  • Tokens de boîte mail

    Le token du webmail (S.C.G.…) ne fonctionne pas ici. Il est refusé avec WRONG_CREDENTIAL_TYPE.

  • IP autorisées

    Si la clé a une liste d'IP autorisées, les requêtes venant d'autres IP reçoivent 403 IP_NOT_ALLOWED.

  • Révocation

    Les 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:read

    get_contacts, query_contacts, count_contacts, list_events, get_stats, list_fields, list_lists, get_list, list_members, list_segments, get_segment, run_segment.

  • contact:create

    create_list, define_field, save_segment.

  • contact:create + update

    upsert_contacts, car il crée ou met à jour.

  • contact:update

    update_contacts, add_tags, remove_tags, add_to_lists, remove_from_lists, set_list_subscription, set_status, set_fields, unset_fields, update_list.

  • contact:delete

    delete_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"
        ]
      }
    }
  ]
}
  • $ref

    L'id d'une commande précédente dans la même requête.

  • path

    Chemin 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
}
i

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érieur

    email, domain, status, status_reason, status_at, created_at, updated_at, tags, lists, fields, stats et les champs de profil (first_name, last_name, phone, company, locale, timezone, source).

  • Imbriqués

    fields.<key>, stats.<key> et lists.<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 / seconde

    Pic de 15. Les réponses servies depuis le cache comptent aussi.

  • 15 simultanées

    Au maximum 15 requêtes traitées en même temps.

  • Groupez au lieu de boucler

    Une requête peut contenir 20 commandes de 500 contacts chacune : 10 000 contacts par requête.

  • Cache de lecture : 1,5 s

    La 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 s

    La 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 cache

    Toute écriture vide immédiatement votre cache de lecture : la lecture suivante voit le nouvel état.

Limites

  • Tags

    50 par contact.

  • Listes

    75 par contact.

  • Champs personnalisés

    100 par compte.

  • Données personnalisées de liste

    50 clés par liste.

  • Texte

    Un champ text contient 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 email

    Un contact appartient à votre compte, pas à une liste. Listes, tags, champs et statut sont des attributs du contact.

  • Emails

    Enregistrés en minuscules et sans espaces. Ana@Acme.com et ana@acme.com sont le même contact.

  • Casse et accents

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

  • Pagination

    Les listes susceptibles de grandir renvoient has_more et next_cursor. Envoyez next_cursor comme cursor à l'appel suivant, avec les mêmes autres arguments.

  • Suppressions

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

  • 400INVALID_JSON

    Le corps n'est pas {"commands":[...]} ou dépasse 1 Mo.

  • 400INVALID_ARGS

    La requête ne contient aucune commande ou plus de 20.

  • 401MISSING_AUTH_HEADER

    Aucun header Authorization n'a été envoyé.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    L'API key a dépassé la date d'expiration définie dans le dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Un token de boîte mail (S.C.G.…) a été envoyé. Les contacts nécessitent une API key du dashboard.

  • 403IP_NOT_ALLOWED

    La requête provient d'une IP qui ne figure pas parmi les IP autorisées de la clé.

  • 403ACCOUNT_BLOCKED

    Le compte est bloqué.

  • 403MISSING_SCOPE

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

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

  • 503AUTH_UNAVAILABLE

    L'authentification est temporairement indisponible. Réessayez.

  • CMDUNKNOWN_COMMAND

    Le nom de la commande n'existe pas.

  • CMDINTERNAL

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