Search by

filagora / filagora-newsletters

zcwilt

Newsletters for Filagora: subscribers with consent, campaigns built from content blocks, scheduled sends, link tracking, and delivery events, independent of any one mail provider.

Package info

github.com/filagora/filagora-newsletters

pkg:composer/filagora/filagora-newsletters

Statistics

Installs: 38

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.1.0 2026-11-14 16:25 UTC

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 between 0.x minor 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 with filagora: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) and anonymizeForErasure($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, under consent in the config.
  • Rendering. ContentRenderer turns 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. BrandingSettings holds the shared brand name, header line, logo, footer text and unsubscribe-link label (saved as settings; branding in the config gives the defaults). CampaignMail is the mailable; its views are filagora-newsletters::mail.* and can be overridden.
  • Tracked links. Button blocks, and links in rich text that carry the nl-tracked-link marker 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. Only http and https destinations are followed.
  • Images. The package has no media library: bind Contracts\NewsletterMedia to 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, preview in 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.plugins and editor.toolbar_buttons.
  • Sending. CampaignSender::queue($newsletter) turns a draft or scheduled newsletter into one queued send per sendable subscriber (confirmed, not unsubscribed, no suppression hash), marks the newsletter sending, 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 a SendCampaignEmail job (three tries, with a back-off; delivery.queue names the queue) that calls CampaignMailer: it skips someone who unsubscribed since being queued, sends with their own signed unsubscribe link, marks the send sent or failed with the reason, and marks the newsletter sent when 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 it sent, a failure marks it failed with 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 implements Contracts\EventHandler, named under events.handlers.
  • Delivery. DeliveryTransport sends through the mailer named by delivery.provider (the application's default when null); CampaignMail tags 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.enabled to serve GET|POST /newsletter (the signup page and form, with a honeypot field and a per-address rate limit), and the signed confirm and unsubscribe links (confirmation links last seven days). The routes are named newsletter.show, newsletter.store, newsletter.confirm and newsletter.unsubscribe. The packaged pages are bare; name your own under routes.views to use your layout. The confirmation mail is ConfirmSubscription; its wording is in resources/lang, with name (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, NewsletterSendStatus and NewsletterSubscriberStatus.
  • 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.