Guide du module Newsletter pour Larapen

Collectez des abonnés par e-mail et SMS, organisez-les en segments, composez des campagnes et envoyez des communications ciblées : le tout depuis votre panneau d’administration Larapen.

Cas d’utilisation

Site portfolio avec mises à jour

Vous gérez un site portfolio et souhaitez tenir vos clients informés des nouveaux projets et services.

• Ajoutez un formulaire d’inscription dans votre pied de page ou une section de page dédiée.
• Créez des segments comme “Clients” et “Prospects” pour envoyer des mises à jour ciblées.
• Composez des campagnes annonçant de nouveaux projets ou services et envoyez-les à tous ou à des segments spécifiques.

Produit SaaS avec liste de lancement

Vous développez un produit et souhaitez collecter des inscriptions en accès anticipé.

• Activez le double opt-in pour garantir des adresses e-mail valides.
• Créez un segment “Liste d’attente Bêta” et marquez-le comme segment par défaut.
• Au moment du lancement, composez une campagne ciblant le segment de la liste d’attente.

Newsletter de blog multi-thèmes

Votre blog couvre plusieurs sujets et les lecteurs souhaitent s’abonner uniquement à ce qui les intéresse.

• Créez des segments publics pour chaque sujet (ex. : “Tech”, “Design”, “Business”).
• Les visiteurs choisissent leurs centres d’intérêt via des cases à cocher sur le formulaire d’inscription.
• Envoyez des campagnes spécifiques à chaque sujet aux segments concernés uniquement.

Alertes SMS pour commerce local

Vous gérez un commerce local et souhaitez envoyer des promotions SMS à vos clients.

• Collectez les numéros de téléphone via le formulaire d’inscription (champ téléphone).
• Créez des campagnes SMS avec du contenu en texte brut (le HTML est automatiquement supprimé).
• Envoyez via Vonage ou Twilio selon votre pilote SMS configuré.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• Un pilote de messagerie configuré (pour les campagnes e-mail et les e-mails de confirmation)
• Optionnel : compte et package Vonage ou Twilio (pour les campagnes SMS)

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écharger 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 Plateforme Newsletter 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 → Newsletter → Paramètres pour configurer le nom de l’expéditeur, l’adresse e-mail, le double opt-in et les réglages par défaut des campagnes. Voir Configuration.

Code d’achat (clé de licence)

Plateforme Newsletter 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 Plateforme Newsletter 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 sont gérés dans Admin → Newsletter → Paramètres (stockés dans la table settings, groupe newsletter). Les valeurs par défaut sont définies dans config/newsletter.php.

Variables d’environnement

Admin : Paramètres

La page des paramètres (Newsletter → Paramètres) est organisée en sections :

Paramètres d’inscription

• Double confirmation : interrupteur à bascule. Lorsqu’il est activé, les nouveaux abonnés reçoivent un e-mail de confirmation et restent en statut “en attente” jusqu’à ce qu’ils cliquent sur le lien de confirmation.

Paramètres e-mail

• Nom de l’expéditeur : le nom d’expéditeur pour tous les e-mails de la newsletter.
• E-mail de l’expéditeur : l’adresse e-mail de l’expéditeur.
• E-mail de réponse : où vont les réponses. Laissez vide pour utiliser l’e-mail d’expédition.

E-mail de bienvenue

• Objet de l’e-mail de bienvenue : champ texte traduisible (un par langue). Définissez l’objet de l’e-mail de bienvenue envoyé après la confirmation d’inscription.
• Contenu de l’e-mail de bienvenue : zone de texte traduisible. Le corps de l’e-mail de bienvenue. Laissez l’objet et le contenu vides pour désactiver entièrement l’e-mail de bienvenue.

Admin : Abonnés

La page des abonnés (Newsletter → Abonnés) est la vue principale de gestion des abonnés.

Tableau de bord statistique

Une rangée de cartes statistiques en haut affiche :

• Total des abonnés : tous les enregistrements de la table
• Confirmés : abonnés actifs et confirmés
• En attente : en attente de confirmation par e-mail
• Désabonnés : ont choisi de se désinscrire
• Nouveaux ce mois-ci : abonnés créés dans le mois calendaire en cours

Liste des abonnés

Un tableau paginé (20 par page) avec des filtres :

• Filtre par statut : liste déroulante pour afficher Tous, En attente, Confirmés ou Désabonnés
• Filtre par segment : liste déroulante pour filtrer par appartenance à un segment

