Email Imports

Vue d'ensemble

Products Manager peut récupérer automatiquement des fichiers de données fournisseurs envoyés par email. Un handler Celery surveille une boîte mail via le protocole IMAP et déclenche un import dès qu'un email contenant une pièce jointe CSV ou Excel est reçu d'un expéditeur autorisé.

Ce mécanisme est particulièrement adapté aux fournisseurs qui envoient régulièrement leurs catalogues ou mises à jour de stock par email, sans intégration FTP ou API. Products Manager prend en charge l'intégralité du flux :

Fournisseur envoie un email avec pièce jointe CSV/Excel
  → Celery Beat poll la boîte IMAP à intervalle régulier
  → Email détecté : expéditeur autorisé, pièce jointe valide
  → Fichier téléchargé et stocké (MinIO/S3)
  → Import déclenché automatiquement (pipeline standard)
  → Email marqué comme lu / déplacé dans un dossier traité
  → Notification import disponible dans le dashboard

Configuration IMAP

Via l'interface

Rendez-vous dans Settings > Imports > Email Source et renseignez la configuration de votre boîte mail d'import.

Vous pouvez également configurer des sources email au niveau d'un import spécifique dans Imports > [nom de l'import] > Configuration > Source > Email.

Via les variables d'environnement

Pour une configuration globale par défaut :

EMAIL_IMPORT_HOST=imap.example.com
EMAIL_IMPORT_PORT=993
EMAIL_IMPORT_USER=imports@votreentreprise.com
EMAIL_IMPORT_PASSWORD=motdepasse
EMAIL_IMPORT_FOLDER=INBOX
EMAIL_IMPORT_INTERVAL=300

Recommandation : utilisez une boîte mail dédiée aux imports, distincte de vos boîtes opérationnelles. Cela simplifie le filtrage et la sécurité.

Filtrage des emails

Tous les emails reçus sur la boîte surveillée ne déclenchent pas nécessairement un import. Plusieurs filtres sont appliqués :

Expéditeurs autorisés (whitelist)

Seuls les emails provenant d'adresses ou de domaines explicitement listés sont traités. Configurez la whitelist dans Settings > Imports > Email Source > Allowed Senders :

fournisseur-a@example.com
@fournisseur-b.fr          # Tous les expéditeurs du domaine
exports@supplier-c.com

Tout email reçu d'un expéditeur non listé est ignoré (et optionnellement marqué comme lu pour ne pas être retraité).

Filtrage par sujet (subject patterns)

Vous pouvez configurer des patterns (expressions régulières) pour n'accepter que les emails dont le sujet correspond :

Catalogue .*\d{4}
Export produits
Weekly stock update

Types de fichiers acceptés

Par défaut, Products Manager accepte les pièces jointes avec les extensions suivantes :

• .csv
• .xlsx, .xls
• .tsv
• .zip (archive contenant un CSV/Excel)

Les autres types de fichiers (PDF, images, etc.) sont ignorés même si présents en pièce jointe.

Sécurité

Validation MIME

Le type MIME déclaré de la pièce jointe est vérifié et doit correspondre au type attendu pour l'extension. Un fichier .csv avec un MIME type application/octet-stream suspect est accepté avec avertissement ; un type application/x-executable serait rejeté.

Taille maximale

Une taille maximale de pièce jointe est configurable (par défaut : 50 Mo) :

EMAIL_IMPORT_MAX_ATTACHMENT_SIZE=52428800  # 50 Mo en octets

Les emails contenant des pièces jointes trop volumineuses sont ignorés avec une alerte dans les logs.

Whitelisting des expéditeurs

La whitelist des expéditeurs est le principal mécanisme de sécurité. Sans whitelist configurée, les emails imports sont désactivés pour éviter tout import non autorisé.

Authentification IMAP

Utilisez de préférence un token d'application plutôt que le mot de passe principal de la boîte mail (notamment pour Gmail ou Outlook avec MFA activé). Ces tokens ont des permissions limitées et peuvent être révoqués indépendamment.

Monitoring

Dashboard Imports

Chaque email traité est tracé dans le dashboard Imports > Historique. Pour chaque import déclenché par email, vous pouvez consulter :

• L'expéditeur et le sujet de l'email source
• La date et heure de réception
• Le nom de la pièce jointe importée
• Le statut de l'import (succès, erreurs, lignes traitées)

Logs Celery

Les logs détaillés du handler email sont visibles dans les logs du worker Celery :

[2026-03-23 08:00:01] INFO  email_import: Polling INBOX (imports@example.com)
[2026-03-23 08:00:02] INFO  email_import: 1 new email(s) found
[2026-03-23 08:00:02] INFO  email_import: Processing email from fournisseur@example.com — "Catalogue Mars 2026"
[2026-03-23 08:00:03] INFO  email_import: Attachment "catalogue_mars_2026.xlsx" (2.3 MB) saved to storage
[2026-03-23 08:00:03] INFO  email_import: Import task queued — task_id: abc123

Cas d'usage typique

Fournisseur qui envoie son catalogue chaque lundi matin

Un fournisseur configure son ERP pour envoyer automatiquement un export Excel de son catalogue tous les lundis à 7h00 à l'adresse imports@votreentreprise.com.

Configuration dans Products Manager :

1. Boîte IMAP imports@votreentreprise.com surveillée avec un intervalle de 5 minutes.
2. Expéditeur exports@fournisseur.com ajouté à la whitelist.
3. Un profil d'import est créé avec le mapping des colonnes correspondant au format Excel du fournisseur.
4. Ce profil d'import est associé à la source email.

Dès 7h00 le lundi, le catalogue est récupéré et importé automatiquement. Une notification est envoyée à l'équipe catalogue une fois l'import terminé. Aucune intervention manuelle n'est nécessaire.

Dépannage

Connexion IMAP refusée

• Vérifiez le serveur (EMAIL_IMPORT_HOST) et le port (EMAIL_IMPORT_PORT).
• Port 993 : SSL/TLS direct (recommandé). Port 143 : STARTTLS. Assurez-vous que votre configuration correspond au mode supporté par votre serveur.
• Pour Gmail : activez l'accès IMAP dans les paramètres Gmail et utilisez un token d'application (le mot de passe principal est bloqué si MFA est activé).
• Pour Outlook/Office 365 : vérifiez que l'IMAP n'est pas désactivé par la politique d'administration Exchange.

Les emails sont reçus mais aucun import n'est déclenché

• Vérifiez que l'expéditeur est bien dans la whitelist des expéditeurs autorisés.
• Vérifiez que le dossier surveillé (EMAIL_IMPORT_FOLDER) correspond au dossier de réception réel. Sur certains serveurs, le dossier est INBOX, sur d'autres Boîte de réception ou Inbox.
• Vérifiez les logs Celery pour voir si le polling fonctionne et si des emails sont détectés.

Les pièces jointes ne sont pas reconnues

• Vérifiez l'extension du fichier (.csv, .xlsx…).
• Certains fournisseurs envoient des fichiers .txt contenant du CSV — vous pouvez ajouter .txt aux extensions acceptées dans la configuration avancée.
• Si le fichier est envoyé dans un ZIP : vérifiez que l'extraction ZIP est activée et que le fichier à l'intérieur de l'archive a une extension reconnue.

Emails traités plusieurs fois

• Vérifiez que le handler marque bien les emails comme lus après traitement. Si le worker Celery redémarre entre deux polls, un email peut être retraité si le marquage IMAP n'a pas été persisté. Le système de déduplication basé sur le Message-ID email évite les doubles imports dans la majorité des cas.