API Contacts

Récupérer les données d’engagement agrégées par destinataire sur toutes les campagnes.

Lister les Contacts

Obtenir la liste de tous les contacts avec leurs métriques d’engagement.

Endpoint


GET /api/contacts

Paramètres de Requête

Paramètre	Type	Requis	Description
`search`	`string`	Non	Filtrer les contacts par adresse email

Exemple de Requête


curl -X GET "NEXT_PUBLIC_BASE_URL/api/contacts?search=john" \
  -H "x-api-key: votre-cle-api"

Schéma de Réponse

Champ	Type	Description
`email`	`string`	Adresse email du destinataire
`totalEmails`	`number`	Total d’emails envoyés à ce contact
`totalOpens`	`number`	Total d’événements d’ouverture
`totalClicks`	`number`	Total d’événements de clic
`campaigns`	`string[]`	Noms des campagnes reçues par le contact
`engagementScore`	`number`	Score de 0 à 100
`lastActivity`	`string`	Timestamp ISO 8601 de la dernière activité

Formule du Score d’Engagement


openRate = totalOpens / totalEmails
clickRate = totalClicks / totalEmails
engagementScore = min(100, round((openRate * 60 + clickRate * 40) * 100))

Exemple de Réponse


[
  {
    "email": "john@example.com",
    "totalEmails": 24,
    "totalOpens": 18,
    "totalClicks": 7,
    "campaigns": ["Série de Bienvenue", "Newsletter Janvier"],
    "engagementScore": 57,
    "lastActivity": "2024-03-14T16:45:00.000Z"
  },
  {
    "email": "jane@example.com",
    "totalEmails": 12,
    "totalOpens": 12,
    "totalClicks": 5,
    "campaigns": ["Newsletter Janvier"],
    "engagementScore": 77,
    "lastActivity": "2024-03-13T09:30:00.000Z"
  }
]

Obtenir le Détail d’un Contact

Obtenir les informations d’engagement détaillées pour un contact spécifique, incluant l’historique complet d’activité.

Endpoint


GET /api/contacts/:email

Paramètres de Chemin

Paramètre	Type	Description
`email`	`string`	Adresse email encodée en URL

Exemple de Requête


curl -X GET NEXT_PUBLIC_BASE_URL/api/contacts/john%40example.com \
  -H "x-api-key: votre-cle-api"

Schéma de Réponse

Champ	Type	Description
`email`	`string`	Adresse email du destinataire
`totalEmails`	`number`	Total d’emails envoyés
`totalOpens`	`number`	Total d’événements d’ouverture
`totalClicks`	`number`	Total d’événements de clic
`campaigns`	`string[]`	Noms des campagnes
`engagementScore`	`number`	Score de 0 à 100
`lastActivity`	`string`	Timestamp ISO 8601 de la dernière activité
`firstSeen`	`string`	Timestamp ISO 8601 du premier email envoyé
`openRate`	`number`	Ratio d’ouvertures par email
`clickRate`	`number`	Ratio de clics par email
`timeline`	`TimelineEvent[]`	Liste chronologique des événements

Schéma TimelineEvent

Champ	Type	Description
`type`	`string`	`"sent"`, `"opened"` ou `"clicked"`
`timestamp`	`string`	Timestamp ISO 8601 de l’événement
`subject`	`string`	Objet de l’email
`campaign`	`string`	Nom de la campagne (optionnel)
`link`	`string`	URL cliquée (uniquement pour les événements `"clicked"`)

Exemple de Réponse


{
  "email": "john@example.com",
  "totalEmails": 24,
  "totalOpens": 18,
  "totalClicks": 7,
  "campaigns": ["Série de Bienvenue", "Newsletter Janvier"],
  "engagementScore": 57,
  "lastActivity": "2024-03-14T16:45:00.000Z",
  "firstSeen": "2024-01-05T08:00:00.000Z",
  "openRate": 0.75,
  "clickRate": 0.29,
  "timeline": [
    {
      "type": "clicked",
      "timestamp": "2024-03-14T16:45:00.000Z",
      "subject": "Newsletter Mars",
      "campaign": "Newsletter Janvier",
      "link": "https://example.com/promo"
    },
    {
      "type": "opened",
      "timestamp": "2024-03-14T16:40:00.000Z",
      "subject": "Newsletter Mars",
      "campaign": "Newsletter Janvier"
    },
    {
      "type": "sent",
      "timestamp": "2024-03-14T10:00:00.000Z",
      "subject": "Newsletter Mars",
      "campaign": "Newsletter Janvier"
    }
  ]
}

Réponses d’Erreur

Statut	Description
`401 Unauthorized`	Clé API invalide ou manquante
`404 Not Found`	Contact non trouvé dans votre organisation

Exemple d’Erreur


{
  "error": "Contact non trouvé"
}