AI-ready newsletters
for Laravel.

MCP for agents, REST for CRM, Filament for operators — subscribers to delivery analytics in one open-source app.

Get started Read the docs
Pillars

Built for operators
and integrations.

Three surfaces, one source of truth — the admin panel, the REST API, and an MCP server for AI clients. PHP 8.3+ · Laravel 13 · Filament 5 · MIT · v2.1

01 AI · MCP Native MCP so Cursor and Claude can list campaigns, draft templates, create messages, and read delivery metrics. Docs
02 REST API Sanctum-authenticated CRUD for subscribers, tags, templates, campaigns, and messages — plus OpenAPI at /api/documentation. Docs
03 Roles Editor, Manager, and Administrator with clear boundaries over campaigns, subscribers, tokens, and users. Docs
Features

Everything for real sends.

From subscriber hygiene to delivery analytics — the essentials, without the bloat.

Subscribers & tags
CSV import/export, status workflows, tagging, and precise audience segmentation — including testing tags that keep dry-runs out of production metrics.
Campaigns & messages
Structured campaigns with draft, ready, sending, and sent states you can trust.
HTML templates
Reusable templates with placeholders — plus optional AI-assisted generation via MCP.
Scheduled sending
Cron-driven delivery with rate limits and estimated completion aligned to your SMTP caps.
Full tracking
Opens, clicks, unsubscribes, and automatic UTM parameters on outbound links.
Dashboard & analytics
KPIs, send statistics, per-message tracking, and widgets built for operators.
Bounce detection
Optional IMAP bounce processing that keeps your list clean automatically.
Multilingual admin
Italian, English, German, French, Spanish, and Portuguese.
Install

Up in minutes.

Clone, configure, migrate — then create your first admin user.

bash — clone & install 
git clone https://github.com/andreapollastri/newsletter.git
cd newsletter
composer install
bash — configure & run 
cp .env.example .env
php artisan key:generate
php artisan migrate
npm install && npm run build
php artisan make:filament-user

Prefer the one-shot setup script? composer run setup installs dependencies, creates .env, generates the key, migrates, and builds assets. Full details in Docs → Installation.

Docs

From zero to first campaign.

The essentials to install, configure, send, and integrate. Deep reference lives in the GitHub README.

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 for Vite asset builds

Installation

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

Then create an admin user and start the queue worker:

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

Optional sample data: php artisan newsletter:seed-data (default credentials after seeding: admin@newsletter.test / password).

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

Configuration

Mail

Configure SMTP in .env:

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.

Variable Window Default
NEWSLETTER_RATE_LIMIT_PER_MINUTE ~1 min 0
NEWSLETTER_RATE_LIMIT_PER_HOUR ~1 h 0
NEWSLETTER_RATE_LIMIT_PER_DAY ~24 h 0
NEWSLETTER_TRACKING_ENABLED — true
Inspect live counters with php artisan newsletter:rate-limits. Keep the worker --timeout a few seconds below your queue retry_after.

IMAP bounce detection (optional)

bash 
composer require webklex/laravel-imap
env
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

Roles

Every user has exactly one role.

Role Access
Editor Create and manage draft messages inside existing campaigns.
Manager Campaigns, subscribers, tags, templates, all message states, and reports.
Administrator Everything a Manager can do, plus users and API token management.

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

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.

http
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

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:

cron 
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
Task Schedule
newsletter:send-scheduled Every minute
newsletter:process-pending Every 5 minutes
newsletter:process-bounces Every 15 minutes
backup:run / backup:clean Daily

Public routes: /subscribe, double opt-in confirm, and unsubscribe flows.

Deploy

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

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

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