AI-ready newsletters
for Laravel.

Overview

Newsletter is a complete newsletter management system for Laravel, built with Filament. Manage subscribers, campaigns, HTML templates, scheduled sending, and full tracking from a modern admin panel.

It ships with a Sanctum REST API (OpenAPI docs included) and an MCP server so AI agents can operate on the same data as your team.

Requirements

• PHP 8.3+
• Laravel 13
• Filament 5
• Database SQLite, MySQL, or PostgreSQL
• Queue database, Redis, or similar
• Node.js 22+ for Vite asset builds — on the server too, every update builds them
• Git on the server, for updates

Installation

git clone https://github.com/andreapollastri/newsletter.git
cd newsletter
composer run setup

Then create an admin user and start the queue worker:

php artisan make:filament-user
./start-worker.sh

The first account you create is an Administrator; later accounts default to Editor.

Want to look around first? php artisan newsletter:seed-data loads the demo dataset used for the screenshots on this page (log in with admin@newsletter.test / password). It only uses example.com addresses and refuses to run in production without --force.

Generate OpenAPI docs with php artisan l5-swagger:generate.

From then on, Newsletter updates itself from the scheduler: see Updates.

Configuration

Mail

Configure SMTP in .env:

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_FROM_ADDRESS="newsletter@yourdomain.com"
MAIL_FROM_NAME="${APP_NAME}"

Rate limiting

Rolling windows in cache. Set a value to 0 to disable that cap.

IMAP bounce detection (optional)

composer require webklex/laravel-imap

NEWSLETTER_IMAP_ENABLED=true
NEWSLETTER_IMAP_HOST=imap.yourdomain.com
NEWSLETTER_IMAP_PORT=993
NEWSLETTER_IMAP_USERNAME=your-username
NEWSLETTER_IMAP_PASSWORD=your-password
NEWSLETTER_IMAP_ENCRYPTION=ssl
NEWSLETTER_IMAP_FOLDER=INBOX

Reports are parsed as RFC 3464 delivery-status notifications when possible: only Action: failed recipients bounce, 5.x.x codes are hard bounces and 4.x.x soft ones, delay warnings are ignored, and your own sender address is never marked as bounced.

Roles

Every user has exactly one role.

Sending

Immediate

1. Open Newsletter → Messages
2. Create or select a message
3. Set status to Ready
4. Click Send Now — the queue worker delivers

Scheduled

Set Scheduled Date on a message. The scheduler picks it up when due (newsletter:send-scheduled every minute). If no confirmed subscriber matches the audience, the message goes back to Draft and everyone gets a notification instead of a silent no-op.

Audience

Tags include subscribers that have any of the selected tags (none selected = all confirmed subscribers). Exclude tags remove anyone with at least one of them. The Estimated recipients badge shows the result while you edit.

Preview & test

Preview renders the saved message inside its template in a sandboxed frame; Send Test delivers it to any address without tracking.

Testing tags

Mark tags as testing in Filament. Messages that target only testing tags are excluded from production statistics and cleaned up after the send — so you can dry-run the pipeline safely.

REST API

Authenticate with a Sanctum personal access token that has the api ability. Create tokens from the admin user menu → API tokens.

Authorization: Bearer <your-token>

Resources under /api: user, newsletter report, tags, subscribers, templates, campaigns, and messages. Interactive OpenAPI UI: /api/documentation.

MCP server

Endpoint: /mcp/newsletter. Authenticate with a Sanctum token that has the mcp ability.

Tools

• list-campaigns
• newsletter-report
• send-history-analysis
• subscriber-insights
• generate-email-template-html
• create-newsletter-message

Cursor / VS Code mcp.json

{
  "mcpServers": {
    "newsletter": {
      "url": "https://your-domain.example/mcp/newsletter",
      "headers": {
        "Authorization": "Bearer YOUR_SANCTUM_TOKEN"
      }
    }
  }
}

Debug locally with php artisan mcp:inspector mcp/newsletter.

Scheduler & commands

Add the Laravel scheduler to crontab:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Public pages

Updates

Newsletter keeps itself up to date. Administrators find Updates in the user menu: the installed release and build, the newest one, Check now, Update to … and Force update, the channel, the nightly update, and the log of the last run.

Channels

An update never goes backwards: a build is installed only when it contains the installed one. Back on stable after beta, Newsletter keeps its main build until a release contains it. Force update installs the channel's newest build again, or one whose history differs — never an older one.

When it runs

Every night at APP_UPDATE_TIME (04:00 by default) while automatic updates are on. An update asked for on the Updates page starts within a minute.

What an update does

1. Backs up the database to storage/app/updates/backups (the newest 5 are kept)
2. Installs the new build and runs composer install --no-dev
3. Builds the assets: npm ci and npm run build
4. Migrates, rebuilds the caches and restarts the queue workers
5. Checks that Newsletter boots

If a step fails, the previous code and the database come back. The log of the last run is on the page and in storage/app/updates/update.log.

Installations

The scheduler's user runs the update: it needs git, composer and the database client (mysqldump/mysql, pg_dump/psql) on its PATH, and write access to the application. public/build is not committed, so every update builds the assets: npm (Node.js 22+) must be on that PATH too, or set APP_UPDATE_NPM. On Cipi releases, Cipi's own node-build.sh builds them.

Environment

• APP_UPDATES — on in production; false turns updates off
• APP_UPDATE_REPOSITORY — where builds come from (this repository on GitHub)
• APP_UPDATE_CHANNEL (stable) and APP_UPDATE_AUTO (true) — the defaults until an Administrator chooses on the Updates page
• APP_UPDATE_TIME (04:00) — the nightly update, in the app timezone
• APP_UPDATE_BACKUP (true) — the database backup before each update
• APP_UPDATE_ASSETS (true) — build the assets with npm; leave it on
• APP_UPDATE_PHP, APP_UPDATE_COMPOSER, APP_UPDATE_NPM, APP_UPDATE_GIT — the tools, when the scheduler's PATH lacks them

Command line

# the last check and run (JSON)
php artisan app:update status
# what the channel would install
php artisan app:update check
# update now, or reinstall
php artisan app:update apply
php artisan app:update apply --force
# channel: stable or beta
php artisan app:update channel beta
# nightly update: on or off
php artisan app:update auto off

Upgrading from 2.2.0 or earlier

Those versions have no updater: update to 2.3.1 by hand one last time and make sure the cron entry is there. From then on, Newsletter updates itself. On a git checkout:

git fetch --tags
git checkout 2.3.1
composer install --no-dev
npm ci && npm run build
php artisan migrate --force
php artisan optimize
php artisan queue:restart

On Cipi or Deployer, deploy 2.3.1 the way you deployed until now.

Deploy

Deploy on any Ubuntu VPS with cipi.sh — dedicated Linux user, PHP-FPM pool, zero-downtime deploys, SSL, and queue workers.

wget -O - https://cipi.sh/setup.sh | bash

Source and issues: github.com/andreapollastri/newsletter · MIT License · v2.3