Guide du module Client Webmail pour Larapen

Un client webmail complet intégré directement dans le panneau d’administration Larapen. Connectez n’importe quel compte e-mail IMAP/SMTP et lisez, rédigez, répondez, transférez et gérez vos messages sans quitter votre tableau de bord.

Cas d’utilisation

Administrateur de site

Vous gérez un site Larapen et souhaitez lire et répondre aux e-mails (demandes de support, notifications de formulaires de contact) sans basculer vers un client de messagerie séparé.

• Ajoutez votre compte e-mail professionnel (ex. admin@yoursite.com).
• Lisez les messages entrants dans la boîte de réception du panneau d’administration.
• Répondez directement depuis le tableau de bord avec votre signature e-mail.

Comptes d’équipe multiples

Chaque utilisateur administrateur gère son ou ses propres comptes e-mail. Un responsable du support peut ajouter à la fois support@company.com et billing@company.com, en basculant entre eux selon les besoins.

Communication centralisée

Gardez toute la communication liée au site visible au même endroit. Transférez les e-mails importants, rédigez des messages de prospection et gérez la correspondance avec les clients : le tout depuis le panneau d’administration.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+ avec l’extension imap activée
• MySQL 8.0+ (requis pour l’indexation FULLTEXT sur la table des messages)
• Le package Composer webklex/php-imap (inclus avec l’add-on)
• Un compte e-mail avec accès IMAP et SMTP

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Téléverser un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez Client Webmail dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont mis en place automatiquement.

Étape 3 : Configurer

Naviguez vers Admin → Webmail → Paramètres pour configurer les options globales (cache, nombre de messages par page, actualisation automatique). Voir Configuration.

Étape 4 : Ajouter un compte e-mail

Allez dans Admin → Webmail → Comptes et cliquez sur Ajouter un compte. Saisissez les paramètres de vos serveurs IMAP et SMTP, puis utilisez le bouton Tester la connexion pour vérifier avant d’enregistrer. Voir Comptes.

Code d’achat (clé de licence)

Client Webmail est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence), distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez Client Webmail dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée : acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l’achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d’achat Envato sont délivrés et fournis par Envato Market, jamais envoyés par e-mail par nous, il n’y a donc rien à chercher dans votre dossier de spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l’article et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d’achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l’article n’en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Configuration

Les paramètres globaux sont gérés dans Admin → Webmail → Paramètres. Le fichier de configuration est config/webmail.php et les valeurs peuvent être remplacées depuis le panneau d’administration (stockées dans la table settings, groupe webmail).

Gestion des comptes

Chaque utilisateur administrateur gère ses propres comptes e-mail. Les comptes sont liés à l’utilisateur authentifié : un utilisateur ne peut ni voir ni modifier les comptes d’un autre utilisateur.

Ajouter un compte

Naviguez vers Admin → Webmail → Comptes → Ajouter un compte. Le formulaire requiert :

Paramètres IMAP & SMTP courants

Tester la connexion

Cliquez sur le bouton Tester la connexion dans le formulaire de compte pour vérifier la connectivité IMAP avant d’enregistrer. Le test tente de se connecter au serveur IMAP avec les identifiants fournis et retourne un message de succès ou d’erreur. Il s’agit d’une requête AJAX : aucun rechargement de page nécessaire.

Boîte de réception & Dossiers

La vue principale de la boîte aux lettres est accessible dans Admin → Webmail → Boîte de réception. Elle affiche la liste des messages pour le compte et le dossier sélectionnés.

Changement de compte

Si un utilisateur possède plusieurs comptes, un menu déroulant permet de basculer entre eux. Le compte par défaut est sélectionné automatiquement au premier chargement.

Navigation dans les dossiers

Les dossiers sont synchronisés automatiquement depuis le serveur IMAP. L’add-on détecte les types de dossiers standards :

• Boîte de réception : messages entrants
• Envoyés : messages envoyés
• Brouillons : brouillons de messages
• Corbeille : messages supprimés
• Spam : messages indésirables
• Archives : messages archivés
• Personnalisé : tout autre dossier créé par l’utilisateur

La détection du type de dossier gère les conventions de nommage de Gmail, Outlook et IMAP standard. Chaque dossier affiche le nombre total de messages et le nombre de messages non lus.

Actualisation des dossiers

Cliquez sur le bouton Actualiser pour resynchroniser les dossiers depuis le serveur IMAP. Cela met à jour les listes de dossiers, les compteurs de messages et (lorsque le cache local est activé) télécharge les nouveaux messages.

Lecture des messages

Cliquez sur n’importe quel message dans la liste pour afficher son contenu complet. La vue de détail du message affiche :

