Plateforme Newsletter

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 : Placer l’add-on

Copiez ou créez un lien symbolique du dossier newsletter dans votre répertoire Larapen « extensions/addons » :

Étape 2 : Activer l’add-on

Allez dans Admin → Add-ons → Add-ons installés et activez Plateforme Newsletter.

Étape 3 : Exécuter les migrations

Cela crée 5 tables : newsletter_subscribers, newsletter_segments, newsletter_segment_subscriber, newsletter_campaigns, et newsletter_campaign_logs. La table pivot newsletter_campaign_segment est également créée.

Étape 4 : Définir les permissions

L’add-on enregistre 14 permissions (voir Permissions). Assignez-les aux rôles admin via Admin → Utilisateurs → Rôles & Permissions.

Étape 5 : Configurer

Naviguez vers Admin → Newsletter → Paramètres et configurez votre nom d’expéditeur, votre adresse e-mail et vos préférences d’opt-in. Voir Configuration.

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.

Paramètre	Description	Par défaut
newsletter_double_opt_in	Lorsqu’il est activé, les abonnés doivent confirmer leur adresse e-mail via un lien de confirmation avant d’être ajoutés à la liste.	true
newsletter_from_name	Le nom affiché dans le champ « De » des e-mails de la newsletter.	APP_NAME
newsletter_from_email	L’adresse e-mail utilisée dans le champ « De » des e-mails de la newsletter.	MAIL_FROM_ADDRESS
newsletter_reply_to	L’adresse e-mail où les réponses seront envoyées. Laissez vide pour utiliser l’e-mail d’expédition.	(vide)
newsletter_welcome_subject	Objet de l’e-mail de bienvenue (traduisible, par langue). Laissez vide pour désactiver l’e-mail de bienvenue.	(vide)
newsletter_welcome_content	Contenu du corps de l’e-mail de bienvenue (traduisible, par langue). Laissez vide pour désactiver.	(vide)

Variables d’environnement

Admin : Paramètres

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

Paramètres d’opt-in

• Double Opt-In : 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 dans 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 au 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 définis immédiatement.

Import & Export

Import depuis 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 par rapport aux 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 hex (validé 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
• Statut badge : Brouillon, Planifié, En 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 : basculer 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é à : champ datetime 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 settings.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éé avec status = 'confirmed' immédiatement.
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 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 settings.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

Étape 1 : Remplacer les fichiers

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

Étape 2 : Exécuter les migrations

Étape 3 : Vider les caches

É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é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 le Double Opt-In est activé 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 settings.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 « L’abonné n’a pas de numéro de téléphone » 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 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.