# Importer et exporter des contacts

> Importez des contacts depuis un fichier CSV ou Excel avec l’assistant d’import, exportez des contacts filtrés en CSV ou XLSX, et lancez des actions groupées et des exports via l’API.

Utilisez l’assistant d’import pour ajouter des contacts depuis une feuille de calcul, et l’export pour télécharger les contacts qui correspondent à vos filtres actuels. Cette page présente aussi les actions groupées et l’endpoint d’export de l’API, qui permettent de faire la même chose depuis votre code.

## Avant de commencer

- Créez les [champs personnalisés](/fr/docs/contacts/custom-fields/) que vous voulez remplir à partir du fichier. L’assistant ne peut associer les colonnes qu’à des champs qui existent déjà.
- Créez les [listes de contacts](/fr/docs/audiences/) que les contacts doivent rejoindre. Les imports comptent dans la limite d’abonnés de chaque liste.
- N’importez que des personnes qui ont accepté de recevoir vos e-mails. L’examen de l’accès production demande comment vous collectez vos abonnés. Consultez [Accès production](/fr/docs/workspaces/production-access/).

## Préparer votre fichier

L’assistant lit les fichiers `.csv`, `.xlsx` et `.xls` contenant jusqu’à **2 500 contacts par fichier**. Découpez les listes plus longues en plusieurs fichiers.

```csv title="contacts.csv"
email,first_name,last_name,company,birthday
ada@example.com,Ada,Lovelace,Acme,1990-04-12
grace@example.com,Grace,Hopper,Acme,1906-12-09
alan@example.com,Alan,Turing,,
```

Conseils pour un import propre :

- **Placez un contact par ligne** et les noms des colonnes sur la première ligne. Seule la première feuille des fichiers Excel est lue.
- **Nommez les colonnes d’après vos champs** pour que l’assistant les associe à votre place. Un en-tête de colonne est associé automatiquement lorsqu’il correspond au nom ou à la clé d’un champ, sans tenir compte de la casse, par exemple `email`, `First name`, `first_name` ou une clé de champ personnalisé comme `company`.
- **Enregistrez les fichiers CSV en UTF-8** pour que les noms accentués soient correctement importés.
- **Écrivez les dates au format `YYYY-MM-DD`.** Les cellules de date des fichiers Excel fonctionnent aussi. Les autres formats de date sont rejetés.
- **Vérifiez les adresses.** Une seule adresse e-mail invalide interrompt tout l’import, avec une erreur qui indique la ligne, par exemple « Contact #12 has an invalid email address. ». Les lignes dont la cellule e-mail est vide sont ignorées.
- **Les valeurs à choix multiple** sont importées sous forme d’une seule valeur texte. Pour stocker plusieurs options sous forme de liste, définissez-les via l’API.

## Importer des contacts

1. **Ouvrez l’assistant.** Accédez à **Email Marketing → Contacts** et sélectionnez **Import**.

2. **Choisissez le fichier.** Sous **CSV File**, sélectionnez votre fichier. Laissez **File has header** coché si la première ligne contient les noms des colonnes. L’assistant affiche les premières lignes et le nombre total de lignes, avec un avertissement si le fichier dépasse 2 500 lignes. Sélectionnez **Continue**.

3. **Associez les colonnes.** Pour chaque colonne, choisissez le champ de contact qu’elle remplit : **Email**, **First name**, **Last name**, l’un de vos champs personnalisés, ou **Exclude** pour l’ignorer. Vous devez associer une colonne à **Email**. Chaque ligne affiche des exemples de valeurs pour vérifier l’association.

4. **Choisissez les listes.** Sous **Audiences**, choisissez les listes que les contacts doivent rejoindre, ou laissez le champ vide pour importer les contacts sans les ajouter à une liste. Sélectionnez **Continue**.

5. **Vérifiez et importez.** L’aperçu affiche le fichier, le nombre de contacts, les listes, l’association des colonnes et les 10 premiers contacts tels qu’ils seront enregistrés. Sélectionnez **Import**.

Emailit valide d’abord l’ensemble du fichier. En cas de problème, comme une adresse invalide, un champ personnalisé inconnu ou une liste pleine, rien n’est importé et les erreurs sont listées pour que vous puissiez corriger le fichier. Sinon, l’import s’exécute en arrière-plan par lots de 500. Actualisez la liste Contacts après quelques instants pour voir les nouveaux contacts.

### Ce qui arrive aux contacts existants

Les contacts sont rapprochés par adresse e-mail, sans tenir compte de la casse.

| Cas | Résultat |
| --- | --- |
| L’adresse est nouvelle | Un contact est créé. |
| L’adresse existe déjà | Le contact est mis à jour. Les noms ne sont remplacés que si le fichier contient une valeur. Les valeurs de champs personnalisés du fichier remplacent celles enregistrées, et une cellule vide dans une colonne associée à un champ personnalisé efface ce champ. Les autres champs personnalisés sont conservés. |
| L’adresse figure deux fois dans le fichier | Les deux lignes sont appliquées dans l’ordre : la dernière l’emporte. |
| Le contact n’est pas encore dans la liste sélectionnée | Il rejoint la liste en tant qu’abonné. |
| Le contact s’était désinscrit de la liste sélectionnée | Il est de nouveau inscrit à cette liste. |

