Contacts : contacts
Obtenir des contacts
Lisez jusqu'à 100 contacts par email, avec leur profil, statut, listes, tags, champs personnalisés et statistiques d'engagement.
https://g.sendcorex.com/v1/contactscommand: get_contactsNécessite le scope contact:read sur votre API key.
Arguments
emailsstring[]facultatifJusqu'à 100 emails.
emailstringfacultatifUn seul email. Utilisez ceci ou
emails.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: "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
contactsLes contacts qui existent, dans l'ordre demandé.
not_foundEmails valides qui ne sont pas des contacts.
invalidValeurs 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 / domainEn minuscules, sans espaces. Le domaine est tiré de l'email.
first_name … sourceChamps de profil.
nulls'ils ne sont pas renseignés.statusStatut global pour toutes les listes :
subscribed,unsubscribed,bounced,complainedoublocked.status_reason / status_atPourquoi et quand le statut a changé pour la dernière fois.
tagsNormalisés : en minuscules, sans accents.
lists.<id>.subscribedAbonnement à cette liste uniquement.
lists.<id>.sendabletruequand le contact est abonné à cette liste et que son statut global estsubscribed. Les campagnes n'envoient qu'aux contacts sendable.fieldsVos champs personnalisés, déjà convertis dans leur type.
statsEngagement 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.
- 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
INTERNALErreur serveur. Le détail n'est écrit que dans le log du serveur.