Contacts

Gérez votre audience avec l'API

Gardez vos contacts synchronisés avec votre application. Importez-en des milliers d'un coup, taguez-les, stockez vos propres champs, organisez-les en listes et trouvez exactement à qui écrire, le tout via un seul endpoint.

  • REST
  • JSON
  • Par lots, jusqu'à 10 000 par requête
  • Listes, tags et champs
  • Segments
POSThttps://g.sendcorex.com/v1/contacts

Fonctionnement

Un contact par email

Un contact appartient à votre compte, pas à une liste. Listes, tags, champs personnalisés et statut sont des attributs de ce contact unique : rien n'est dupliqué.

Un endpoint pour tout

Importer, taguer, interroger, désabonner, gérer les listes et les segments : chaque action est une commande envoyée à POST /v1/contacts. Jusqu'à 20 commandes par requête.

Conçu pour le volume

Chaque action accepte jusqu'à 500 emails et répond email par email. Une ligne invalide échoue seule ; le reste du lot passe.

Premiers pas

Quatre étapes, et seule la première est obligatoire avant votre première requête.

  1. 1

    Créez une API key

    Dans le dashboard, ouvrez Developers → API Keys et créez une clé. Donnez-lui les scopes de contacts dont votre application a besoin.

    Le token du webmail ne fonctionne pas ici. Les contacts utilisent la même API key du dashboard que pour l'envoi d'emails.

  2. 2

    Choisissez les scopes

    Les intégrations en lecture seule n'ont besoin que de contact:read. Une synchronisation qui importe et met à jour a besoin de contact:create et contact:update.

  3. 3

    Définissez vos champs et vos listes

    Créez les champs personnalisés à stocker (offre, ville, anniversaire…) et les listes auxquelles vous envoyez. Vous pouvez aussi le faire depuis le dashboard.

  4. 4

    Importez et interrogez

    Envoyez vos contacts avec Upsert Contacts, puis retrouvez-les avec Query Contacts.

Scopes

Chaque commande nécessite un scope sur la clé. Quand il en manque un, seule cette commande échoue avec MISSING_SCOPE ; le reste de la requête s'exécute quand même.

  • contact:read

    Lire les contacts, listes, champs, segments, événements et statistiques.

  • contact:create

    Créer des listes, champs et segments. Upsert en a aussi besoin, pour créer de nouveaux contacts.

  • contact:update

    Mettre à jour les contacts, tags, statuts, champs et appartenances aux listes.

  • contact:delete

    Supprimer des contacts, listes, champs et segments.

i

La liste complète, commande par commande, se trouve dans Run Commands. Chaque page de commande indique aussi le scope requis.

Le contact

Chaque lecture renvoie les contacts sous cette forme. Vous n'écrivez que les parties qui vous intéressent.

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

Global. Un contact désabonné, en bounce, plaignant ou bloqué n'est joignable dans aucune liste.

lists

Appartenance et abonnement par liste. Quelqu'un peut quitter une liste et rester dans les autres.

sendable

Abonné à la liste et avec le statut subscribed. C'est à eux que les campagnes envoient.

stats

Envois, ouvertures et clics issus du tracking. En lecture seule, et vous pouvez filtrer et trier dessus.

Votre première requête

Importez deux contacts et relisez-les, en une seule requête. Remplacez SENDCOREX_API_KEY par votre API key.

curl -X POST 'https://g.sendcorex.com/v1/contacts' \
  -H "Authorization: $SENDCOREX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "commands": [
    { "command": "upsert_contacts", "args": {
        "tags": ["imported"],
        "contacts": [
          { "email": "ana@acme.com", "first_name": "Ana", "company": "Acme" },
          { "email": "bob@gmail.com", "first_name": "Bob" }
        ]
    } },
    { "command": "query_contacts", "args": { "where": { "tags": { "has": "imported" } } } }
  ]
}'

Vous obtenez un résultat par commande. Le premier indique combien de contacts ont été created ; le second les renvoie. Relancez-la et rien n'est écrit : les deux lignes reviennent avec changed: false. La même requête en 8 langages se trouve dans Upsert Contacts.

Tâches courantes

Synchronisez les inscriptions de votre application

Faites un upsert du contact avec list_id à chaque inscription. Renvoyer les mêmes données n'écrit rien : vous pouvez aussi l'appeler à chaque connexion.

Upsert Contacts

Honorez un lien de désabonnement

Désabonnez d'une liste avec Set List Subscription, ou de tout avec Set Status.

Set List Subscription

Trouvez les clients engagés

Interrogez par liste, tag et last_open_at, triés par open_rate. Enregistrez-le comme segment pour le réutiliser.

Query Contacts

Exportez une liste

Parcourez List Members avec sendable_only et sélectionnez uniquement les champs nécessaires, 5 000 membres par page.

List Members

Référence complète

Tout ce qui est marqué CMD est une commande envoyée via POST /v1/contacts, jusqu'à 20 par requête.

Routes

1

Contacts

4

Recherche

2

Tags, statut et champs

5

Listes

9

Champs personnalisés

3

Segments

5

Activité

2