Chaque ligne affiche : e-mail, nom, téléphone, badge de statut, badge de source, étiquettes de segment, date d’inscription et une action de suppression.

Ajouter un abonné

Cliquez sur Ajouter un abonné pour ouvrir le formulaire de création :

• E-mail : obligatoire, doit être unique dans la table des abonnés
• Téléphone : optionnel, pour les campagnes SMS
• Nom : optionnel
• Statut : sélection : En attente, Confirmé ou Désabonné
• Segments : sélection multiple des segments actifs

Les abonnés ajoutés manuellement ont source = 'manual'. S’ils sont définis comme “Confirmé”, leurs horodatages confirmed_at et subscribed_at sont renseignés immédiatement.

Import & Export

Import depuis un CSV

Cliquez sur Importer pour téléverser un fichier CSV. Conditions requises :

• La première ligne doit être une ligne d’en-tête.
• L’importateur détecte automatiquement les colonnes email et name depuis l’en-tête.
• Si aucune correspondance d’en-tête n’est trouvée, la colonne 1 est traitée comme e-mail, la colonne 2 comme nom.
• Taille maximale du fichier : 5 Mo.
• Formats acceptés : .csv, .txt

Les abonnés importés sont créés avec status = 'confirmed' et source = 'import'. Les e-mails en double sont ignorés. Après l’import, un résumé indique combien ont été importés et combien ont été ignorés.

Export en CSV

Cliquez sur Exporter pour télécharger un CSV de tous les abonnés actifs (confirmés). L’export comprend les colonnes : E-mail, Nom, Statut, Date d’inscription et Source.

Admin : Segments

Les segments (Newsletter → Segments) vous permettent de regrouper les abonnés en listes ciblées.

Liste des segments

Un tableau paginé affichant chaque segment avec :

• Échantillon de couleur : identifiant visuel
• Nom (traduisible)
• Description (traduisible)
• Nombre d’abonnés actifs
• Indicateurs : badges Public, Par défaut, Actif
• Position : ordre de tri

Créer & Modifier

Le formulaire de segment comprend :

