Top destinataires de l'espace de travail

Classe les destinataires les plus sollicités sur une fenêtre temporelle, d'après le nombre de transferts reçus.

Réponse exemple

{
  "data": [
    {
      "email": "comptabilite@acme.fr",
      "total_files": 96,
      "last_sent_at": "2026-06-04T16:02:11.000Z",
      "first_sent_at": "2026-03-09T08:41:55.000Z",
      "transfers_sent": 24,
      "in_address_book": true
    },
    {
      "email": "notaire@cabinet-durand.fr",
      "total_files": 18,
      "last_sent_at": "2026-06-01T11:20:03.000Z",
      "first_sent_at": "2026-04-12T14:55:30.000Z",
      "transfers_sent": 9,
      "in_address_book": false
    },
    {
      "email": "rh@startup-xyz.io",
      "total_files": 5,
      "last_sent_at": "2026-05-28T09:00:00.000Z",
      "first_sent_at": "2026-05-02T10:30:12.000Z",
      "transfers_sent": 4,
      "in_address_book": false
    }
  ],
  "since": "2026-03-07T09:12:44.000Z",
  "object": "list",
  "range_days": 90,
  "next_actions": [
    "coffrify_add_recipient email=\"notaire@cabinet-durand.fr\" - sent 9x in the last 90d, not yet in address book.",
    "coffrify_add_recipient email=\"rh@startup-xyz.io\" - sent 4x in the last 90d, not yet in address book."
  ],
  "workspace_id": "ws_3kT9aZ0qVbN4",
  "unique_recipients": 137,
  "total_transfers_with_recipient": 482
}

GET/v1/recipients/topClassement des destinataires les plus fréquents de l'espace de travail sur une période glissante.

Cet endpoint agrège les transferts de l'espace de travail courant et renvoie les destinataires les plus sollicités, classés par nombre décroissant de transferts qui leur ont été envoyés. L'agrégation se fait par adresse e-mail (normalisée en minuscules) sur les transferts dont le champ recipient_email est renseigné, dans la fenêtre de days jours. Chaque entrée est enrichie de la date du premier et du dernier envoi, du nombre total de fichiers cumulés sur ses transferts, et d'un drapeau indiquant si l'adresse figure déjà dans le carnet d'adresses du propriétaire de l'espace. La réponse inclut aussi un bloc next_actions qui suggère d'ajouter au carnet d'adresses les destinataires récurrents (au moins 3 transferts) qui n'y sont pas encore.

Authentification

Requiert une clé API valide portant le scope transfers:read. Le wildcard * ainsi que le wildcard de ressource transfers:* satisfont également cette exigence. L'espace de travail ciblé est toujours celui résolu depuis la clé (ctx.workspaceId) : il n'est pas possible de demander le classement d'un autre espace via cet endpoint.

Paramètres de requête

Paramètre	Type	Requis	Description
days	entier (query)	Non	Taille de la fenêtre d'agrégation en jours. Défaut `90`. Borné entre `1` et `365` (toute valeur hors plage est ramenée à la borne ; une valeur non numérique retombe sur `90`).
limit	entier (query)	Non	Nombre maximum de destinataires renvoyés. Défaut `20`. Borné entre `1` et `100` (une valeur non numérique retombe sur `20`).

Réponse

La réponse est un objet de type liste (object: "list"). Le tableau data contient les destinataires classés, et plusieurs champs de contexte accompagnent la collection.

Champ	Type	Description
workspace_id	string	Identifiant de l'espace de travail analysé (résolu depuis la clé API).
range_days	entier	Fenêtre effectivement appliquée après bornage (1 à 365).
since	string (ISO 8601)	Horodatage de début de fenêtre, soit `maintenant - range_days` jours.
unique_recipients	entier	Nombre total d'adresses e-mail distinctes trouvées sur la fenêtre (avant troncature par `limit`).
total_transfers_with_recipient	entier	Nombre total de transferts avec un destinataire renseigné, scannés sur la fenêtre.
object	string	Toujours `"list"`.
data	tableau	Destinataires classés par `transfers_sent` décroissant, tronqués à `limit`.
data[].email	string	Adresse e-mail du destinataire (en minuscules).
data[].transfers_sent	entier	Nombre de transferts envoyés à cette adresse sur la fenêtre.
data[].last_sent_at	string (ISO 8601)	Date du transfert le plus récent vers cette adresse.
data[].first_sent_at	string (ISO 8601)	Date du premier transfert vers cette adresse sur la fenêtre.
data[].total_files	entier	Somme des fichiers cumulés sur l'ensemble des transferts envoyés à cette adresse.
data[].in_address_book	booléen	`true` si l'adresse figure déjà dans le carnet d'adresses du propriétaire de l'espace.
next_actions	tableau de string	Suggestions d'ajout au carnet d'adresses pour les destinataires récurrents (≥ 3 transferts) absents du carnet, limité à 5 entrées.

Erreurs

Code	Quand	Résolution
401 missing_api_key	Aucun en-tête Authorization fourni et aucune session valide.	Ajoutez l'en-tête `Authorization: Bearer cof_live_...`.
401 invalid_api_key	Préfixe de clé non reconnu, ou clé introuvable.	Vérifiez la clé ou générez-en une nouvelle sur app.coffrify.com/developer.
401 revoked_api_key	Clé révoquée ou désactivée.	Utilisez une clé active.
401 expired_api_key	Clé expirée.	Renouvelez la clé API.
403 scope_missing	La clé ne porte pas le scope `transfers:read` (ni `transfers:` ni ``).	Émettez une clé incluant `transfers:read`.
403 ip_not_allowed	Adresse IP appelante hors de la liste autorisée de la clé.	Appelez depuis une IP autorisée ou élargissez l'allowlist.
429 rate_limited	Quota de débit dépassé sur les endpoints `expensive` de l'espace.	Respectez l'en-tête `Retry-After` et espacez les appels.
500 internal_error	Erreur interne (ex. service de données indisponible).	Réessayez plus tard ; conservez le `request_id` renvoyé pour le support.

Voir aussi

GET /v1/transfers - lister les transferts source de cette agrégation.
GET /v1/recipients - consulter le carnet d'adresses (champ in_address_book).
POST /v1/recipients - ajouter un destinataire suggéré par next_actions.