Importer et exporter des contacts

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 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 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.

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.

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.

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.

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 :

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 pour chacun, ou Ajouter un abonné pour créer le contact et son appartenance à la liste en un seul appel.

Actions groupées

POST /v2/contacts/bulk exécute une action sur 100 contacts au maximum, désignés par leur ID con_ :

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"
  }'

{
  "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 et envoyez des lots de 100.

Export

GET /v2/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 :

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