Contacts : activité

Lister les événements

L'historique d'un contact, du plus récent au plus ancien : envois, ouvertures, clics, bounces, plaintes et désabonnements.

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

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

i

Les événements sont enregistrés par l'envoi et le tracking. L'API se contente de les lire.

Arguments

  • emailstringobligatoire

    Le contact.

    ex. : "ana@acme.com"

  • typesstring[]facultatif

    Uniquement ces types : sent, open, click, bounce, complaint, unsubscribe.

    ex. : ["open", "click"]

  • limitnumberfacultatif

    Taille de page, de 1 à 1000. 50 par défaut.

  • cursorstringfacultatif

    Le next_cursor de la page précédente.

Démarrage rapide

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/contacts',
  {
    commands: [
      {
        command: "list_events",
        args: {
          email: "ana@acme.com",
          types: [
            "open",
            "click"
          ],
          limit: 50
        }
      }
    ]
  },
  { 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": "list_events",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 14,
      "data": {
        "events": [
          {
            "event_id": "ev_7c1d02",
            "type": "click",
            "at": "2026-10-14T21:04:10.000Z",
            "campaign_id": "cmp_october",
            "list_id": "customers",
            "url": "https://acme.com/offer",
            "ip": "203.0.113.24",
            "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
            "reason": null,
            "by_proxy": false,
            "hard": null,
            "meta": null
          },
          {
            "event_id": "ev_7c1cf9",
            "type": "open",
            "at": "2026-10-14T21:03:55.000Z",
            "campaign_id": "cmp_october",
            "list_id": "customers",
            "url": null,
            "ip": "203.0.113.24",
            "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)",
            "reason": null,
            "by_proxy": false,
            "hard": null,
            "meta": null
          }
        ],
        "has_more": true,
        "next_cursor": "eyJ0IjoxNzYwNDc1ODM1fQ"
      }
    }
  ]
}

Champs de la réponse

  • events[].type

    sent, open, click, bounce, complaint ou unsubscribe.

  • events[].at

    Quand c'est arrivé.

  • events[].campaign_id / list_id

    La campagne et la liste auxquelles appartenait l'email, si elles sont connues.

  • events[].url

    Le lien, pour les événements click.

  • events[].ip / user_agent

    D'où viennent l'ouverture ou le clic.

  • events[].by_proxy

    true quand l'ouverture provient d'un proxy de confidentialité de messagerie et non de la personne.

  • events[].reason / hard

    Pour bounce : la raison, et s'il s'agissait d'un hard bounce.

  • has_more / next_cursor

    Pagination. Envoyez next_cursor comme cursor pour obtenir des événements plus anciens.

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…

  • CMDINVALID_CURSOR

    Le cursor est mal formé ou appartient à une autre requête ou à un autre compte.

  • CMDINTERNAL

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