Newsletter plugin Documentation

Collect email and SMS subscribers, organize them into segments, compose campaigns, and send targeted communications: all from within your LaraClassifier / JobClass admin panel.

Use Cases

Portfolio Site with Updates

You run a portfolio site and want to keep clients informed about new projects and services.

• Add a subscription form to your footer or a dedicated page section.
• Create segments like “Clients” and “Prospects” to send targeted updates.
• Compose campaigns announcing new projects or services and send to all or specific segments.

SaaS Product with Launch List

You are building a product and want to collect early-access signups.

• Enable double opt-in to ensure valid email addresses.
• Create a “Beta Waitlist” segment and mark it as default.
• When ready to launch, compose a campaign targeting the waitlist segment.

Multi-Topic Blog Newsletter

Your blog covers multiple topics and readers want to subscribe only to what interests them.

• Create public segments for each topic (e.g. “Tech”, “Design”, “Business”).
• Visitors choose their interests via checkboxes on the subscription form.
• Send topic-specific campaigns to the relevant segments only.

SMS Alerts for Local Business

You run a local business and want to send SMS promotions to customers.

• Collect phone numbers through the subscription form (phone field).
• Create SMS campaigns with plain-text content (HTML is auto-stripped).
• Send via Vonage or Twilio depending on your configured SMS driver.

Requirements

• LaraClassifier / JobClass v19.0.0 or later
• PHP 8.3+
• MySQL 8.0+
• A configured mail driver (for email campaigns and confirmation emails)
• Optional: Vonage or Twilio account and package (for SMS campaigns)

Installation

Step 1: Upload the Add-on

In the admin panel, go to Admin → Extensions → Add-ons and click the Upload Add-on button. Select the add-on’s ZIP file: the system extracts it automatically and the add-on appears in the installed add-ons list.

Step 2: Activate the Add-on

Find Newsletter Platform in the list and click Activate. Its migrations, seeders (if any) and permissions are set up automatically.

Step 3: Configure

Navigate to Admin → Newsletter → Settings to configure your sender name, email address, double opt-in, and campaign defaults. See Configuration.

Purchase Code (License Key)

Newsletter Platform is sold as a separate product, so it has its own purchase code (license key) — distinct from the purchase code of the main application and from the one of every other add-on. You are asked for it when you activate Newsletter Platform in Admin panel → Add-ons.

Our products are sold on three platforms. The way you receive a purchase code depends on where you bought the product.

Platform / Marketplace	How you get the purchase code	Where to find it again
bedigit.com Store In-site purchase (Shop)	Generated automatically when the order is paid, then sent by email — either in its own license email, or inside the order confirmation email.	My Account → My Licenses on bedigit.com
Gumroad	Created as soon as Gumroad notifies us of the sale, then sent in a separate email, in addition to the Gumroad receipt.	The license email, your Gumroad Library, and My Account → My Licenses on bedigit.com
Envato Market CodeCanyon	Issued by Envato, not by us, and never sent by email: you download it yourself from your Envato account.	Envato account → Downloads → License certificate & purchase code

1. bedigit.com Store (in-site purchase)

• As soon as the order’s payment status becomes Paid, a license key is generated automatically for every licensed item in the order (one key per purchased unit — buying 3 units gives 3 distinct keys).
• It is emailed to the address used on the order, either in a dedicated license email or inside the order confirmation email. Check your inbox and your spam / junk folder.
• The key stays available in your account under My Account → My Licenses. Keys are masked in the list; open the license detail page to reveal and copy the full key, see the domains it is activated on, and deactivate a domain to free an activation slot.
• The matching invoice is under My Account → My Orders.

2. Gumroad

• A Gumroad purchase produces two separate emails: the Gumroad receipt (sent by Gumroad, giving access to the files) and a license key email (sent by bedigit.com) that contains your purchase code.
• The license key email is generated as soon as Gumroad notifies us of the sale, so it normally arrives within seconds of the payment. Here too, check your inbox and your spam / junk folder.
• When the Gumroad product uses Gumroad’s own license-key feature, the same key also appears in your Gumroad receipt and under Library → your purchase on gumroad.com.
• Use the same email address on bedigit.com as on Gumroad: your keys are then linked to your account automatically and listed under My Account → My Licenses, even if you register after the purchase. You can also add a Gumroad key manually from My Account → My Gumroad Licenses.

3. Envato Market (CodeCanyon)