• Adresses De, À, CC, CCI
• Sujet et date
• Corps HTML (rendu dans un iframe isolé) ou corps en texte brut
• Liste des pièces jointes avec liens de téléchargement
• Boutons d’action rapide : Répondre, Répondre à tous, Transférer, Supprimer

Recherche

Utilisez la barre de recherche pour trouver des messages dans le dossier actuel. Lorsque le cache local est activé, la recherche utilise l’indexation FULLTEXT de MySQL sur les colonnes subject et text_body, ainsi que la recherche JSON sur les champs d’adresses. Lorsque le cache est désactivé, la recherche interroge directement le serveur IMAP.

Actions sur les messages

Les actions suivantes sont disponibles via AJAX (sans rechargement de page) :

Rédiger & Répondre

Nouveau message

Naviguez vers Admin → Webmail → Rédiger pour créer un nouvel e-mail. Sélectionnez le compte d’envoi (si vous en avez plusieurs), remplissez les champs À, CC et CCI, saisissez un sujet et le corps du message, puis cliquez sur Envoyer.

• Plusieurs destinataires peuvent être saisis sous forme d’adresses séparées par des virgules.
• Les champs CC et CCI sont masqués par défaut et peuvent être dépliés via des liens de bascule.
• La signature du compte est ajoutée automatiquement si elle est configurée.

Répondre & Transférer

Depuis la vue de détail du message, cliquez sur Répondre, Répondre à tous ou Transférer pour ouvrir le formulaire de rédaction pré-rempli avec :

• Répondre : champ À défini sur l’expéditeur original. Sujet préfixé par Re:. Message original cité.
• Répondre à tous : champ À défini sur l’expéditeur original plus tous les destinataires CC. Sujet préfixé par Re:.
• Transférer : champ À laissé vide. Sujet préfixé par Fwd:. Message original cité avec un bloc d’en-tête de transfert.

Le format de citation utilise le modèle : “Le [date], [expéditeur] a écrit :” suivi du corps du message original.

Pièces jointes

Les messages sortants prennent en charge les pièces jointes. La taille maximale des pièces jointes est contrôlée par le paramètre max_attachment_size (par défaut : 25 Mo). Les pièces jointes prévisualisables (images, PDF) peuvent être ouvertes directement dans le navigateur lorsque attachment_preview est activé.

Pour télécharger une pièce jointe d’un message reçu, cliquez sur le nom de la pièce jointe dans la vue de détail du message. Les pièces jointes sont récupérées directement depuis le serveur IMAP à la demande.

Paramètres

Naviguez vers Admin → Webmail → Paramètres pour configurer l’add-on. Les paramètres sont organisés en sections :

Affichage

• Messages par page : nombre de messages affichés par page dans la boîte aux lettres.
• Mode d’affichage HTML : iframe (isolé, recommandé) ou text (texte brut uniquement).
• Format de date : format de date PHP pour les horodatages des messages.
• Aperçu des pièces jointes : ouvrir les images/PDF directement ou forcer le téléchargement.
• Taille max des pièces jointes : taille maximale des fichiers pour les pièces jointes sortantes (en Ko).

Performance

• Cache local : activer le cache de messages en base de données pour un chargement plus rapide.
• Intervalle d’actualisation : actualisation automatique de la boîte aux lettres en secondes. Définissez à 0 pour désactiver, ou choisissez des intervalles comme “au focus de l’onglet”, 30 secondes, 1 minute, etc.

Mise à jour

Il existe deux façons de mettre cet add-on à jour : via le panneau d’administration (recommandé) ou en remplaçant manuellement les fichiers.

Méthode 1 : Téléversement via le panneau d’administration (recommandé)

1. Téléchargez le dernier fichier .zip de cet add-on.
2. Allez dans Panneau d’administration → Add-ons et cliquez sur le bouton Téléverser.
3. Sélectionnez ou faites glisser le fichier .zip dans la zone de téléversement.
4. Une invite de confirmation affichera les numéros de version actuelle et nouvelle. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour du système (/admin/update) pour appliquer les migrations de base de données en attente.

Méthode 2 : Remplacement manuel des fichiers

Étape 1 : Remplacer les fichiers

Remplacez le répertoire de l’add-on par la nouvelle version.

Étape 2 : Exécuter les migrations

php artisan migrate

Les migrations en attente ne s’exécutent qu’une seule fois : la commande peut être relancée sans risque.

Étape 3 : Vider les caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Étape 4 : Vérifier

