Diagnostiquer Dolibarr : emailing Framework sans casser l’existant

(Guide complet pour identifier, tester et corriger les problèmes d’envoi d’e‑mail dans Dolibarr tout en préservant la stabilité du système)

1. Contexte et Pourquoi « Tester Sans Casser » ?

Dolibarr est un ERP/CRM open‑source très populaire, mais son moteur d’e‑mail, basé sur la fonction PHP mail() ou sur des bibliothèques SMTP, reste sensible aux petites modifications de configuration serveur.

  • Un mauvais diagnostic peut entraîner : perte d’e‑mails (notifications, factures, relances) → impact business.

  • Une modification directe sur la prod sans sauvegarde augmente le risque de downtime ou de corruption des données.

Le principe de ce guide : diagnostiquer le problème en isolant le composant d’envoi d’e‑mail, valider la solution dans un environnement contrôlé, puis la déployer en production sans interrompre le service.

2. Architecture du Système d’E‑mail dans Dolibarr

Niveau Description Points de Config
1. Core PHP mail() native ou classe PHPMailer intégrée (depuis Dolibarr 13) php.ini → SMTP, smtp_port, sendmail_path
2. Modules Dolibarr Cartes, Factures, Relances, etc. déclenchent html likes ou mail via fonctions sendmail ou trigger Paramètres Setup → Emails → Default email engine, SMTP server, Port, Login, Password
3. Jobs Cron Envois périodiques (rappels, factures récurrentes) crontab → commande php -f /path/to/dolibarr/cron.php
4. CRON cron lance les schedulers qui appellent les scripts de génération d’e‑mail Vérifier l’entrée dans crontab et les logs /var/log/cron*

Bonne pratique : gardez la même version de PHP/SMTP entre dev et prod. Si vous migrez, testez d’abord en mode « mail() » avant d’activer le SMTP complet.

3. Checklist de Diagnostic (Étape par Étape)

3.1 Audit de la Machine (Environnement)

  1. Version Dolibarr : php -r "echo PHP_VERSION; require '/path/to/dolibarr/dolibarr_main.inc.php';"

  2. PHP Config : 
    php -i | grep -i '^\s*sendmail_path\|^\s*SMTP\|^\s*smtp_port'

  3. Logs Apache/Nginx : recherchez les erreurs PHP Fatal error ou SMTP connect() failed.

  4. Logs Dolibarr :

    • /var/www/dolibarr/documents/logs/ → fichier error.log

    • /var/www/dolibarr/var/log/ → cron.log etc.

3.2 Méthodes d’Envoi

Méthode Comment vérifier
mail() (sendmail ou Postfix) Exécuter manuellement : php -r 'mail("test@example.com","Test","body");' puis vérifier la réception.
SMTP (PHPMailer/SMTP intégré) Dans Setup → Emails → Enable SMTP → tester avec le même compte que le serveur utilise.
Cron Jobs Forcer l’exécution : php /path/to/dolibarr/cron.php → observer la console pour les messages “Email envoyé” ou les erreurs.

3.3 Vérifications Fonctionnelles- Modèles d’e‑mail : Aller dans Factures → Modèles > E‑mail → envoyer un test à votre adresse via le bouton “Test”. – Relances / Rappels : Créez une relance manuelle pour vérifier que le mail est généré (pas d’erreur de parsing).

  • Contacts externes : Ajoutez un contact test avec plusieurs adresses (ex: user+dev@domain.com) afin d’observer le filtrage SPAM/RBL.

4. Stratégie de Tests Sans Modifier L’Existant

4.1 Environnements Isolés

Environnement Objectif Tools
Dev (Local) Analyse de la configuration PHP et des modèles Docker (ex: php:8.2-apache), MailHog ou Mailcatcher pour intercepter les e‑mails.
Staging Reproduire exactement le serveur de prod (PHP, Apache, DB, config SMTP) Clone du dépôt Git + base de datos backup.
Production Déploiement final Plan de rollback (Sauvegarde DB + fichiers, version Git tag).