• Envato purchase codes are issued and delivered by Envato Market, never emailed by us — so there is nothing to look for in your spam folder: you retrieve the code from your Envato account.
• Log in to your Envato / CodeCanyon account, open the Downloads page, find the item, and choose License certificate & purchase code from the Download dropdown. The code is written in that certificate.
• An Envato purchase code looks like 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 characters). It never changes, and renewing item support does not issue a new one.
• Official Envato article: Where Is My Purchase Code?

Configuration

Settings are managed in Admin → Newsletter → Settings (stored in the settings table, group newsletter). Config defaults are defined in config/newsletter.php.

Setting	Description	Default
newsletter_double_opt_in	When enabled, subscribers must confirm their email address via a confirmation link before being added to the list.	true
newsletter_from_name	The name displayed in the “From” field of newsletter emails.	APP_NAME
newsletter_from_email	The email address used in the “From” field of newsletter emails.	MAIL_FROM_ADDRESS
newsletter_reply_to	The email address where replies will be sent. Leave empty to use the From email.	(empty)
newsletter_welcome_subject	Subject line for the welcome email (translatable, per-locale). Leave empty to disable the welcome email.	(empty)
newsletter_welcome_content	Body content of the welcome email (translatable, per-locale). Leave empty to disable.	(empty)

Environment Variables

Admin: Settings

The settings page (Newsletter → Settings) is organized into sections:

Opt-in Settings

• Double Opt-In: Toggle switch. When enabled, new subscribers receive a confirmation email and remain in “pending” status until they click the confirmation link.

Email Settings

• From Name: The sender name for all newsletter emails.
• From Email: The sender email address.
• Reply-To Email: Where replies go. Leave empty to use the From email.

Welcome Email

• Welcome Email Subject: Translatable text input (one per language). Set the subject line of the welcome email sent after subscription confirmation.
• Welcome Email Content: Translatable textarea. The body of the welcome email. Leave both subject and content empty to disable the welcome email entirely.

Admin: Subscribers

The Subscribers page (Newsletter → Subscribers) is the main subscriber management view.

Statistics Dashboard

A row of stat cards at the top shows:

• Total Subscribers: all records in the table
• Confirmed: active, confirmed subscribers
• Pending: awaiting email confirmation
• Unsubscribed: opted out
• New This Month: subscribers created in the current calendar month

Subscribers List

A paginated table (20 per page) with filters:

• Status filter: dropdown to show All, Pending, Confirmed, or Unsubscribed
• Segment filter: dropdown to filter by segment membership

Each row shows: email, name, phone, status badge, source badge, segment tags, subscribed date, and a delete action.

Adding a Subscriber

Click Add Subscriber to open the creation form:

• Email: required, must be unique in the subscribers table
• Phone: optional, for SMS campaigns
• Name: optional
• Status: select: Pending, Confirmed, or Unsubscribed
• Segments: multi-select of active segments

Manually added subscribers have source = 'manual'. If set to “Confirmed”, their confirmed_at and subscribed_at timestamps are set immediately.

Import & Export

Import from CSV

Click Import to upload a CSV file. Requirements:

• The first row must be a header row.
• The importer auto-detects email and name columns from the header.
• If no header match is found, column 1 is treated as email, column 2 as name.
• Maximum file size: 5 MB.
• Accepted formats: .csv, .txt

Imported subscribers are created with status = 'confirmed' and source = 'import'. Duplicate emails are skipped. After import, a summary shows how many were imported vs. skipped.

Export to CSV

Click Export to download a CSV of all active (confirmed) subscribers. The export includes: Email, Name, Status, Subscribed At, and Source columns.

Admin: Segments

Segments (Newsletter → Segments) let you group subscribers into targeted lists.

Segments List

A paginated table showing each segment with:

• Color swatch: visual identifier
• Name (translatable)
• Description (translatable)
• Active subscribers count
• Flags: Public, Default, Active badges
• Position: sort order

Create & Edit

The segment form includes:

• Name: translatable, required in the default language
• Description: translatable, optional
• Color: hex color picker (validated as #RRGGBB)
• Public: when enabled, the segment appears on front-end subscription forms, allowing visitors to choose which lists to join
• Default: new subscribers are automatically added to default segments, regardless of their form selection
• Active: inactive segments are excluded from campaign targeting and front-end forms
• Position: integer for display ordering

Admin: Campaigns

Campaigns (Newsletter → Campaigns) are the email or SMS messages you send to subscribers.

Campaigns List

A paginated table (20 per page) with an optional status filter showing:

• Subject
• Channel: Email or SMS badge
• Status badge: Draft, Scheduled, Sending, Sent, or Failed
• Segments: target segment names, or “All subscribers”
• Recipients / Opens / Clicks: delivery statistics
• Author
• Created date

Composing a Campaign

Click New Campaign to open the compose form:

• Sending Mode: toggle between Email and SMS
• Subject: translatable text input (required for email in default locale, optional for SMS)
• Content: translatable rich text editor (required in default locale). For SMS mode, HTML is automatically stripped when saving.
• Target Segments: multi-select of active segments. If none are selected, the campaign sends to all active subscribers.
• Scheduled At: optional datetime field for future scheduling

Campaigns are created in draft status. The active subscriber count is displayed to indicate how many recipients will receive the campaign.

Editing Campaigns

Only campaigns in draft or scheduled status can be edited. Once a campaign enters sending or sent status, it becomes read-only and displays as a detail view with delivery statistics.

Sending a Campaign

When you click Send Now, the following process occurs:

1. The campaign status changes to sending.
2. Target subscribers are resolved based on assigned segments (or all active subscribers if no segments).
3. A newsletter_campaign_logs record is created for each subscriber in a database transaction.
4. Each log entry is processed: the subscriber receives a Laravel Notification (email via MailMessage or SMS via Vonage/Twilio channel).
5. Successful deliveries are marked as sent; failures are logged with the error message.
6. The campaign status updates to sent with the final recipients_count.

SMS Campaign Mode

When the sending mode is set to SMS:

• The subject field becomes optional (SMS messages have no subject line).
• HTML content is automatically stripped from all locale translations when the campaign is saved.
• Content is truncated to 1600 characters (10 SMS parts) when sent.
• The notification routes through the Vonage or Twilio channel based on the sms_driver configuration.
• Only subscribers with a phone number receive SMS campaigns; those without are skipped with an error.

Front-end: Subscribe Form

The subscription form is typically embedded in theme views (footer, sidebar, or a dedicated section). It submits via AJAX and returns a JSON response.

Front-end: Email Confirmation

When double opt-in is enabled, subscribers receive an email with a confirmation link.

Front-end: Unsubscribe

Unsubscribe links are included in campaign emails automatically via the campaign email template.

Subscription Flow

With Double Opt-In Enabled (Default)

1. Visitor submits the subscription form with their email (and optionally name, phone, segments).
2. A subscriber record is created with status = 'pending'.
3. A confirmation email is sent with a unique token link.
4. Visitor clicks the confirmation link.
5. Subscriber status changes to confirmed.
6. A welcome email is sent (if subject and content are configured in settings).
7. The subscriber is now eligible to receive campaigns.

Without Double Opt-In

1. Visitor submits the subscription form.
2. A subscriber record is created with status = 'confirmed' immediately.
3. A welcome email is sent (if configured).
4. The subscriber is immediately eligible to receive campaigns.

Re-subscription

If a previously unsubscribed email submits the form again:

1. The existing record is found and its status is reset to pending.
2. A new token is generated and a confirmation email is sent (if double opt-in is enabled).
3. The unsubscribed_at timestamp is cleared.

Segment Assignment

When a subscriber is created or re-subscribed:

• All default segments (segments with is_default = true) are automatically assigned.
• Any segment IDs submitted via the form are also assigned.
• Both are merged and applied using syncWithoutDetaching, so existing memberships are preserved.

Confirmation Email

The SubscriptionConfirmationNotification sends a Markdown email using the newsletter::emails.subscription-confirmation template.

• Subject: “Confirm your subscription to {site_name}” (translatable)
• From: Uses newsletter.from_email / newsletter.from_name
• Action button: Links to /newsletter/confirm/{token}

Failures during email sending are caught silently: the subscriber is still created in pending state.

Welcome Email

The WelcomeNotification is sent after a subscriber is confirmed, but only if the admin has configured both a subject and content in the newsletter settings.

• Subject & Content: Read from database settings, resolved by current locale with fallback to the application’s fallback locale.
• Unsubscribe link: Included in the email template.
• From: Uses newsletter.from_email / newsletter.from_name

Campaign Delivery

The CampaignNotification handles both email and SMS delivery using Laravel’s notification system.

Email Delivery

• Uses a Markdown template: newsletter::emails.campaign
• Subject and content are translatable (resolved by the app locale)
• Reply-To is applied from newsletter.reply_to if configured
• Unsubscribe link is included in the email footer

SMS Delivery

• Routes through Vonage (VonageMessage) or Twilio (TwilioSmsMessage) based on sms_driver
• Content is stripped of HTML tags and truncated to 1600 characters
• Unicode mode is enabled for Vonage to support international characters

Updating

There are two ways to update this add-on: via the admin panel (recommended) or manually replacing files.

Method 1: Admin Panel Upload (Recommended)

1. Download the latest .zip file of this add-on.
2. Go to Admin panel → Add-ons and click the Upload button.
3. Select or drag the .zip file into the upload area.
4. A confirmation prompt will show the current and new version numbers. Click Replace to proceed.
5. Go to Admin panel → System Update (/admin/update) to apply any pending database migrations.

Method 2: Manual File Replacement

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

php artisan migrate

Pending migrations run once, so the command is safe to repeat.

Step 3: Clear Caches

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

Step 4: Verify

Visit Admin → Newsletter → Settings and confirm your settings are intact. Check the subscribers list to verify data integrity.

Uninstallation

Switching an add-on off without losing anything is a deactivation: go to Admin panel → Add-ons, find Newsletter Platform and click Deactivate.

• Its routes, views, admin menu entries and permissions stop being registered, and its front-end pages stop answering.
• Its database tables and all the data they hold are kept, and its files stay under extensions/addons/newsletter/. Nothing is deleted.
• The purchase code recorded at activation is kept too, so activating the add-on again does not ask for it.
• Deactivation is refused while another active add-on depends on this one: deactivate that add-on first.

Click Activate on the same card to switch it back on. Pending migrations are re-run, assets are republished, and the add-on picks up exactly where it left off.

Removing

Removing is permanent and destroys the add-on's data. The Remove button only appears on a deactivated add-on, so removal is always two steps:

1. Deactivate Newsletter Platform (see Uninstallation).
2. Click Remove on its card and confirm the prompt.

The admin panel then, in one pass:

• runs the add-on's uninstall hook, if it ships one, while its code is still on disk;
• revokes the permissions declared in its addon.json;
• rolls back its migrations — this drops its database tables and every row they hold — and purges its entries from the migrations table, so a later reinstall migrates from scratch;
• deletes its published assets: public/addons/newsletter/, public/vendor/newsletter/ and storage/app/public/addons/newsletter/;
• deletes the add-on directory extensions/addons/newsletter/;
• deletes its row in the addons table (the recorded purchase code goes with it) and clears the application cache.

Removal is refused, with an explanatory message and before anything is destroyed, when the add-on is still active, when another active add-on depends on it, or when the web server (PHP) user cannot delete extensions/addons/newsletter/. In that last case, give that user write permission on the directory and on its parent, then try again.

Deleting the folder over FTP or SSH is not equivalent: the add-on's tables, its entries in the migrations table and its addons row are all left behind, and its card stays in the list. Use Remove in the admin panel instead.

Troubleshooting

Confirmation emails not being sent

• Ensure your mail driver is correctly configured in .env (MAIL_MAILER, MAIL_HOST, etc.).
• Check that Double Opt-In is enabled in Newsletter settings.
• Check the Laravel log file (storage/logs/laravel.log) for mail sending errors.
• Confirmation email failures are caught silently: the subscriber is still created in pending state, but no email is sent.

Welcome email not being sent

• Ensure both Welcome Email Subject and Welcome Email Content are filled in for at least one language in the newsletter settings.
• The welcome email requires content in the current locale or the fallback locale. If neither has content, it is skipped.

Subscribers not receiving campaigns

• Verify the subscriber’s status is confirmed (pending and unsubscribed subscribers are excluded).
• If the campaign targets specific segments, ensure the subscriber belongs to at least one of those segments.
• Check the newsletter_campaign_logs table for error messages on failed deliveries.

SMS campaigns failing

• Ensure the Vonage or Twilio package is installed and configured.
• Verify sms_driver is set to either vonage or twilio.
• Subscribers must have a phone number to receive SMS campaigns. Those without phone numbers will produce a “Subscriber has no phone number” error in the campaign logs.

CSV import shows all subscribers as “skipped”

• Ensure the CSV file has valid email addresses.
• Duplicate emails (already in the database) are skipped by design.
• Invalid email formats (failing FILTER_VALIDATE_EMAIL) are also skipped.
• Check that the header row has a column labeled email (case-insensitive).

Campaign stuck in “sending” status

If the sending process was interrupted (e.g., request timeout, server crash), the campaign may remain in sending status. To recover:

1. Check newsletter_campaign_logs for the campaign to see how far delivery progressed.
2. Manually update the campaign’s status to failed or sent in the database.
3. For large lists, consider implementing queue-based sending to avoid timeouts.

Subscribers not being assigned to default segments

• Ensure the segment has is_default = true and is_active = true.
• Default segments are only assigned at subscription time. Existing subscribers are not retroactively added when a segment is marked as default.

Theme views not overriding add-on views

The front-end confirmation and unsubscribe pages look for theme overrides at:

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

Create these views in your active theme’s views/ directory to override the default templates.