A complete newsletter management system for Laravel, built with Filament. Manage subscribers, campaigns, HTML templates, scheduled sending, and full tracking — all from a modern admin panel. Includes a REST API, OpenAPI documentation, and an MCP server for AI integrations.
Open Source Newsletter System
स्टार
15
टूल
—
अपटाइम
—
Screenshots in this README come from a real local install seeded with php artisan newsletter:seed-data.
Full CRUD API with Sanctum authentication and OpenAPI docs
MCP Server
AI integration endpoint for Cursor, Claude Code, and other clients
Testing Tags
Mark tags as testing to exclude sends from production statistics
Multilingual
Admin panel in Italian, English, German, French, Spanish, Portuguese
UTM Tracking
Automatic UTM parameters on signed, tracked outbound links
Demo Data
newsletter:seed-data builds a realistic dataset to explore the app
User Roles
Three permission levels: Editor, Manager, Administrator
Screenshots
Messages and audiences
Include / exclude targeting
Email preview
Per-message statistics
Subscribers
API tokens & MCP
User Management & Roles
The application supports three user roles with progressively broader permissions. Every user is assigned exactly one role, stored in the role column of the users table.
Roles
Role
Description
Editor
Focused on content creation. Can create and manage draft messages within existing campaigns.
Manager
Full operational access. Manages campaigns, subscribers, tags, templates, and all message states.
Administrator
Everything a Manager can do, plus user management, API token management and updates.
Permission Matrix
Area
Editor
Manager
Administrator
Dashboard
—
✓
✓
Campaigns (view)
✓
✓
✓
Campaigns (create/edit/delete)
—
✓
✓
Messages (create)
✓
✓
✓
Messages (view/edit/delete draft)
✓
✓
✓
Messages (view sent/sending)
—
✓
✓
Subscribers
—
✓
✓
Tags
—
✓
✓
Templates
—
✓
✓
Users
—
—
✓
API Tokens
—
—
✓
Updates
—
—
✓
Newsletter Report API
—
✓
✓
Navigation
Editor — lands on the Campaigns page after login; the dashboard is not shown in navigation.
Manager / Administrator — lands on the Dashboard; all navigation items are visible according to the matrix above.
User menu — the Users, API Tokens and Updates links appear only for Administrators.
Managing Users
Administrators can create, edit, and delete users from the Users page in the admin panel. When creating or editing a user, the following fields are available:
Name and Email (required)
Password (required on create, optional on edit — leave blank to keep unchanged)
Role — select Editor, Manager, or Administrator
Locale — preferred language for the admin panel UI
An administrator cannot delete their own account.
Migrations
When upgrading from a version without roles, two migrations handle the transition:
add_role_to_users_table — adds the role column (defaults to editor).
set_all_existing_users_to_legacy_administrator_role — promotes all pre-existing users to administrator so they retain full access.
They run like any other migration: from 2.3.0 on, every update runs them by itself; an installation on 2.2.0 or earlier is updated by hand one last time (see Upgrading from 2.2.0 or earlier).
On a fresh install, the first account created without an explicit role (for example with php artisan make:filament-user) becomes an Administrator. Later accounts without a role default to Editor.
Requirements
PHP 8.3+
Laravel 13
Filament 5
Database (SQLite, MySQL, or PostgreSQL)
Queue driver (database, Redis, etc.)
Node.js 22+ (to build the frontend assets, also on the server: every update builds them)
When disabled, missing credentials, or without webklex/laravel-imap, newsletter:process-bounces exits cleanly and does nothing.
How reports are interpreted:
Delivery-status notifications (RFC 3464) — when the report carries Final-Recipient / Action / Status fields (Postfix, Exim, Gmail, Exchange…), only recipients with Action: failed bounce. 5.x.x status codes are hard bounces, 4.x.x are soft.
Delay warnings (Action: delayed, "Delayed Mail (still being retried)", "Delivery Status Notification (Delay)") are ignored: the MTA is still retrying.
Other reports fall back to keyword detection; your own MAIL_FROM_ADDRESS and IMAP username are never treated as bounced recipients.
The bounce is linked to the original send (tracking URL in the returned message, also when quoted-printable encoded) or to the subscriber's latest send, and any opens/clicks recorded for that send are discarded (mail clients load the tracking pixel of the returned copy).
API Documentation (Swagger)
To auto-generate the OpenAPI spec on every request in local development:
L5_SWAGGER_GENERATE_ALWAYS=true
For production, run php artisan l5-swagger:generate during deploy.
Quick Start
Seed demo data (optional, recommended for a first look):
php artisan newsletter:seed-data
This creates a realistic, reproducible dataset: 400 subscribers (--subscribers= to change it) with mixed statuses and tags, three templates and campaigns, six sent messages with opens, clicks, bounces and unsubscribes, plus a scheduled message, drafts and a testing-tag message. All addresses use reserved example.* domains. Re-running it is safe, and it refuses to run in production unless you pass --force.
Start the queue worker:
./start-worker.sh
Or manually:
php artisan queue:work --tries=3 --timeout=90
Access the admin panel:
URL:https://newsletter.test (Laravel Herd) or http://localhost:8000
Emails are queued and sent automatically via the queue worker
Scheduled Sending
Create or edit a message
Set the Scheduled Date field
The system sends automatically at the scheduled time (requires cron — see Scheduled Tasks)
If a due message matches no confirmed subscriber, it is moved back to Draft and every user gets a notification. Sending is idempotent: a subscriber never gets two send rows for the same message, even if sending is triggered twice.
Audience
Tags — subscribers with any of the selected tags receive the message. No tags = all confirmed subscribers.
Exclude tags — subscribers with at least one of these tags are removed, even if they match an include tag (e.g. Customers, but not Partners). A tag cannot be both included and excluded.
Estimated recipients — live count of confirmed subscribers matching the current selection (Managers and Administrators).
Preview and Test
Preview (messages table, message view/edit pages, templates) renders the saved email inside its template in a sandboxed frame, personalised with your name.
Send Test delivers the message to any address, without tracking, with a [TEST] subject prefix.
Unsubscribe Headers
Every newsletter carries List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058), so Gmail, Yahoo and Outlook can show their native unsubscribe button. Make sure your MTA DKIM-signs these headers.
Link Tracking
When tracking is enabled, links are rewritten to /track/click/{send} with UTM parameters and a signature that binds the destination to the send, so the endpoint cannot be used as an open redirect. Links sent by earlier versions (unsigned) keep working as long as their send row exists. mailto:, tel: and #anchor links are left untouched.
Monitoring & Analytics
Dashboard: Main KPIs plus a daily chart of emails sent and opens, filterable by campaign and period
Messages: Status, audience and send counts per message
Message Details: Sends, opens, clicks, failures, bounces and unsubscribes, plus per-recipient tracking
Rate Limiting
Configure how many emails the queue may send using rolling windows (stored in the app cache). Set a variable to 0 to turn off that cap; the other caps still apply.
Env variable
Window
Typical use
NEWSLETTER_RATE_LIMIT_PER_MINUTE
~1 min
Burst control; low values cause jobs to release() often (short delays).
NEWSLETTER_RATE_LIMIT_PER_HOUR
~1 h
Provider hourly quotas.
NEWSLETTER_RATE_LIMIT_PER_DAY
~24 h
Daily provider caps.
How sending works: for each queued send, SendNewsletterEmail checks daily, then hourly, then per-minute (App\Services\EmailRateLimiter). The send proceeds only if it fits under every enabled limit; otherwise the job is released with a delay and no quota is consumed for that attempt.
Throughput: in practice the tightest of your enabled limits dominates (e.g. high hourly but low per-minute still throttles bursts).
Estimated time: while a message is in Sending, the UI uses the same three env-driven values to approximate completion (Message::getEstimatedSendTime()).
Keeping PER_MINUTE=0 and using only hourly/daily is a common choice for large campaigns to avoid many small queue delays.
Queue / worker: ensure the worker --timeout stays a few seconds below your database queue retry_after (see config/queue.php, DB_QUEUE_RETRY_AFTER) so jobs are not processed twice.
Check current counters:
php artisan newsletter:rate-limits
REST API
The application exposes a full REST API authenticated via Laravel Sanctum personal access tokens.
Authentication
Go to the admin panel user menu > API tokens (or navigate to /api-tokens)
Create a token with the API ability enabled
Use the token in the Authorization header:
Authorization: Bearer <your-token>
Endpoints
All endpoints are prefixed with /api and require a valid Bearer token with the api ability.
Method
Endpoint
Description
GET
/api/user
Authenticated user info
GET
/api/reports/newsletter
Newsletter report (filterable)
GET
/api/tags
List all tags
POST
/api/tags
Create a tag
GET
/api/tags/{tag}
Show a tag
PUT
/api/tags/{tag}
Update a tag
DELETE
/api/tags/{tag}
Delete a tag
GET
/api/subscribers
List subscribers
POST
/api/subscribers
Create a subscriber
GET
/api/subscribers/{subscriber}
Show a subscriber
PUT
/api/subscribers/{subscriber}
Update a subscriber
DELETE
/api/subscribers/{subscriber}
Delete a subscriber
GET
/api/templates
List templates
POST
/api/templates
Create a template
GET
/api/templates/{template}
Show a template
PUT
/api/templates/{template}
Update a template
DELETE
/api/templates/{template}
Delete a template
GET
/api/campaigns
List campaigns
POST
/api/campaigns
Create a campaign
GET
/api/campaigns/{campaign}
Show a campaign
PUT
/api/campaigns/{campaign}
Update a campaign
DELETE
/api/campaigns/{campaign}
Delete a campaign
GET
/api/campaigns/{campaign}/messages
List messages in a campaign
POST
/api/campaigns/{campaign}/messages
Create a message
GET
/api/campaigns/{campaign}/messages/{message}
Show a message
PUT
/api/campaigns/{campaign}/messages/{message}
Update a message
DELETE
/api/campaigns/{campaign}/messages/{message}
Delete a message
OpenAPI Documentation
Interactive Swagger UI is available at /api/documentation. Generate or update the spec with:
php artisan l5-swagger:generate
MCP Server (AI Integrations)
The application includes a Model Context Protocol (MCP) server that allows AI clients (Cursor, Claude Code, Windsurf, etc.) to interact with your newsletter data.
Endpoint
/mcp/newsletter
Authenticated with a Sanctum Bearer token that has the mcp ability.
Available Tools
Tool
Description
list-campaigns
Lists campaigns (all campaigns for managers/administrators; editors see their own)
newsletter-report
Delivery report with summary, per-message stats, and daily timeseries
send-history-analysis
Highlights and trends from recent send history
subscriber-insights
Audience breakdown by tags and statuses
generate-email-template-html
Generates responsive HTML email template from a description
create-newsletter-message
Creates a draft or ready message inside a campaign
Prompt
The server ships with a newsletter-assistant prompt — a reusable skill template that guides AI assistants through campaign planning, report interpretation, content drafting, and message creation.
Setup in Your AI Client
Create a token in the admin panel with the MCP ability
Configure your AI client to connect to the MCP endpoint with the token as Bearer auth
Replace your-domain.example with your deployment host (for local development, something like http://127.0.0.1:8000/mcp/newsletter). Replace YOUR_SANCTUM_TOKEN with the plaintext token string from the admin panel (treat it like a password).
Example requests
You can phrase tasks in natural English; the assistant maps them to MCP tools. Examples:
Campaigns: “List all newsletter campaigns.” / “What campaigns do we have?”
Delivery stats: “Give me a newsletter delivery report from 2026-01-01 to 2026-01-31.” / “Show sends, opens, clicks, and bounces for the last 30 days.”
Scoped report: “Report for the campaign with id … between 2026-01-01 and 2026-01-31.”
Narrative summary: “Summarize send history and highlights for the last quarter.”
Audience: “How many subscribers do we have by status? Which tags have the most subscribers?”
HTML: “Generate a responsive HTML email template for a product launch: hero, short intro, three feature bullets, primary CTA button.”
New message: “Create a draft message in the given campaign id, using the given template id, subject Weekly digest, HTML body …, and the listed tag ids.”
For send statistics and campaign listing, use a token belonging to a Manager or Administrator if your organization splits campaign ownership across users; those roles see all campaigns in reports (same idea as the admin panel).
Testing Tags
Tags can be marked as testing (is_testing flag) in the Filament admin panel. When a message targets recipients only through testing tags:
Sends are excluded from dashboard statistics (emails sent, opens, clicks, bounces, charts)
After the send completes, per-recipient send rows and related bounces are removed from the database
Testing tags and normal tags cannot be mixed on the same message
This allows safe end-to-end testing of the sending pipeline without polluting production metrics.
Multilingual Support
The admin panel supports six languages: Italian, English, German, French, Spanish, and Portuguese.
Logged-in users can choose their language from the Profile page
Before login, the panel detects the browser Accept-Language header and uses the closest supported language (defaults to English)
New users automatically inherit the browser language on account creation
Public Routes
The following routes are available for public use:
Route
Method
Description
/subscribe
GET
Subscription form
/subscribe
POST
Process subscription (10/min per IP, 5/hour per address)
/subscribe/confirm/{token}
GET
Confirm subscription (double opt-in)
/unsubscribe/{subscriber}
GET
Unsubscribe form
/unsubscribe/{subscriber}
POST
RFC 8058 one-click unsubscribe (no CSRF token, returns 204)
/unsubscribe/{subscriber}/confirm
POST
Confirm unsubscribe
/unsubscribe/test
POST
One-click target for test sends (no-op, returns 204)
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 and the nightly update, and the log of the last run.
Channels: Stable installs the release tags (2.3.0; v2.3.0 and 2.3 count too) and nothing in between; Beta follows the head of main, for a server you test on.
Never 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.
Every night at APP_UPDATE_TIME (04:00 by default) while automatic updates are on; an update asked for on the page starts within a minute. Both run from the scheduler, so the cron entry is required: the page warns when the scheduler has not run in the last few minutes.
Safe: each update backs up the database (storage/app/updates/backups, the newest 5 are kept), installs the build, runs composer install --no-dev, builds the assets (npm ci and npm run build), migrates, rebuilds the caches, restarts the queue workers and 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.
in place: maintenance mode, checkout of the new build (detached), build, migrations. Tracked files changed by hand stop the update; Force update discards them.
A release of a deploy: releases/<x>, current, shared/ (Cipi, Deployer)
the new build is cloned into releases/<build> next to the running one, shares its .env and storage, is built and migrated, then current points at it; Cipi's workers restart. A later cipi deploy keeps working as before.
The scheduler's user runs the update, so 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, its own Node build script is used). From the command line:
php artisan app:update status # what the last check and the last run said (JSON)
php artisan app:update check # what the channel would install
php artisan app:update apply [--force] # update now
php artisan app:update channel stable # or beta
php artisan app:update auto off # or on
Variable
Default
APP_UPDATES
on in production
false turns updates off
APP_UPDATE_REPOSITORY
https://github.com/andreapollastri/newsletter.git
where builds come from
APP_UPDATE_CHANNEL
stable
the channel until an Administrator picks one
APP_UPDATE_AUTO
true
the nightly update until an Administrator switches it
APP_UPDATE_TIME
04:00
when the nightly update runs
APP_UPDATE_BACKUP
true
the database backup before each update
APP_UPDATE_ASSETS
true
build the assets (npm); leave it on, public/build is not committed
the tools, when the scheduler's PATH does not have them
The installed release is in the VERSION file.
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:
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
Newsletter कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
क्या Newsletter के लिए API key चाहिए?
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Newsletter कौन सा ट्रांसपोर्ट इस्तेमाल करता है?
Newsletter stdio पर लोकल चलता है।
Newsletter की पिछली जाँच कब हुई थी?
पिछली जाँच 2026-10-28 को हुई। Open Source Newsletter System