filagora / filagora-newsletters
Newsletters for Filagora: subscribers with consent, campaigns built from content blocks, scheduled sends, link tracking, and delivery events, independent of any one mail provider.
Requires
- php: ^8.4
- filagora/filagora-core: ^0.2.2
- filament/filament: ^5.0
Requires (Dev)
- filagora/filagora-entitlements: ^0.2.2
- larastan/larastan: ^3.0
- laravel/pint: ^1.0
- orchestra/testbench: ^11.0
- pestphp/pest: ^4.0
- pestphp/pest-plugin-laravel: ^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-15 12:53:52 UTC
README
Newsletters for Filagora: subscribers with their consent record, campaigns built from content
blocks, scheduled sends, link tracking and delivery events, independent of any one mail provider.
Requires filagora/filagora-core.
The package is at
0.1: the API may change between0.xminor versions. It was extracted from the zen-cart.com support site, and its tables match that site's live tables, so the site can adopt them as they are withfilagora:adopt.
What it provides
Overview
Newsletters for Filagora: subscribers with consent, campaigns built from content blocks, scheduled sends, link tracking, and delivery events, independent of any one mail provider.
Tables
newsletter_subscribers, newsletters, newsletter_sends, newsletter_events, newsletter_blocks and newsletter_link_clicks, prefixed filagora_ by default. A site that already has them can run php artisan filagora:adopt instead of migrating. The migration also adds the two shared system blocks (shared_header, shared_footer) when they are missing.
Commands
| Command | What it does |
|---|---|
filagora:newsletters:queue-scheduled (alias newsletter:queue-scheduled) |
Queues campaigns whose scheduled time has come, then releases queued recipients up to the daily limit. The package schedules it every minute (schedule.enabled). |
filagora:newsletters:export-subscribers {path} (alias newsletter:export-subscribers) |
Writes the sendable subscribers to a CSV, each with a signed unsubscribe link, for an external sending provider. |
Events
This package fires no events yet.
Access
| Ability | Entitlement key |
|---|---|
filagora.newsletters.manage |
filagora.newsletters.manage |
One ability opens every newsletter screen. Remap the key under gates in the config (the Zen Cart profile maps it to operator.newsletter.manage). With filagora-entitlements installed the key is declared so filagora:entitlements:sync creates its definition. Nothing is allowed unless the ability passes.
Using it
- Subscribers.
Subscribers(resolve it from the container) does the work:subscribeFromProfile($user, $ip, $userAgent),unsubscribeFromProfile($user),requestPublicSubscription($email, $name, $ip, $userAgent)(pending until confirmed),confirm(),unsubscribe(),forUser(),forEmail(),unlinkUserForEmailChange($user, $oldEmail)(call it when a member changes their address, so the list keeps the old address with its consent) andanonymizeForErasure($user)(keeps a hash so an erased address is not silently re-added). The words a person agreed to are stored with their subscription; set them, and a version label, underconsentin the config. - Rendering.
ContentRendererturns a newsletter's content blocks (header, text, image, button, footer, or a reference to a reusable library block) into email HTML and text.preparedBlocks()shapes blocks for storage: the shared header goes first, the shared footer last, and library references stay live so an edit to a reusable block reaches campaigns not yet sent.BrandingSettingsholds the shared brand name, header line, logo, footer text and unsubscribe-link label (saved as settings;brandingin the config gives the defaults).CampaignMailis the mailable; its views arefilagora-newsletters::mail.*and can be overridden. - Tracked links. Button blocks, and links in rich text that carry the
nl-tracked-linkmarker classes, are rewritten to a signed first-party redirect (newsletter.link-click, part of the public routes). A click is recorded against the send and the library block, then redirects to the link's current destination, so a corrected link works for mail already sent. Onlyhttpandhttpsdestinations are followed. - Images. The package has no media library: bind
Contracts\NewsletterMediato yours (it answers an image's URL and alt text by number, and lists the choices for the editor). The default finds no images. - Filament screens.
NewslettersPlugin::make()on a panel adds a Newsletters navigation group with:- Campaigns: a three-step wizard (details, content blocks, review and send) with a live preview of the rendered email. A campaign can be changed only while it is a draft or scheduled, and deleted only before it was ever queued. Header actions send a test, schedule or reschedule, cancel a schedule, or queue the send now; the view page shows delivery and engagement figures, with relation managers listing each recipient's delivery and every recorded click.
- Settings: the shared brand name, header line, logo, footer text and unsubscribe-link label.
- Preview:
newsletters.preview(/staff/newsletters/{newsletter}/preview,previewin the config) shows the campaign as the email will look, to staff with the ability. - Subscribers: list with filters, add and edit (the address is normalised on the server), unsubscribe or re-confirm one (the reason is kept as the consent record), and bulk unsubscribe or CSV export. A subscriber is never deleted here.
- Blocks: the reusable library (text, image, button), with the shared header and footer as system blocks that cannot be deleted and whose content comes from the newsletter settings; a block's page shows its click performance across every campaign that uses it.
- Rich-text editor: every editor has the Insert Tracked Link button. Add your own plugins (for example a media library's image button) under
editor.pluginsandeditor.toolbar_buttons.
- Sending.
CampaignSender::queue($newsletter)turns a draft or scheduled newsletter into onequeuedsend per sendable subscriber (confirmed, not unsubscribed, no suppression hash), marks the newslettersending, and releases recipient jobs. It refuses a newsletter that is not a draft or scheduled, or that already has deliveries.CampaignSender::dispatchQueuedSends()releases waiting recipients up to the daily limit (delivery.campaign_daily_limit, 90 by default; the rest wait for the next day, which the every-minute command picks up). Each recipient is aSendCampaignEmailjob (three tries, with a back-off;delivery.queuenames the queue) that callsCampaignMailer: it skips someone who unsubscribed since being queued, sends with their own signed unsubscribe link, marks the sendsentorfailedwith the reason, and marks the newslettersentwhen nothing is left waiting.CampaignMailer::sendPreview()sends a preview to any address. - Delivery events. The host serves the provider's webhook (and checks its signature and guards against replays) and passes each decoded event to
DeliveryEvents::handle('mailgun', $event). The provider's handler (MailgunEvents,MailtrapEvents) finds the send (by the send id the mail was tagged with, else the provider's message id, else the recipient's latest send), keeps the event, and updates the send: a delivery marks itsent, a failure marks itfailedwith the provider's message. A permanent bounce, a complaint or the provider's unsubscribe also changes the subscriber (bounced,complained,unsubscribed), with the provider named in the reason (mailgun_bounce). Opens and clicks are kept as events only. It answers a short note when the event was about a newsletter and null when it was not, so the host can go on to treat it as ordinary mail. Another provider is a class that implementsContracts\EventHandler, named underevents.handlers. - Delivery.
DeliveryTransportsends through the mailer named bydelivery.provider(the application's default when null);CampaignMailtags outgoing mail with the send id for Mailgun or Mailtrap so their events can be matched to a send. - Public pages (off by default). Set
filagora-newsletters.routes.enabledto serveGET|POST /newsletter(the signup page and form, with a honeypot field and a per-address rate limit), and the signedconfirmandunsubscribelinks (confirmation links last seven days). The routes are namednewsletter.show,newsletter.store,newsletter.confirmandnewsletter.unsubscribe. The packaged pages are bare; name your own underroutes.viewsto use your layout. The confirmation mail isConfirmSubscription; its wording is inresources/lang, withname(for example "Zen Cart newsletter") filled in. - Models are resolved through
config('filagora-newsletters.models'), so a host can swap any of the six for a subclass and every relation follows. - Enums:
NewsletterStatus,NewsletterBlockType,NewsletterEventType,NewsletterSendStatusandNewsletterSubscriberStatus. - Users: the optional links from subscribers, newsletters and blocks to a user go through the configured user model (
filagora.user_model).
Requirements
PHP 8.4, Laravel 13 and Filament 5. Tested against MariaDB 11.4. Requires filagora/filagora-core.
Install
composer require filagora/filagora-newsletters php artisan vendor:publish --tag=filagora-newsletters-config php artisan migrate
A site that already has the tables runs php artisan filagora:adopt --package=newsletters instead of migrate.
Configuration
config/filagora-newsletters.php holds the swappable models, the newsletter name (FILAGORA_NEWSLETTERS_NAME), the consent wording and versions, the public routes (switch, prefix, middleware, rate limit, page views) and the Filament navigation_group (FILAGORA_NEWSLETTERS_NAVIGATION_GROUP).
Extending
Swap a model by pointing its key under filagora-newsletters.models at your own subclass.
Testing
composer test # Pest, on MariaDB composer lint # Pint composer analyse # Larastan
Local development (DDEV)
ddev start, ddev restart once (it creates the testing database), ddev composer install, then ddev composer test.
Licence
MIT. See LICENSE.