> **Les imports réinscrivent les personnes:** Importer un contact dans une liste dont il s’est désinscrit le réinscrit. Avant d’importer dans une liste existante, retirez de votre fichier les personnes qui se sont désinscrites, ou importez sans choisir cette liste.

Quelques autres points à connaître :

- La liste d’association comprend **Unsubscribed**, mais l’import ne l’applique pas. Pour marquer les personnes importées comme désinscrites, sélectionnez-les ensuite dans la liste Contacts et utilisez l’action groupée **Unsubscribe**.
- Les imports n’envoient pas d’événements webhook `contact.*` ou `subscriber.*`, et ne démarrent pas d’automatisations comme **Added to audience**.
- Si une liste devait dépasser sa limite d’abonnés, l’import est rejeté avec la limite indiquée dans le message, par exemple « Pay as you go includes 10,000 subscribers per audience. ». Consultez [Listes de contacts](/fr/docs/audiences/#limits).

## Exporter des contacts

1. **Restreignez la liste.** Sur **Email Marketing → Contacts**, utilisez la recherche et **Filter** pour afficher les contacts voulus. Sans recherche ni filtre, l’export inclut tous les contacts.

2. **Exportez.** Sélectionnez **Export** et choisissez **CSV** ou **XLSX**. Votre navigateur télécharge `contacts.csv` ou `contacts.xlsx`.

Un export peut inclure jusqu’à **10 000 contacts**. Si davantage de contacts correspondent, l’export échoue : ajoutez des filtres, comme une liste ou une plage de dates de création, et exportez en plusieurs fois.

Le fichier contient une ligne par contact et ces colonnes :

| Colonne | Valeur |
| --- | --- |
| `email` | L’adresse e-mail du contact. |
| `first_name`, `last_name` | Les noms du contact. |
| `unsubscribed` | `true` si le statut marketing est **Unsubscribed**, sinon `false`. |
| `audiences` | Les noms de toutes les listes dont le contact fait partie, séparés par `; `. |
| Une colonne par clé de champ personnalisé | La valeur stockée. Les valeurs à choix multiple sont jointes avec `;`. |
| `created_at`, `updated_at` | Horodatages ISO 8601. |

## Utiliser l’API

L’API ne permet pas d’importer de fichier. Pour ajouter de nombreux contacts depuis votre code, appelez [Créer un contact](/fr/docs/api-reference/contacts/create/) pour chacun, ou [Ajouter un abonné](/fr/docs/api-reference/audiences/subscribers/add/) pour créer le contact et son appartenance à la liste en un seul appel.

### Actions groupées

[`POST /v2/contacts/bulk`](/fr/docs/api-reference/contacts/bulk/) exécute une action sur 100 contacts au maximum, désignés par leur ID `con_` :

| `action` | Effet | Nécessite `audience_id` |
| --- | --- | --- |
| `add_to_audience` | Ajoute les contacts à la liste. Les contacts avec `unsubscribed: true` la rejoignent en tant que désinscrits. | Oui |
| `remove_from_audience` | Supprime leur appartenance à la liste. | Oui |
| `unsubscribe` | Définit `unsubscribed: true` (statut marketing **Unsubscribed**). | Non |
| `resubscribe` | Définit `unsubscribed: false`. | Non |
| `delete` | Supprime les contacts et leurs appartenances aux listes. | Non |

```bash
curl https://api.emailit.com/v2/contacts/bulk \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add_to_audience",
    "ids": ["con_2kq8Vt4xLm7Rz", "con_9fW3pQ1nBc6Yt"],
    "audience_id": "aud_5hJ2kL8mNp4Qr"
  }'
```

```json
{
  "object": "contact_bulk",
  "action": "add_to_audience",
  "processed": 2,
  "ids": ["con_2kq8Vt4xLm7Rz", "con_9fW3pQ1nBc6Yt"]
}
```

La requête échoue entièrement si `ids` contient plus de 100 entrées (`400`) ou si un contact ou la liste n’existe pas (`404`, avec les ID inconnus dans `missing`). Pour traiter davantage de contacts, parcourez les pages de [Lister les contacts](/fr/docs/api-reference/contacts/list/) et envoyez des lots de 100.

### Export

[`GET /v2/contacts/export`](/fr/docs/api-reference/contacts/export/) renvoie le même fichier que le tableau de bord. Définissez `format` sur `csv` (par défaut) ou `xlsx`, et ajoutez les filtres, la recherche et le tri de [Lister les contacts](/fr/docs/api-reference/contacts/list/) :

```bash
curl "https://api.emailit.com/v2/contacts/export?format=csv&audience_id=aud_5hJ2kL8mNp4Qr&unsubscribed=false" \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -o contacts.csv
```

Si plus de 10 000 contacts correspondent, l’endpoint renvoie `422` avec « Export is limited to 10000 contacts. Narrow your filters and try again. »

## Voir aussi

  - [Champs personnalisés](/fr/docs/contacts/custom-fields/): Définissez les champs auxquels vos colonnes sont associées.
  - [Abonnés](/fr/docs/audiences/subscribers/): Gérez les personnes présentes dans chaque liste.

---
Source: https://emailit.com/fr/docs/contacts/import-export/