Visitez Webmail → Comptes et vérifiez que vos comptes sont toujours listés et opérationnels. Cliquez sur Tester la connexion sur un compte pour confirmer la connectivité.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Webmail Client et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/webmail/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Les migrations en attente sont rejouées, les assets republiés, et l’add-on reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez Webmail Client (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d’administration, en une seule passe :

• exécute le hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations, ce qui supprime ses tables de base de données et toutes les lignes qu’elles contiennent, et purge ses entrées de la table migrations, afin qu’une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/webmail/, public/vendor/webmail/ et storage/app/public/addons/webmail/ ;
• supprime le dossier de l’add-on extensions/addons/webmail/ ;
• supprime sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et vide le cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/webmail/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

Le test de connexion échoue : “Could not connect to IMAP server”

Vérifiez que :

• L’hôte et le port IMAP sont corrects pour votre fournisseur de messagerie.
• Le type de chiffrement correspond au port (SSL pour 993, STARTTLS pour 143).
• Le nom d’utilisateur et le mot de passe sont corrects. Pour Gmail, utilisez un mot de passe d’application si l’authentification à deux facteurs est activée.
• Le pare-feu de votre serveur autorise les connexions sortantes sur le port IMAP.
• Si vous utilisez un certificat auto-signé, désactivez imap_validate_cert.

Les messages ne se chargent pas : boîte de réception vide

• Cliquez sur Actualiser pour forcer une synchronisation des dossiers.
• Vérifiez que le compte est marqué comme Actif.
• Consultez la colonne connection_error dans webmail_accounts pour les messages d’erreur stockés.
• Vérifiez que le serveur IMAP autorise la connexion (certains fournisseurs nécessitent d’activer “l’accès IMAP” dans leurs paramètres).

L’envoi d’e-mail échoue : “Send failed”

• Vérifiez les paramètres d’hôte, de port et de chiffrement SMTP.
• Si le nom d’utilisateur/mot de passe SMTP est laissé vide, le système utilise les identifiants IMAP par défaut : assurez-vous qu’ils fonctionnent aussi pour le SMTP.
• Vérifiez les journaux du serveur (storage/logs/laravel.log) pour le message d’erreur SMTP spécifique.
• Certains fournisseurs (ex. Gmail) nécessitent d’autoriser les “applications moins sécurisées” ou d’utiliser des mots de passe d’application.

La synchronisation des dossiers affiche des types de dossiers incorrects

L’add-on utilise une détection heuristique pour identifier les types de dossiers. Si un dossier est incorrectement catégorisé (ex. votre dossier “Envoyés” apparaît comme “personnalisé”), vérifiez que :

• Le nom du dossier suit les conventions IMAP standard de votre fournisseur.
• Les dossiers Gmail utilisent le préfixe [Gmail]/ (ex. [Gmail]/Sent Mail).
• La méthode resolveCanonicalFolders() gère les types en double en sélectionnant le plus approprié.

Le cache local ne se met pas à jour

• Assurez-vous que local_cache est défini sur true dans Webmail → Paramètres.
• Vérifiez la colonne uid_validity dans webmail_folders. Si elle a changé sur le serveur, le cache est automatiquement purgé et resynchronisé lors du prochain accès.
• Essayez de cliquer sur Actualiser pour déclencher une synchronisation incrémentielle.
• Pour les problèmes persistants, videz manuellement le cache en tronquant la table webmail_messages pour le dossier concerné et en réinitialisant last_synced_uid à 0.

Les pièces jointes ne se téléchargent pas

• Les pièces jointes sont récupérées directement depuis le serveur IMAP à la demande : elles ne sont pas stockées localement. Assurez-vous que la connexion IMAP est active.
• Si l’index de la pièce jointe est incorrect, le téléchargement échouera. Cela peut se produire si la structure du message a changé sur le serveur.
• Vérifiez le paramètre max_attachment_size : il s’applique aux pièces jointes sortantes, pas aux téléchargements.

La recherche ne retourne aucun résultat

• Lorsque le cache local est désactivé, la recherche interroge directement le serveur IMAP. Certains serveurs IMAP ont des capacités de recherche limitées.
• Lorsque le cache local est activé, la recherche utilise le FULLTEXT MySQL. Les termes de recherche courts (moins de 3-4 caractères, selon le ft_min_word_len de MySQL) peuvent ne pas retourner de résultats.
• Assurez-vous que les messages ont été synchronisés dans le cache local avant de rechercher.

Le compte par défaut ne persiste pas

Le WebmailAccountObserver garantit qu’un seul compte par utilisateur peut être défini par défaut. Lors de la définition d’un nouveau compte par défaut, tous les autres comptes de cet utilisateur sont automatiquement désactivés comme défaut. Si aucun compte par défaut n’est explicitement défini, le premier compte actif est utilisé comme solution de repli.