> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Les contacts sont vos abonnés, clients et prospects dans Notifuse. Chacun a un profil, des champs personnalisés et un historique d'engagement.

![Interface des contacts : la liste des contacts avec ses champs et les options de données personnalisées](https://www.notifuse.com/docs/assets/screenshots/contacts.png)

## Vue d'ensemble

Un contact enregistre le profil d'un abonné, ses préférences et ses données d'engagement dans des champs prédéfinis et personnalisés. Il peut appartenir à plusieurs listes de diffusion.

## Champs d'un contact

| Champ                                                    | Type                  | Description                                                                                                                                                                  |
| -------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                                                  | Chaîne                | Adresse email du contact, qui sert aussi d'identifiant unique (**Requis**)                                                                                                   |
| `external_id`                                            | Chaîne                | Référence facultative au contact dans votre propre système. N'est pas unique (voir [Identité du contact](#contact-identity-and-upsert-behavior))                             |
| `first_name`                                             | Chaîne                | Prénom du contact                                                                                                                                                            |
| `last_name`                                              | Chaîne                | Nom de famille du contact                                                                                                                                                    |
| `phone`                                                  | Chaîne                | Numéro de téléphone                                                                                                                                                          |
| `timezone`                                               | Chaîne                | Fuseau horaire ISO du contact                                                                                                                                                |
| `language`                                               | Chaîne                | Langue préférée                                                                                                                                                              |
| `job_title`                                              | Chaîne                | Intitulé du poste                                                                                                                                                            |
| `address_line_1`                                         | Chaîne                | Adresse principale                                                                                                                                                           |
| `address_line_2`                                         | Chaîne                | Complément d'adresse (appartement, bureau, etc.)                                                                                                                             |
| `country`                                                | Chaîne                | Pays au format ISO                                                                                                                                                           |
| `state`                                                  | Chaîne                | État ou province                                                                                                                                                             |
| `postcode`                                               | Chaîne                | Code postal                                                                                                                                                                  |
| `custom_string_1` à `custom_string_5`                    | Chaîne                | Champs texte personnalisés                                                                                                                                                   |
| `custom_number_1` à `custom_number_5`                    | Nombre                | Champs numériques personnalisés                                                                                                                                              |
| `custom_datetime_1` à `custom_datetime_5`                | Date et heure         | Champs date et heure personnalisés                                                                                                                                           |
| `custom_json_1` à `custom_json_5`                        | JSON                  | Champs JSON personnalisés                                                                                                                                                    |
| `tracking_opens_consent`, `tracking_clicks_consent`      | Chaîne                | `granted`, `denied` ou `null` (inconnu) : le choix du contact concernant le [suivi des ouvertures et des clics](https://www.notifuse.com/fr/docs/features/email-tracking.md) |
| `tracking_consent_updated_at`, `tracking_consent_source` | Date et heure, chaîne | Date et origine du dernier changement de ce choix                                                                                                                            |

## La fiche du contact

Cliquer sur un contact dans le tableau ouvre sa fiche par-dessus la page. La fiche a sa propre adresse (l'URL de la page suivie de `?contact=` et de l'email), que vous pouvez partager ou rouvrir. Si vous l'avez ouverte depuis le tableau, le bouton Retour du navigateur la ferme.

![La fiche d'un contact, avec ses chiffres clés, sa chronologie d'activité et ses champs de profil](https://www.notifuse.com/docs/assets/screenshots/contact_profile.png)

- **Parcourez le tableau** avec les flèches en haut de la fiche, ou avec **J** (suivant) et **K** (précédent). La fiche suit dans l'ordre les lignes de la vue d'où vous l'avez ouverte, et en charge d'autres quand vous arrivez à la dernière.
- **Modifiez un champ** en cliquant sur sa valeur. Les champs vides sont regroupés sous un lien en bas de chaque panneau.
- **Chiffres clés** : emails reçus, taux d'ouverture et de clic, dernière activité et, si l'analyse web est activée, visites du site.
- **Activité** : la chronologie du contact, filtrable par type (emails, listes et segments, modifications du profil, événements, visites web).
- **Messages** : les emails envoyés au contact.
- **Visites web** : les visites du contact sur votre site, quand l'[analyse web](https://www.notifuse.com/fr/docs/web-analytics/identifying-visitors.md#on-the-contact-sheet) est activée.
- **Listes et segments** : les abonnements du contact, que vous pouvez modifier, et les segments auxquels il appartient.

![Le haut de la fiche d'un contact : nom, email et date d'inscription, puis emails reçus, taux d'ouverture, taux de clic, dernière activité et visites du site](https://www.notifuse.com/docs/assets/screenshots/contacts_key_figures.png)

## Gestion des contacts

### Identité du contact et comportement de l'upsert

L'**adresse email est l'identifiant unique d'un contact** : c'est la clé primaire en base de données. Chaque upsert (`contacts.upsert`, `contacts.import` et le contact inclus dans `transactional.send`) retrouve les contacts par leur adresse email, et uniquement par elle :

- **Adresse inconnue** : un nouveau contact est créé
- **Adresse existante** : le contact existant est mis à jour avec les champs fournis
- **Valeurs nulles** : mettre un champ à `null` efface cette valeur du contact

`external_id` est une référence facultative au contact dans votre propre système (par exemple l'identifiant utilisateur de votre application). Il est enregistré, consultable par la recherche et renvoyé par l'API, mais ce n'est **pas une clé unique** :

- Il ne sert jamais à retrouver un contact lors d'un upsert.
- Notifuse n'empêche pas plusieurs contacts de partager le même `external_id`.
- Si plusieurs contacts partagent le même `external_id`, `contacts.getByExternalID` n'en renvoie qu'un seul, sans que l'on sache lequel.

### Changer l'adresse email d'un contact

L'adresse email fait l'identité du contact. Un upsert avec le même `external_id` et une nouvelle adresse **crée donc un second contact**, et l'adresse du contact existant ne change pas. Quand un utilisateur change d'adresse email dans votre système :

1. Récupérez l'ancien contact avec `contacts.getByEmail` pour obtenir son profil et ses abonnements aux listes avec leurs statuts.
2. Faites l'upsert d'un contact avec la **nouvelle** adresse email en envoyant le profil complet. Un upsert fusionne les champs : incluez tous ceux que vous voulez garder, comme `external_id`, les noms et les champs personnalisés.
3. Recréez les abonnements aux listes sur le nouveau contact avec `lists.subscribe`.
4. Supprimez le contact à l'**ancienne** adresse email avec `contacts.delete`.

> [!WARNING]
>
> Conservez les statuts de désabonnement en recréant les abonnements. Si l'ancien contact s'était
> désabonné d'une liste, ou si son adresse y avait été rejetée ou avait porté plainte, ne réabonnez
> **pas** la nouvelle adresse à cette liste. Le nouveau contact part de zéro : le réabonner sans
> vérifier annule en silence un désabonnement. C'est une violation du consentement (RGPD / CAN-SPAM),
> qui peut aussi nuire à votre réputation d'expéditeur.

Gardez aussi en tête :

- **L'historique des messages et l'appartenance aux segments** sont rattachés à l'adresse email. Ils restent liés à l'ancienne adresse et ne passent pas au nouveau contact.
- **Les automations en cours** : supprimer l'ancien contact le retire de toute automation qu'il est en train de suivre, et le nouveau contact ne reprend pas à la même étape.

### Supprimer un contact

Supprimer un contact avec `contacts.delete` supprime aussi ses abonnements aux listes, y compris les statuts désabonné, rejeté et plainte. Notifuse oublie alors que l'adresse s'était désinscrite. Un import ultérieur, un upsert avec `subscribe_to_lists` ou un appel à `lists.subscribe` rajoute l'adresse comme nouveau contact abonné. Pour continuer à respecter un désabonnement, passez le statut du contact sur la liste à désabonné au lieu de le supprimer.

Un lien de désabonnement dans un email envoyé avant la suppression répond toujours avec succès, mais n'enregistre rien sur l'adresse.

### Abonnements aux listes

- Un contact peut s'abonner à une ou plusieurs listes de diffusion
- Le statut d'abonnement se gère liste par liste
- Les appartenances aux listes sont suivies dans la relation `contact_lists`

## Moteur de segmentation des contacts

![Interface de segmentation : filtres sur les propriétés des contacts et conditions basées sur l'activité](https://www.notifuse.com/docs/assets/screenshots/segment_form.png)

Notifuse segmente les contacts selon leurs propriétés et leur engagement. L'appartenance aux segments est calculée en arrière-plan, pas en temps réel. Quand un élément arrive dans la chronologie d'un contact (une modification du profil, un email ouvert, un événement personnalisé), le contact entre dans une file d'attente.

Une tâche récurrente traite cette file, si bien qu'un changement apparaît en général dans les segments du contact en moins d'une minute. Les segments à dates relatives, comme « dans les 30 derniers jours », sont aussi recalculés chaque jour à 5 h dans le fuseau horaire du segment.

### Créer des segments

Un segment se construit à partir des types de conditions suivants.

#### Conditions sur les propriétés du contact

Filtrez les contacts sur les données de leur profil :

- **Champs texte** : email, noms, téléphone, pays, langue, fuseau horaire, adresse, intitulé du poste, consentement au suivi et son origine, champs texte personnalisés. Opérateurs : est défini, n'est pas défini, égal à, n'est pas égal à, contient (une ou plusieurs valeurs), ne contient pas.
- **Champs numériques** : champs numériques personnalisés. Opérateurs : est défini, n'est pas défini, égal à, n'est pas égal à, supérieur ou inférieur à (ou égal à).
- **Champs date** : dates de création et de mise à jour, date du consentement au suivi, champs date personnalisés. Opérateurs : est défini, n'est pas défini, avant, après, entre, pas entre, dans les N derniers jours, pas dans les N derniers jours (ce dernier inclut aussi les contacts dont la date n'a jamais été renseignée).
- **Champs JSON** : champs JSON personnalisés, lus à un chemin de clés et d'index de tableau, comme texte, nombre ou date. En texte, l'opérateur « est dans le tableau » s'ajoute ; en date, vous avez avant, après, égal à et les opérateurs sur les N derniers jours.

Tous les filtres d'une même condition doivent correspondre. Chaque filtre se modifie sur place, et une condition ne peut pas être validée tant qu'un de ses filtres est incomplet.

#### Conditions sur les objectifs

Créez des segments RFM (récence, fréquence, montant) à partir des [événements personnalisés et objectifs](https://www.notifuse.com/fr/docs/features/custom-events.md) :

- **Montant** : dépense totale, panier moyen
- **Fréquence** : nombre d'achats, nombre d'événements
- **Récence** : activité sur une période donnée

Exemples de segments : clients VIP (plus de 1000 $ dépensés), clients fidèles (3 commandes ou plus), clients à risque (aucun achat depuis 90 jours).

#### Conditions sur l'activité

Ciblez les contacts selon leur engagement avec vos emails et votre site web :

- **Email envoyé** : un email a été envoyé au contact
- **E-mail ouvert** : le contact a ouvert un email
- **E-mail cliqué** : le contact a cliqué sur un lien d'un email, éventuellement un lien dont l'adresse contient un texte donné. Pour les emails envoyés à partir de la version 42.2, le contact entre dans le segment dès qu'il clique sur ce lien, même si ce n'est pas le premier lien qu'il a cliqué dans l'email
- **Email rejeté** : un email a été rejeté pour ce contact
- **Plainte sur l’e-mail** : le contact a signalé un email comme spam
- **S’est désabonné depuis un e-mail** : le contact s'est désabonné via un email
- **Voir la page web** : le contact a vu une page de votre site, filtrable par chemin, temps passé sur la page et profondeur de défilement
- **Visiter le site web** : le contact a fait une visite, filtrable par page d'entrée et de sortie, pages vues, durée, canal, campagne, appareil et pays

Les deux conditions sur le site web demandent l'[analyse web](https://www.notifuse.com/fr/docs/web-analytics/setup.md) et un visiteur [identifié](https://www.notifuse.com/fr/docs/web-analytics/identifying-visitors.md).

Les conditions sur l'activité acceptent des paramètres supplémentaires :

- **Fréquence** : au moins, au plus ou exactement un nombre de fois
- **Période** : n'importe quand, entre deux dates, avant ou après une date, ou dans les N derniers jours
- **Modèle et newsletter** (toutes les activités email, Email envoyé compris) : ne compter que les emails envoyés avec un modèle donné, ou par une newsletter donnée
- **Lien cliqué** (E-mail cliqué) : ne compter que les clics sur les liens qui contiennent un texte donné, comme `/pricing`

### Logique des conditions

Un segment combine ses conditions avec une logique ET ou OU :

- **Toutes les conditions suivantes** : le contact doit remplir chaque condition (logique ET)
- **Au moins une des conditions suivantes** : le contact doit remplir une condition ou plus (logique OU)

Les conditions peuvent être regroupées, chaque groupe ayant son propre « toutes les » ou « au moins une des », et les groupes peuvent s'imbriquer.

### Cas d'usage

Situations courantes :

- **Clients VIP** : gros acheteurs avec plusieurs achats (conditions sur les objectifs)
- **Réengagement** : relancer les abonnés inactifs qui n'ont ouvert aucun email depuis 90 jours
- **Clients à risque** : acheteurs autrefois actifs sans achat récent
- **Ciblage géographique** : envoyer des campagnes propres à une région selon le pays ou l'État
- **Déclencheurs comportementaux** : cibler les utilisateurs qui ont cliqué sur des liens produit précis

### Détails techniques

Le moteur de segmentation lit la chronologie des contacts apparue en version 7.0, qui enregistre chaque interaction d'un contact, y compris les messages, les événements webhook et les modifications du profil. Chaque événement d'activité a un `kind` (par exemple `email.opened`, `email.clicked`, `web.pageview`) que les conditions peuvent cibler. Les horodatages sont stockés en UTC, et les conditions sur les dates peuvent les évaluer dans le fuseau horaire de votre choix.

### Permissions des segments

Les segments ont leur propre permission **Segments** : la **lecture** permet de lister les segments et d'en ouvrir un ; l'**écriture** permet de les créer, de les modifier, de les supprimer et de les recalculer, ainsi que de lancer, réinitialiser ou supprimer leurs tâches de calcul en arrière-plan.

L'aperçu d'un segment pendant sa création et la liste des contacts qu'un segment contient à un instant donné demandent aussi la permission **Contacts** en lecture. Ces deux actions renseignent en effet sur vos contacts, et non sur la définition du segment. Un membre qui n'a que Segments en lecture peut travailler sur les définitions de segments, mais ne voit pas qui en fait partie.

L'aperçu accepte n'importe quelle définition, pas seulement un segment enregistré. Une personne qui a Segments en lecture et Contacts en lecture peut donc poser des questions de comptage sur n'importe quel attribut de contact, appartenance à une liste, événement personnalisé ou entrée de chronologie, un comptage à la fois.

## Importer des contacts depuis un CSV

![Import CSV : chaque colonne du fichier avec des exemples de valeurs et le champ du contact dans lequel elle est importée](https://www.notifuse.com/docs/assets/screenshots/import_csv.png)

L'import se déroule en trois étapes : déposez un fichier CSV, associez ses colonnes, puis suivez l'import.

### Associer les colonnes

La première ligne du fichier contient les noms des colonnes, et une colonne doit contenir les adresses email. Chaque colonne s'affiche avec des exemples de valeurs tirés des premières lignes. Une colonne nommée d'après un champ de contact, par sa clé (`first_name`) ou son libellé (`First Name`), est associée automatiquement.

Vous pouvez associer n'importe quelle colonne à un champ standard ou personnalisé, ou la laisser sur **Ne pas importer**. Chaque champ ne reçoit qu'une colonne, et l'import reste désactivé tant qu'aucune colonne n'est associée à l'email.

Les colonnes de consentement acceptent `granted` ou `denied`, et les champs JSON personnalisés attendent du JSON valide. Un contact déjà présent dans l'espace de travail est retrouvé par son email et mis à jour : chaque champ présent dans la ligne remplace la valeur enregistrée.

### Ajouter à des listes

Chaque contact importé est abonné aux listes que vous choisissez, une ou plusieurs.

### Suivre l'import

Les lignes sont envoyées par lots de 100, et l'import compte les contacts créés, mis à jour et en échec. Chaque ligne en échec est listée avec son numéro de ligne dans votre fichier et la raison. **Télécharger les lignes en échec** vous donne ces lignes avec une colonne `error`, pour les corriger et les importer à nouveau.

L'import s'exécute dans votre navigateur. Vous pouvez le mettre en pause ou l'arrêter ; fermer le panneau ou l'onglet l'arrête aussi. Sa progression est gardée dans ce navigateur pendant 7 jours : l'étape Fichier liste les imports inachevés, et déposer de nouveau le même fichier propose de reprendre à la ligne où il s'est arrêté, avec la même association de colonnes et les mêmes listes.

### Permissions de l'import

Importer demande la permission **Contacts** en écriture. Choisir une ou plusieurs listes de diffusion pendant l'import demande aussi **Listes** en écriture.

Chaque champ présent dans une ligne remplace la valeur enregistrée sur le contact correspondant : un seul import peut donc réécrire toute votre base de contacts. Accordez Contacts en écriture en connaissance de cause.

## Mise à jour en masse depuis un CSV

**Mise à jour en masse (CSV)**, dans le menu ⋯ de la page Contacts, applique une même action à chaque contact dont l'adresse figure dans une colonne d'un CSV :

- **Désabonner d'une liste** passe l'abonnement des contacts à cette liste au statut désabonné. Ils restent dans l'espace de travail et peuvent se réabonner. Un contact qui n'est pas dans la liste est ignoré.
- **Supprimer les contacts** retire les contacts et leur historique de l'espace de travail. Cette action est irréversible.

![Mise à jour en masse depuis un CSV : l'action Désabonner d'une liste avec la liste Newsletter, le fichier et sa colonne d'emails, les premières adresses, et un résumé de 49 lignes, 2 doublons retirés et 1 ligne sans email valide, soit 46 contacts](https://www.notifuse.com/docs/assets/screenshots/bulk_update_csv.png)

La colonne dont le nom contient « mail » est choisie automatiquement, et vous pouvez en prendre une autre. Les adresses sont passées en minuscules et chacune n'est traitée qu'une fois. Avant le lancement, le résumé compte les lignes du fichier, les doublons retirés et les lignes sans adresse valide.

La mise à jour s'exécute dans votre navigateur, un contact à la fois. Chaque adresse est marquée comme traitée, ignorée ou en échec ; vous pouvez télécharger les résultats en CSV et relancer les échecs. Une mise à jour arrêtée peut reprendre à partir du même fichier.

Désabonner demande la permission **Listes** en écriture en plus de **Contacts** en écriture ; supprimer demande **Contacts** en écriture.

## Permissions

Les données des contacts relèvent de la permission **Contacts** :

- **Lecture** couvre les fiches des contacts et leurs profils complets, la chronologie des contacts et les événements personnalisés enregistrés sur les contacts. Avec la permission Listes ou Segments correspondante, elle est aussi nécessaire pour lister les adresses d'une liste ou d'un segment. Elle est également requise pour renseigner `cc` ou `bcc` lors d'un envoi transactionnel.
- **Écriture** couvre la création et la mise à jour des contacts, le fait de les **supprimer** définitivement ou de les **écraser en masse** par un import CSV ou API, et l'enregistrement d'événements personnalisés. Changer le statut d'abonnement d'un contact à une liste demande aussi Listes en écriture.

Sur la fiche du contact, chaque partie demande sa propre permission : **Messages** demande Historique des messages en lecture, **Visites web** demande Analyse web en lecture (avec l'analyse web activée), et les panneaux des listes et des segments demandent Listes en lecture et Segments en lecture. Sans Contacts en écriture, les champs ne sont pas modifiables.

Trois permissions donnent accès aux données des contacts sans Contacts en écriture. Vérifiez-les avant d'accorder l'une d'elles :

- **Listes en écriture**, à elle seule, crée ou remplace une fiche de contact complète : `/api/lists.subscribe` écrit chaque champ présent dans la requête, et peut abonner quelqu'un à une liste qui n'est pas publique.
- **Automations en écriture** envoie la fiche complète du contact à toute URL indiquée par un nœud webhook, et aucune permission n'est vérifiée pendant l'exécution d'une automation.
- **Transactionnel en écriture** crée le contact destinataire au moment de l'envoi. Sans Contacts en écriture, seule l'adresse email est enregistrée et un contact existant n'est jamais modifié (voir [API transactionnelle](https://www.notifuse.com/fr/docs/features/transactional-api.md#permissions)).

## Fonctionnalités principales

- Les champs prédéfinis couvrent la plupart des besoins, et les champs personnalisés couvrent le reste.
- Les upserts retrouvent les contacts par leur adresse email : une même adresse ne crée jamais deux contacts.
- Un contact peut appartenir à plusieurs listes de diffusion.
- Mettre un champ à `null` l'efface.
