Newsletter System

Version 2.0.7 — Changelog

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.

Table of Contents

• Features
• User Management & Roles
• Requirements
• Installation
• Configuration
• Quick Start
• Sending Newsletters
• Monitoring & Analytics
• Rate Limiting
• REST API
• MCP Server (AI Integrations)
• Testing Tags
• Multilingual Support
• Public Routes
• Scheduled Tasks
• Artisan Commands
• Troubleshooting

Features

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

Permission Matrix

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 API Tokens and Users 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:

1. add_role_to_users_table — adds the role column (defaults to editor).
2. set_all_existing_users_to_legacy_administrator_role — promotes all pre-existing users to administrator so they retain full access.

Requirements

• PHP 8.3+
• Laravel 13
• Filament 5
• Database (SQLite, MySQL, or PostgreSQL)
• Queue driver (database, Redis, etc.)

Installation

1. Clone the repository and install dependencies:

git clone <repository-url> newsletter
cd newsletter
composer install

1. Configure the environment:

cp .env.example .env
php artisan key:generate

1. Run migrations:

php artisan migrate

1. Build frontend assets:

npm install
npm run build

1. Create an admin user (if not using seed data):

php artisan make:filament-user

1. Generate API documentation (optional):

php artisan l5-swagger:generate

Configuration

Mail

Configure your SMTP settings 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="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Newsletter

See Rate limiting for behaviour and tuning.

IMAP (Bounce Detection)

Optional configuration for processing bounced emails:

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

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

1. Seed sample data (optional, recommended for testing):

php artisan newsletter:seed-data

1. Start the queue worker:

./start-worker.sh

Or manually:

php artisan queue:work --tries=3 --timeout=90

1. Access the admin panel:

• URL: https://newsletter.test (Laravel Herd) or http://localhost:8000
• Default credentials (after seeding): [email protected] / password

Sending Newsletters

Immediate Sending

1. Go to Newsletter > Messages
2. Create a new message or select an existing one
3. Set status to Ready
4. Click Send Now
5. Emails are queued and sent automatically via the queue worker

Scheduled Sending

1. Create or edit a message
2. Set the Scheduled Date field
3. The system sends automatically at the scheduled time (requires cron — see Scheduled Tasks)

Monitoring & Analytics

• Dashboard: Main KPIs and send statistics
• Messages: Status and send counts per message
• Message Details: Individual tracking (opens, clicks) per recipient

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.

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()).

Example (adjust to your SMTP limits):

NEWSLETTER_RATE_LIMIT_PER_MINUTE=0
NEWSLETTER_RATE_LIMIT_PER_HOUR=1000
NEWSLETTER_RATE_LIMIT_PER_DAY=10000

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

1. Go to the admin panel user menu > API tokens (or navigate to /api-tokens)
2. Create a token with the API ability enabled
3. 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.

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

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

1. Create a token in the admin panel with the MCP ability
2. Configure your AI client to connect to the MCP endpoint with the token as Bearer auth
3. Debug locally with: php artisan mcp:inspector mcp/newsletter

VS Code / Cursor mcp.json example (HTTP)

Point the URL at your app’s origin plus /mcp/newsletter, and send the Sanctum token in the Authorization header:

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

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:

Scheduled Tasks

Add the Laravel scheduler to your crontab:

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

Artisan Commands

Take it to production — cipi.sh

Once your app is ready, deploy it to any Ubuntu VPS with cipi.sh — an open-source CLI built exclusively for Laravel.

• Full app isolation — own Linux user, PHP-FPM pool & database per app
• Zero-downtime deploys with instant rollback via Deployer
• Let's Encrypt SSL, Fail2ban, UFW firewall — all automated
• Multi-PHP (7.4 → 8.5), queue workers, S3 backups, auto-deploy webhooks
• AI Agent ready — any AI with SSH access can deploy & manage your server

wget -O - https://raw.githubusercontent.com/andreapollastri/cipi/refs/heads/latest/install.sh | bash

→ Learn more at cipi.sh

Troubleshooting

Emails not sending

1. Ensure the queue worker is running: ./start-worker.sh or php artisan queue:work
2. Manually process pending: php artisan newsletter:process-pending
3. Check the jobs table: php artisan tinker --execute="DB::table('jobs')->count()"

Test email delivery

php artisan tinker --execute="Mail::raw('Test', fn(\$m) => \$m->to('[email protected]'))"

Verify rate limits

php artisan newsletter:rate-limits

Frontend changes not visible

Run npm run build or npm run dev to compile assets.

API issues

1. Verify the token is valid: check the API tokens page in the admin panel
2. Ensure the token has the correct ability (api for REST endpoints, mcp for the MCP server)
3. Check the OpenAPI docs at /api/documentation for request/response format

License

MIT

Credits

Created by Andrea Pollastri