Mailroom
A newsletter for any Grav 2 site, with subscribers and a real consent record, lists, double opt-in, campaigns, segments, automations and open and click numbers of your own.
Mailroom is a newsletter that runs inside your Grav site. People sign up through a box on your pages, confirm by email, and land on the lists they chose. You write campaigns in Admin Next, send them through the Grav Email plugin, and read how they did on screens that count opens and clicks in your own database. Everything is stored in a database you control: SQLite by default, or MySQL or PostgreSQL.
The numbers are yours. An open or a click is a timestamp against a send row, with no IP address, browser or location stored, and the history stays when you change the company that carries your mail.
Important
Premium products require the free License Manager plugin. Install it and add your product license before installing Mailroom.
Requirements
| Requirement | Notes |
|---|---|
Grav >= 2.1.0 |
Mailroom is not compatible with Grav 1.7 |
PHP >= 8.3 |
With PDO and the driver for your database: pdo_sqlite, pdo_mysql or pdo_pgsql |
API plugin >= 1.0.31 |
Powers the admin screens and the REST API |
Email plugin >= 5.1.0 |
All outgoing mail. It must be configured and sending |
| Admin Next | Where you work. Admins need api.access |
| A database | SQLite (created for you, the default), MySQL or MariaDB, or PostgreSQL |
Optional plugins add more:
| Plugin | Adds |
|---|---|
form |
The Form plugin's mailroom action, for a signup form you define yourself |
A transport plugin such as email-smtp2go, email-amazon, email-sendgrid, email-postmark, email-mailgun, email-mailersend or email-resend |
Delivery, bounce and complaint reports through the provider's webhook, and a deliverability check that knows your provider |
Mailroom works without either. Without a provider webhook, campaigns still send; the delivered, bounced and complained figures stay empty.
What's in the box
- Subscribers with a consent record: the sentence each person agreed to, when, and from which address, plus a consent history of every change to their lists.
- Lists people can leave one at a time, each with its own double opt-in, a preference center, and one-click unsubscribe from the mail client.
- A signup box anywhere:
{{ mailroom_form() }}in a theme or page, the Form plugin'smailroomaction, or a JSON endpoint another server can post to. - Campaigns in Markdown, to one list, several lists or every list with a segment, with subject tests, test sends, scheduling, sending to people who joined late, and a retry for failed sends.
- Segments built from conditions, tags, templates, and automations that start on a signup, a confirmation or a tag.
- CSV import and export, with column mapping, a dry run, and the rules that keep people who left from coming back.
- Deliverability checks for SPF, DKIM, DMARC, your From address, the unsubscribe headers, the sending rate, the bounce webhook and your bounce and complaint rates.
- Seven reports, from campaign performance to the hour your readers read.
- Privacy tools: one person's data as a JSON file, and erasure by address that keeps only a suppression hash.
- A REST API and MCP tools for everything the admin does.
Where to start
- Installation gets the plugin running and the database ready.
- Getting started walks through the site URL, the From address, a signup box, the scheduler and your first campaign.
- Lists and signup forms covers every way people join.
Before your first real campaign, read Sending and providers and Deliverability. If mail is not going out, start with Troubleshooting and Jobs and cron.
Installation
Install Mailroom, choose and protect its database, set up cron, and give your admins the permissions they need.
Getting Started
Check the site URL, set who mail comes from, put a signup box on the site, make sure the worker runs, send your first campaign, and learn the words Mailroom uses.
Sending and Providers
How Mailroom's mail leaves through the Email plugin, who it comes from, how fast it goes, the headers it carries, and the provider webhooks that report deliveries, bounces and complaints.
Lists and Signup Forms
Lists and their settings, the mailroom_form() Twig function and its options, several lists as checkboxes, the Form plugin's mailroom action, and the public pages under the route base.
Double Opt-in and Consent
The confirmation email and page, the consent sentence and what is recorded, each person's consent history, and what counts as somebody leaving by their own hand.
Subscribers
The Subscribers table and its filters, a subscriber's page with their lists and tags, adding people with an invite or as already agreed, and the difference between unsubscribing, deleting, suppressing and erasing.
Bulk Actions
Select subscribers by hand, by page or by filter, then add or remove a list or a tag, unsubscribe or delete them, and read what was done and who was left alone.
Import and Export
Bring a contact list in from another tool with column mapping, a preview and a dry run, the rules every row goes through, import:csv on the command line, and exporting subscribers as CSV.
Tags and Segments
Tags as notes the site keeps about people, and segments as saved questions about your audience, with every field, operator and count, and how campaigns and automations use them.
Campaigns
Write a campaign, choose one list, several lists or every list with a segment, use merge tags, test two subjects, send a test, send or schedule it, and pause, resume, send to newcomers or retry what failed.
Templates and Branding
The branded email layout and its settings, the plain layout, campaign templates as starting points, and overriding Mailroom's email and page templates in your theme.
Automations
Emails that go out on their own when somebody signs up, confirms or gets a tag, with triggers, waits, emails, tags, lists and branches, the Welcome series recipe, and how people move through them.
Reports and Tracking
How opens and clicks are counted without storing anything about the reader, link tagging for your analytics, and the seven reports with their windows, CSV export and definitions.
Deliverability
The Health screen's checks for your domain, transport and list, the settings behind them, deliverability alerts, deliverability:check, bounces and complaints, and the suppression list.
Unsubscribe and Preferences
The links at the foot of every campaign, the unsubscribe page and which lists it leaves, the mail client's one-click button, the preference center, and view in browser.
Privacy
What Mailroom keeps about a subscriber and what it never stores, exporting one person's data, erasing an address, and how long everything is kept.
Subscribe API
The public subscribe endpoint as a JSON reference, with every field, every answer, the honeypot and rate limit, how the source is recorded, and a server-side relay behind trusted proxies.
Jobs and Cron
The job queue, the worker and the scheduler line with its PATH, the drain after a request, what a worker run does, retries, emails held for a site URL, the daily housekeeping, and how to tell the worker is running.
Configuration
Every Mailroom setting, tab by tab, with its label, default and what it does.
CLI Reference
Every bin/plugin mailroom command, its arguments and options, and when to run it.
REST API
Mailroom's admin routes under /api/v1/mailroom, how to authenticate, which permission each needs, and the routes grouped by screen.
MCP
Run your newsletter from an AI client through grav-mcp, with every Mailroom tool, the permission it needs, and the routes that have none.
Troubleshooting
Start from status and the Health screen, then fix the common problems - no site URL, the worker not running, mail not arriving, provider webhooks refused, signups rate limited, and people who cannot be added.