Documentation du plugin Newsletter

Collectez des abonnés email et SMS, organisez-les en segments, composez des campagnes et envoyez des communications ciblées : le tout depuis le panneau d'administration de LaraClassifier / JobClass.

Cas d'utilisation

Site portfolio avec actualités

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

• Ajoutez un formulaire d'abonnement dans votre pied de page ou dans une section de page dédiée.
• Créez des segments comme “Clients” et “Prospects” pour envoyer des actualités ciblées.
• Composez des campagnes annonçant vos nouveaux projets ou services et envoyez-les à tous ou à des segments précis.

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 email 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ématique

Votre blog couvre plusieurs sujets et vos lecteurs souhaitent ne s'abonner qu'à ce qui les intéresse.

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

Alertes SMS pour un commerce local

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

• Collectez les numéros de téléphone via le formulaire d'abonnement (champ téléphone).
• Créez des campagnes SMS avec un contenu en texte brut (le HTML est automatiquement supprimé).
• Envoyez via Vonage ou Twilio selon le pilote SMS que vous avez configuré.

Prérequis

• LaraClassifier / JobClass v19.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• Un pilote de messagerie configuré (pour les campagnes email et les emails de confirmation)
• Optionnel : un compte et un 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éverser un add-on. Sélectionnez le fichier ZIP de l’add-on : le système l'extrait automatiquement et l'add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l'add-on

Trouvez Newsletter Platform dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont configurés automatiquement.

Étape 3 : Configurer

Rendez-vous dans Admin → Newsletter → Paramètres pour configurer le nom de l'expéditeur, l'adresse email, le double opt-in et les valeurs par défaut des campagnes. Voir Configuration.

Code d'achat (clé de licence)

Newsletter Platform 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 Newsletter Platform 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 passe à 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 — l'achat de 3 unités donne 3 clés distinctes).
• Elle est envoyée par email à l'adresse utilisée pour la commande, soit dans un email de licence dédié, soit dans l'email 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 révéler 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 génère deux emails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un email de clé de licence (envoyé par bedigit.com) qui contient votre code d'achat.
• L'email 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é 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 email 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 manuellement une clé Gumroad depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d'achat Envato sont émis et délivrés par Envato Market, jamais envoyés par email par nos soins — il n'y a donc rien à chercher dans votre dossier 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 figure 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 génère 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 de configuration 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'opt-in

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

Paramètres email

• Nom de l'expéditeur : le nom de l'expéditeur pour tous les emails de newsletter.
• Email de l'expéditeur : l'adresse email de l'expéditeur.
• Email de réponse : où vont les réponses. Laissez vide pour utiliser l'email de l'expéditeur.

Email de bienvenue

• Sujet de l'email de bienvenue : champ texte traduisible (un par langue). Définit la ligne de sujet de l'email de bienvenue envoyé après la confirmation de l'abonnement.
• Contenu de l'email de bienvenue : zone de texte traduisible. Le corps de l'email de bienvenue. Laissez le sujet et le contenu vides pour désactiver entièrement l'email de bienvenue.

Admin : Abonnés

La page 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 de page 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 email
• Désabonnés : ayant retiré leur consentement
• Nouveaux ce mois-ci : abonnés créés durant le mois calendaire en cours

Liste des abonnés

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

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

Chaque ligne affiche : l'email, le nom, le téléphone, le badge de statut, le badge de source, les étiquettes de segments, la date d'abonnement et une action de suppression.

Ajouter un abonné

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

• Email : 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 sur “Confirmé”, leurs horodatages confirmed_at et subscribed_at sont renseignés immédiatement.

Import & export

Importer depuis un CSV

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

• 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 n'est trouvée dans l'en-tête, la colonne 1 est traitée comme l'email et la colonne 2 comme le 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 emails en doublon sont ignorés. Après l'import, un récapitulatif indique combien ont été importés et combien ont été ignorés.

Exporter en CSV

Cliquez sur Exporter pour télécharger un CSV de tous les abonnés actifs (confirmés). L'export inclut les colonnes : Email, Nom, Statut, Date d'abonnement et Source.

Admin : Segments

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

Liste des segments

Un tableau paginé affichant chaque segment avec :

• Pastille 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 au format #RRGGBB)
• Public : lorsqu'il est activé, le segment apparaît sur les formulaires d'abonnement 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, quelle que soit 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 email ou SMS que vous envoyez aux abonnés.

Liste des campagnes

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

