Contacts : contacts

Obtenir des contacts

Lisez jusqu'à 100 contacts par email, avec leur profil, statut, listes, tags, champs personnalisés et statistiques d'engagement.

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

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

Arguments

  • emailsstring[]facultatif

    Jusqu'à 100 emails.

  • emailstringfacultatif

    Un seul email. Utilisez ceci ou emails.

  • 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: "get_contacts",
        args: {
          emails: [
            "ana@acme.com",
            "zoe@acme.com",
            "not-an-email"
          ]
        }
      }
    ]
  },
  { 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": "get_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"
            }
          }
        ],
        "not_found": [
          "zoe@acme.com"
        ],
        "invalid": [
          "not-an-email"
        ]
      }
    }
  ]
}

Champs de la réponse

  • contacts

    Les contacts qui existent, dans l'ordre demandé.

  • not_found

    Emails valides qui ne sont pas des contacts.

  • invalid

    Valeurs qui ne sont pas des emails, telles que vous les avez envoyées.

Le contact

Chaque lecture renvoie les contacts sous cette forme.

Contact

{
  "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"
  }
}
  • email / domain

    En minuscules, sans espaces. Le domaine est tiré de l'email.

  • first_name … source

    Champs de profil. null s'ils ne sont pas renseignés.

  • status

    Statut global pour toutes les listes : subscribed, unsubscribed, bounced, complained ou blocked.

  • status_reason / status_at

    Pourquoi et quand le statut a changé pour la dernière fois.

  • tags

    Normalisés : en minuscules, sans accents.

  • lists.<id>.subscribed

    Abonnement à cette liste uniquement.

  • lists.<id>.sendable

    true quand le contact est abonné à cette liste et que son statut global est subscribed. Les campagnes n'envoient qu'aux contacts sendable.

  • fields

    Vos champs personnalisés, déjà convertis dans leur type.

  • stats

    Engagement issu de l'envoi et du tracking. En lecture seule : l'API ne l'écrit jamais. Les taux vont de 0 à 1.

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…

  • CMDINTERNAL

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