• Nom : traduisible, obligatoire dans la langue par défaut
• Description : traduisible, optionnelle
• Couleur : sélecteur de couleur hexadécimale (validée comme #RRGGBB)
• Public : lorsqu’il est activé, le segment apparaît sur les formulaires d’inscription front-end, permettant aux visiteurs de choisir les listes à rejoindre
• Par défaut : les nouveaux abonnés sont automatiquement ajoutés aux segments par défaut, indépendamment de leur sélection dans le formulaire
• Actif : les segments inactifs sont exclus du ciblage des campagnes et des formulaires front-end
• Position : entier pour l’ordre d’affichage

Admin : Campagnes

Les campagnes (Newsletter → Campagnes) sont les messages e-mail ou SMS que vous envoyez aux abonnés.

Liste des campagnes

Un tableau paginé (20 par page) avec un filtre de statut optionnel affichant :

• Objet
• Canal : badge E-mail ou SMS
• Badge de statut : Brouillon, Planifié, En cours d’envoi, Envoyé ou Échoué
• Segments : noms des segments cibles, ou “Tous les abonnés”
• Destinataires / Ouvertures / Clics : statistiques de livraison
• Auteur
• Date de création

Composer une campagne

Cliquez sur Nouvelle campagne pour ouvrir le formulaire de composition :

• Mode d’envoi : bascule entre E-mail et SMS
• Objet : champ texte traduisible (obligatoire pour l’e-mail dans la langue par défaut, optionnel pour le SMS)
• Contenu : éditeur de texte riche traduisible (obligatoire dans la langue par défaut). En mode SMS, le HTML est automatiquement supprimé lors de l’enregistrement.
• Segments cibles : sélection multiple des segments actifs. Si aucun n’est sélectionné, la campagne est envoyée à tous les abonnés actifs.
• Planifié le : champ date et heure optionnel pour une planification future

Les campagnes sont créées avec le statut draft. Le nombre d’abonnés actifs est affiché pour indiquer combien de destinataires recevront la campagne.

Modification des campagnes

Seules les campagnes avec le statut draft ou scheduled peuvent être modifiées. Une fois qu’une campagne passe au statut sending ou sent, elle devient en lecture seule et s’affiche comme une vue détaillée avec les statistiques de livraison.

Envoi d’une campagne

Lorsque vous cliquez sur Envoyer maintenant, le processus suivant se déroule :

1. Le statut de la campagne passe à sending.
2. Les abonnés cibles sont résolus en fonction des segments assignés (ou tous les abonnés actifs si aucun segment).
3. Un enregistrement newsletter_campaign_logs est créé pour chaque abonné dans une transaction de base de données.
4. Chaque entrée de journal est traitée : l’abonné reçoit une notification Laravel (e-mail via MailMessage ou SMS via le canal Vonage/Twilio).
5. Les livraisons réussies sont marquées comme sent ; les échecs sont enregistrés avec le message d’erreur.
6. Le statut de la campagne est mis à jour à sent avec le recipients_count final.

Mode campagne SMS

Lorsque le mode d’envoi est défini sur SMS :

• Le champ objet devient optionnel (les messages SMS n’ont pas de ligne d’objet).
• Le contenu HTML est automatiquement supprimé de toutes les traductions lors de l’enregistrement de la campagne.
• Le contenu est tronqué à 1600 caractères (10 parties SMS) lors de l’envoi.
• La notification est acheminée via le canal Vonage ou Twilio en fonction de la configuration sms_driver.
• Seuls les abonnés ayant un numéro de téléphone reçoivent les campagnes SMS ; ceux sans numéro sont ignorés avec une erreur.

Front-end : formulaire d’inscription

Le formulaire d’inscription est généralement intégré dans les vues du thème (pied de page, barre latérale ou section dédiée). Il soumet via AJAX et retourne une réponse JSON.

Front-end : confirmation par e-mail

Lorsque le double opt-in est activé, les abonnés reçoivent un e-mail avec un lien de confirmation.

Front-end : désinscription

Les liens de désinscription sont inclus automatiquement dans les e-mails de campagne via le modèle d’e-mail de campagne.

Flux d’inscription

Avec le double opt-in activé (par défaut)

1. Le visiteur soumet le formulaire d’inscription avec son e-mail (et optionnellement nom, téléphone, segments).
2. Un enregistrement abonné est créé avec status = 'pending'.
3. Un e-mail de confirmation est envoyé avec un lien à jeton unique.
4. Le visiteur clique sur le lien de confirmation.
5. Le statut de l’abonné passe à confirmed.
6. Un e-mail de bienvenue est envoyé (si l’objet et le contenu sont configurés dans les paramètres).
7. L’abonné est désormais éligible pour recevoir des campagnes.

Sans double opt-in

1. Le visiteur soumet le formulaire d’inscription.
2. Un enregistrement abonné est créé immédiatement avec status = 'confirmed'.
3. Un e-mail de bienvenue est envoyé (si configuré).
4. L’abonné est immédiatement éligible pour recevoir des campagnes.

Réinscription

Si un e-mail précédemment désabonné soumet à nouveau le formulaire :

1. L’enregistrement existant est trouvé et son statut est réinitialisé à pending.
2. Un nouveau jeton est généré et un e-mail de confirmation est envoyé (si le double opt-in est activé).
3. L’horodatage unsubscribed_at est effacé.

Attribution des segments

Lorsqu’un abonné est créé ou réinscrit :

• Tous les segments par défaut (segments avec is_default = true) sont automatiquement assignés.
• Tous les identifiants de segments soumis via le formulaire sont également assignés.
• Les deux sont fusionnés et appliqués en utilisant syncWithoutDetaching, de sorte que les appartenances existantes sont préservées.

E-mail de confirmation

La notification SubscriptionConfirmationNotification envoie un e-mail Markdown en utilisant le modèle newsletter::emails.subscription-confirmation.

• Objet : “Confirmez votre inscription à {site_name}” (traduisible)
• De : utilise newsletter.from_email / newsletter.from_name
• Bouton d’action : lien vers /newsletter/confirm/{token}

Les échecs d’envoi d’e-mail sont capturés silencieusement : l’abonné est tout de même créé en statut “en attente”.

E-mail de bienvenue

La notification WelcomeNotification est envoyée après la confirmation d’un abonné, mais uniquement si l’administrateur a configuré à la fois un objet et un contenu dans les paramètres de la newsletter.

• Objet & contenu : lus depuis les paramètres de la base de données, résolus par la langue courante avec repli sur la langue de secours de l’application.
• Lien de désinscription : inclus dans le modèle d’e-mail.
• De : utilise newsletter.from_email / newsletter.from_name

Livraison des campagnes

La notification CampaignNotification gère à la fois la livraison par e-mail et par SMS en utilisant le système de notifications de Laravel.

Livraison par e-mail

• Utilise un modèle Markdown : newsletter::emails.campaign
• L’objet et le contenu sont traduisibles (résolus par la langue de l’application)
• Le Reply-To est appliqué depuis newsletter.reply_to s’il est configuré
• Le lien de désinscription est inclus dans le pied de l’e-mail

Livraison par SMS

• Acheminé via Vonage (VonageMessage) ou Twilio (TwilioSmsMessage) en fonction de sms_driver
• Le contenu est débarrassé des balises HTML et tronqué à 1600 caractères
• Le mode Unicode est activé pour Vonage afin de prendre en charge les caractères internationaux

Mise à jour

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

Méthode 1 : Téléversement depuis 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 le fichier .zip ou glissez-le dans la zone de téléversement.
4. Une demande de confirmation affiche le numéro de version actuel et le nouveau. 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 Admin → Newsletter → Paramètres et confirmez que vos paramètres sont intacts. Vérifiez la liste des abonnés pour confirmer l’intégrité des données.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Newsletter Platform 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/newsletter/. 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 Newsletter Platform (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/newsletter/, public/vendor/newsletter/ et storage/app/public/addons/newsletter/ ;
• supprime le dossier de l’add-on extensions/addons/newsletter/ ;
• 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/newsletter/. 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

Les e-mails de confirmation ne sont pas envoyés

• Assurez-vous que votre pilote de messagerie est correctement configuré dans .env (MAIL_MAILER, MAIL_HOST, etc.).
• Vérifiez que la Double confirmation est activée dans les paramètres de la Newsletter.
• Consultez le fichier de log Laravel (storage/logs/laravel.log) pour les erreurs d’envoi d’e-mails.
• Les échecs d’envoi des e-mails de confirmation sont capturés silencieusement : l’abonné est tout de même créé en statut “en attente”, mais aucun e-mail n’est envoyé.

L’e-mail de bienvenue n’est pas envoyé

• Assurez-vous que l’Objet de l’e-mail de bienvenue et le Contenu de l’e-mail de bienvenue sont remplis pour au moins une langue dans les paramètres de la newsletter.
• L’e-mail de bienvenue nécessite du contenu dans la langue courante ou la langue de secours. Si aucune des deux n’a de contenu, il est ignoré.

Les abonnés ne reçoivent pas les campagnes

• Vérifiez que le statut de l’abonné est confirmed (les abonnés en attente et désabonnés sont exclus).
• Si la campagne cible des segments spécifiques, assurez-vous que l’abonné appartient à au moins un de ces segments.
• Consultez la table newsletter_campaign_logs pour les messages d’erreur sur les livraisons échouées.

Les campagnes SMS échouent

• Assurez-vous que le package Vonage ou Twilio est installé et configuré.
• Vérifiez que sms_driver est défini sur vonage ou twilio.
• Les abonnés doivent avoir un numéro de téléphone pour recevoir les campagnes SMS. Ceux sans numéro de téléphone produiront une erreur “Subscriber has no phone number” dans les journaux de campagne.

L’import CSV affiche tous les abonnés comme “ignorés”

• Assurez-vous que le fichier CSV contient des adresses e-mail valides.
• Les e-mails en double (déjà dans la base de données) sont ignorés par conception.
• Les formats d’e-mail invalides (échouant à FILTER_VALIDATE_EMAIL) sont également ignorés.
• Vérifiez que la ligne d’en-tête a une colonne nommée email (insensible à la casse).

Campagne bloquée au statut “en cours d’envoi”

Si le processus d’envoi a été interrompu (ex. : délai d’expiration de la requête, plantage du serveur), la campagne peut rester au statut sending. Pour récupérer :

1. Consultez newsletter_campaign_logs pour la campagne afin de voir jusqu’où la livraison a progressé.
2. Mettez à jour manuellement le status de la campagne à failed ou sent dans la base de données.
3. Pour les grandes listes, envisagez d’implémenter un envoi basé sur une file d’attente pour éviter les délais d’expiration.

Les abonnés ne sont pas assignés aux segments par défaut

• Assurez-vous que le segment a is_default = true et is_active = true.
• Les segments par défaut sont assignés uniquement au moment de l’inscription. Les abonnés existants ne sont pas ajoutés rétroactivement lorsqu’un segment est marqué comme par défaut.

Les vues du thème ne remplacent pas les vues de l’add-on

Les pages front-end de confirmation et de désinscription cherchent les surcharges de thème à :

• theme::newsletter.confirm
• theme::newsletter.unsubscribe

Créez ces vues dans le répertoire views/ de votre thème actif pour remplacer les modèles par défaut.