Home

plMail documentation

The handbook. README says what plMail is and gets you to a running instance; this covers everything after that — every feature and how to use it, how to install it on whatever you have, how to register the Google and Microsoft applications it talks to, and how the parts work underneath.

Mirrored to the GitHub wiki, which is generated from these files. Edit them here; browser edits to the wiki are overwritten by the next mirror.

If you want to	Start at
Use a feature	Using plMail
Install or run it	Installing and running
Connect Gmail, Outlook or a CalDAV server	Providers
Understand or extend the internals	How it works

---

Using plMail

One page per area. Each ends with links into How it works for the mechanism behind it.

Page	What it covers
Mail	Reading, threads, labels, search and its operators, snooze, attachments, composing, signatures, emoji and inline images, scheduled send, read receipts, drafts, undo send
Accounts and aliases	Adding Gmail, Outlook and IMAP accounts, sending aliases, per-account settings
Account health	What is broken and what fixes it, reconnecting an account without losing its mail, the two ways push breaks
Filters	Condition trees, actions, the plain-English restatement, applying a rule to mail that already arrived
Calendar	The four views and the time grid, creating and editing events, recurrence, editing one occurrence, the docked pane
Invitations and events from mail	RSVP, events extracted from invitations and from ordinary prose, proposals, Happening Soon
Reminders	Setting alerts, how they are delivered, what a fresh install needs before they arrive
Connected calendars	Subscribing to Google, Microsoft and CalDAV calendars, two-way sync, ICS import, export and feed subscriptions, duplicate meetings
Sharing and booking	Share links and what each reveals, appointment pages, how a booking arrives
Files and integrations	Attaching from and saving to Drive, Photos, OneDrive, Dropbox, Nextcloud, Immich and Paperless-ngx
Security	Changing your password, two-factor authentication, recovery codes, remembered devices, app passwords, sessions
Other clients	Connecting a JMAP client, per-app passwords, the PWA and browser notifications
Appearance	Themes, custom colours and background, the live preview, what a list row shows, typeface and text size, per-pane density, import and export, language
Administration	Users and roles, switching an account off, enabling integrations, monitoring, queues and the version chip

Installing and running

Page	What it covers
Docker Compose	The supported path, start to finish
Platform notes	Linux, Windows via WSL2, macOS, and NAS boxes
Behind a reverse proxy	TLS, APP_PUBLIC_URL, TRUSTED_PROXIES, and what breaks without them
Configuration reference	Every environment variable, what it does and what happens if it is wrong
Backup and restore	What to back up, the encryption key, and restoring onto a new host
Configuration backup	Carrying an install's settings and credentials to another one, as one encrypted file
Upgrading	Migrations run on boot, what that means, and how to tell which build is running
Demo mode	Hosting a public demo: throwaway mailboxes, scripted mail, and what it switches off
Troubleshooting	Health checks, the queue, logs, and the failures that have actually happened

Providers

Each page names the exact console, the exact checkboxes and the exact redirect URIs.

Page	What it covers
Google	Cloud project, OAuth client, scopes for mail and calendar, Pub/Sub for Gmail push, calendar watch channels and domain verification
Microsoft	Azure app registration, redirect URIs, delegated permissions, tenant choice, Graph subscriptions
IMAP and SMTP	Plain mailboxes, IDLE, and the settings servers disagree about
CalDAV	Discovery, app passwords, and the servers that have been tested
ICS feeds	Subscribing to a published calendar by URL, and why some addresses are refused

How it works

Deeper than CONTRIBUTING's notes, and aimed at somebody auditing or extending plMail rather than running it.

Page	What it covers
Architecture	The layers, what lives where, and the rules that keep it that way
Mail ingest	The pipeline from provider to database, threading, categorisation
The calendar model	JSCalendar in jsonb, projected columns, occurrences, recurrence and overrides
The sync engine	The driver contract every provider implements, push channels, deduplication
AI assistance	The optional model features: what is off by default, and why the vector design avoids pgvector
Event extraction	How an invitation and how a sentence become a calendar entry
JMAP	What is implemented, what is deliberately not, and the id spaces
Security model	Encryption at rest, the secrets file, tokens, and what a public link can reach

Client authors should also read Client development, which is the protocol-level reference.

---

Conventions in these pages

• Commands are given as you would run them against a Compose deployment: docker compose exec php php bin/console <command>. Drop the prefix if you run plMail directly.
• Settings paths are written as Settings → Calendar → Connected calendars.
• A "things that bite" section at the end of a page collects the traps — the failure whose cause is not obvious from the symptom. They are there because they happened.

---

This page is generated from docs/README.md. Edit it there — changes made here are overwritten on the next push to main.