• Sujet
• Canal : badge Email ou SMS
• Badge de statut : Brouillon, Planifiée, En cours d'envoi, Envoyée ou Échouée
• Segments : noms des segments ciblés, 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 : basculez entre Email et SMS
• Sujet : champ texte traduisible (obligatoire pour l'email dans la langue par défaut, optionnel pour le SMS)
• Contenu : éditeur de texte enrichi traduisible (obligatoire dans la langue par défaut). En mode SMS, le HTML est automatiquement supprimé lors de l'enregistrement.
• Segments ciblés : sélection multiple des segments actifs. Si aucun n'est sélectionné, la campagne est envoyée à tous les abonnés actifs.
• Planifiée le : champ date/heure optionnel pour une planification future

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

Modifier des campagnes

Seules les campagnes au 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 sous forme de vue détaillée avec les statistiques de livraison.

Envoyer 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 ciblés sont déterminés selon les segments assignés (ou tous les abonnés actifs s'il n'y a pas de segments).
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 (email via MailMessage ou SMS via le canal Vonage/Twilio).
5. Les livraisons réussies sont marquées comme sent ; les échecs sont journalisés avec le message d'erreur.
6. Le statut de la campagne passe à sent avec le recipients_count final.

Mode campagne SMS

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

• Le champ sujet devient optionnel (les messages SMS n'ont pas de ligne de sujet).
• 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 segments SMS) lors de l'envoi.
• La notification est acheminée via le canal Vonage ou Twilio selon la configuration sms_driver.
• Seuls les abonnés disposant d'un numéro de téléphone reçoivent les campagnes SMS ; ceux qui n'en ont pas sont ignorés avec une erreur.

Front-end : Formulaire d'abonnement

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

Front-end : Confirmation par email

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

Front-end : Désabonnement

Les liens de désabonnement sont inclus automatiquement dans les emails de campagne via le modèle d'email de campagne.

Flux d'abonnement

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

1. Le visiteur soumet le formulaire d'abonnement avec son email (et éventuellement son nom, son téléphone et des segments).
2. Un enregistrement d'abonné est créé avec status = 'pending'.
3. Un email de confirmation est envoyé avec un lien contenant un jeton unique.
4. Le visiteur clique sur le lien de confirmation.
5. Le statut de l'abonné passe à confirmed.
6. Un email de bienvenue est envoyé (si le sujet 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'abonnement.
2. Un enregistrement d'abonné est créé immédiatement avec status = 'confirmed'.
3. Un email de bienvenue est envoyé (s'il est configuré).
4. L'abonné est immédiatement éligible pour recevoir des campagnes.

Réabonnement

Si un email précédemment désabonné soumet à nouveau le formulaire :

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

Assignation des segments

Lorsqu'un abonné est créé ou réabonné :

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

Email de confirmation

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

• Sujet : “Confirmez votre abonnement à {site_name}” (traduisible)
• Expéditeur : utilise newsletter.from_email / newsletter.from_name
• Bouton d'action : pointe vers /newsletter/confirm/{token}

Les échecs lors de l'envoi de l'email sont interceptés silencieusement : l'abonné est tout de même créé au statut en attente.

Email de bienvenue

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

• Sujet & contenu : lus depuis les paramètres en base de données, résolus selon la langue courante avec repli sur la langue de secours de l’application.
• Lien de désabonnement : inclus dans le modèle d'email.
• Expéditeur : utilise newsletter.from_email / newsletter.from_name

Livraison des campagnes

La notification CampaignNotification gère la livraison par email et par SMS en utilisant le système de notifications de Laravel.

Livraison par email

• Utilise un modèle Markdown : newsletter::emails.campaign
• Le sujet et le contenu sont traduisibles (résolus selon la langue de l'application)
• L'adresse de réponse est appliquée depuis newsletter.reply_to si elle est configurée
• Le lien de désabonnement est inclus dans le pied de page de l'email

Livraison par SMS

• Acheminée via Vonage (VonageMessage) ou Twilio (TwilioSmsMessage) selon 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 existe deux façons de mettre à jour cet add-on : 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 éventuelles 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

Étape 3 : Vider les caches

Étape 4 : Vérifier

Visitez Admin → Newsletter → Paramètres et confirmez que vos paramètres sont intacts. Consultez la liste des abonnés pour vérifier l'intégrité des données.

Dépannage

Les emails 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 journal de Laravel (storage/logs/laravel.log) pour les erreurs d'envoi d'email.
• Les échecs d'email de confirmation sont interceptés silencieusement : l'abonné est tout de même créé au statut en attente, mais aucun email n'est envoyé.

L'email de bienvenue n'est pas envoyé

• Assurez-vous que le Sujet de l'email de bienvenue et le Contenu de l'email de bienvenue sont tous deux renseignés pour au moins une langue dans les paramètres de la newsletter.
• L'email de bienvenue nécessite un contenu dans la langue courante ou dans 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 précis, assurez-vous que l'abonné appartient à au moins l'un de ces segments.
• Consultez la table newsletter_campaign_logs pour les messages d'erreur des 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 qui n'en ont pas 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 email valides.
• Les emails en doublon (déjà présents en base de données) sont ignorés par conception.
• Les formats d'email invalides (échouant à FILTER_VALIDATE_EMAIL) sont également ignorés.
• Vérifiez que la ligne d'en-tête comporte une colonne intitulée email (insensible à la casse).

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

Si le processus d'envoi a été interrompu (par 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 sur failed ou sent dans la base de données.
3. Pour les grandes listes, envisagez de mettre en place un envoi basé sur une file d'attente afin d'é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 ne sont assignés qu'au moment de l'abonnement. Les abonnés existants ne sont pas ajoutés rétroactivement lorsqu'un segment est marqué comme segment 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ésabonnement recherchent les surcharges du 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.