Astuce Dolibarr : ajoutez dans config.php la ligne __('MAIL_DEBUG', 1); pour activer le mode debug des e‑mails. Les messages seront affichés dans le log et dans la console du navigateur (dans la page d’édition du mail).

4.2 Scripts de Test Rapides (PHP)

<?php

require '/var/www/dolibarr/dolibarr_init.php';
// 1. Test simple de fonction mail()

mail('test@example.com', 'Dolibarr Test', 'Ceci est un test depuis '.php_uname()."\n".microtime());
// 2. Envoi via le moteur SMTP de Dolibarr (simuler le trigger)

$dol = new Dolibarr($conf);

$dol->restoreStateFromPrevPrevState(); // charge la session Dolibarr

$dol->sendStdEmail('test@example.com', 'Test Email', 'Le corps du test', 'Test', 'html');
echo "Test terminé – vérifier votre boîte.";

Note : Ce script ne touche aucun enregistrement. Il peut être exécuté en CLI sans interférer avec la production.

4.3 Capture des E‑mails avec MailHog

  • Docker‑Compose : 
    version: "3.8"
    
services:
    
mailhog:
    
  image: mailhog/mailhog
    
  ports: ["1025:1025", "8025:80"]
    
app:
    
  image: your-dolibarr-image
    
  environment:
    
    - SMTP_HOST=mailhog
    
    - SMTP_PORT=1025
    
  depends_on: ["mailhog"]

  • Résultat : Tous les e‑mails sont stockés dans l’UI MailHog (http://localhost:8025) au lieu d’être réellement envoyés.

  • Vérification : Vous pouvez visualiser le corps, les pièces jointes, le From/To et le Subject avant de les envoyer réellement en prod.

5. Procédure de Diagnostic Pas à Pas

Étape Action Résultat Attendu
5.1 Vérifier que mail() fonctionne via CLI Pas d’erreur → "mail()" utilise le MTA du serveur.
5.2 Configurer Dolibarr → Setup → Email → Activer SMTP (même serveur que prod) Les champs doivent être remplis (host, port, login, password, TLS/SSL).
5.3 Créer un Contact Test avec une adresse de test Le champ “E‑mail” doit être l’adresse de votre boîte ou du MailHog.
5.4 Ouvrir Factures → Nouveau → Ajouter le contact test → Envoyer e‑mail → “Envoyer le test” Email reçu (ou visible dans MailHog).
5.5 Vérifier les logs error.log et cron.log pour les messages “SMTP connect” ou “mail() returned false”. Aucun “false” ou “error” → problème résolu.
5.6 Tester le cron : forcer la tâche avec php /path/to/cron.php Les logs doivent afficher “Email sent to …” sans erreur.
5.7 (Optionnel) Désactiver temporairement toutes les fonctions d’envoi via ini_set('disable_functions', 'mail'); pour forcer l’utilisation du moteur par défaut et observer le comportement. Permet d’isoler le problème au niveau de la librairie SMTP.

6. Bonnes Pratiques pour Modifier Sans Casser

  1. Sauvegarde

    • mysqldump -u root -p dbname > backup_$(date +%F).sql

    • tar -czvf dolibarr_$(date +%F).tar.gz /var/www/dolibarr/*

  2. Contrôle de version

    • Créez une branche Git : git checkout -b bugfix/email-smpt

    • Commitez chaque changement et générez un tag avant le déploiement (v1.0.5-rc1).

  3. Déploiement Rolling

    • Si vous avez plusieurs serveurs, déployez un serveur à la fois et vérifiez les logs avant de passer au suivant.

  4. Feature Flag (si votre version le supporte)

    • Ajoutez dans conf/inc_submodule/email.conf une variable ENABLE_SMTP_TEST_MODE = 1; et testez via le switch avant le vrai envoi.

  5. Notifiez les utilisateurs

    • Planifiez une fenêtre de maintenance courte (ex. 15 min) et prévoyez un message de maintenance via la page d’accueil de Dolibarr (Message d’information).

  6. Monitoring Post‑déploiement

    • Activez un alerte sur le taux d’e‑mail échoué (ex. >5% d’échecs en 5 min).

    • Utilisez monit ou systemd pour surveiller le processus php-fpm et le job cron.

7. Exemples de Correctifs Courants

Probème Cause fréquente Solution rapide
Aucun e‑mail envoyé sendmail_path pointe vers un binaire qui n’existe plus ou mail() est désactivé. Modifier php.ini : sendmail_path = "/usr/sbin/sendmail -t -i" puis redémarrer Apache.
E‑mail bloqué en spam L’adresse From n’est pas déclarée dans le domaine SPF/DKIM. Ajouter From: noreply@votre-domaine.com et configurer SPF/DKIM sur le DNS.
Erreur “SMTP connect() failed” Authentification SMTP échoue (mot de passe expiré ou port bloqué). Vérifier lescredentials dans le module Setup → Email et tester via telnet (telnet smtp.example.com 587).
E‑mail “vide” dans les notifications Le template associé ne possède aucun champ PHPDIR/NAME_CLIENT. Copier le template email_template vierge et l’assigner dans Setup → Emails → Default email template.
Cron ne s’exécute pas Le job cron.php n’est pas accessible par l’utilisateur du serveur (permissions). chmod 755 cron.php et s’assurer que le user du cron possède les droits sur /var/www/dolibarr.

8. Checklist Déploiement Sans Risque

✅ Action
1 Sauvegarde du répertoire htdocs/dolibarr + base DB.
2 Créer une branche email-fix-<date> et pousser les changements.
3 Faire un test complet dans l’environnement Staging (envoyer tout type de notification).
4 Activer le mode debug (define('ERROR_REPORTING', E_ALL);) pour capturer les warnings.
5 Déployer un seul nœud de prod, observer les logs avec tail -f /var/log/apache2/error.log.
6 Vérifier les e‑mails envoyés dans la boîte de réception d’un compte test.
7 Wenn tout est OK, déployer les changements sur les nœuds restants (Rolling).
8 Nettoyer la branche et mettre à jour le tag de version.
9 Notifier l’équipe (Slack/Email) que le patch est en production.
10 Surveiller les 24 h suivantes via le tableau de bord de monitoring.

9. Conclusion

Diagnostiquer le framework d’e‑mail de Dolibarr sans perturber les processus en cours est tout à fait réalisable en suivant une approche modulaire, isolée et documentée.

  • Séparez les tests (dev / staging) du code de production.

  • Utilisez des outils de capture d’e‑mail (MailHog, Mailcatcher) et des logs détaillés.

  • Sauvegardez avant toute modification et déployez en mode « rolling » avec un plan de rollback.

  • Validez chaque changement par des tests fonctionnels réels (test de modèle, jobs cron, relances).

En appliquant ces principes, vous pourrez résoudre rapidement les problèmes d’e‑mailage (SMTP, mail(), relances) tout en garantissant la continuité du service pour l’ensemble de vos utilisateurs Dolibarr.

Ressources complémentaires

Ressource Lien
Documentation officielle Dolibarr – Emails https://doc.dolibarr.org/en_US/email
PHPMailer – Guide d’utilisation avec Dolibarr https://github.com/PHPMailer/PHPMailer
MailHog – Documentation https://github.com/vysal/mailhog
Docker‑Compose pour Dolibarr + MailHog https://github.com/technossance/docker-compose-letsencrypt-nginx-proxy-companion/tree/master/examples/dolibarr
Forum Dolibarr – Section « Email troubleshooting » https://forum.dolibarr.org

Bon diagnostic et bon déploiement ! N’hésitez pas à partager vos retours d’expérience dans les forums Dolibarr afin d’enrichir la communauté.

Publications similaires