mirror of
https://github.com/karatektus/pl_mail.git
synced 2026-10-25 10:04:18 +00:00
Paul LütznerandClaude Opus 5
9835756aec
Seven columns used to divide whatever width there was, so a phone — or a narrow docked pane — gave each of them about fifty pixels, and a block showed its colour and little else. A column has a floor now: below the width where seven of them fit the grid pans sideways under an hour gutter that stays pinned, and four days are legible where none were. The time-grid shell's own header costed that fix as disproportionate once — "three scroll containers kept in step by JavaScript" — and it is not, because the three grids already share one scroller; all that was left was making each one's first cell sticky. A BLOCK IS TWO ROWS NOW. The time on one line with the calendar's colour as a bar down the left, the title under it, which is a whole title in a 96px column where one line was four characters of each. Day view keeps the single line and is told so rather than measured for it: a day column is the whole grid and is never the width that makes stacking worth doing. The agenda's date rail is gone. A day is a heading with its events under it, and the times sit in a lane that is a grid track rather than a fixed guess — sized against every time in the view, so it is 43px where an "all day" needs it and 33px where nothing does. The month gives up its words entirely below 5.5rem of cell and draws one bar per entry, which is what a phone can honestly say in forty pixels, and "N more" is gone along with a count that a variable cell height could never make true; the date is the link into the day instead. The grid opens on now rather than on a fixed 07:00, and a chip too small for its own title opens to it while the pointer rests on it. Width only: growing the height made the chip inside stop following its parent, and a click aimed at the middle of a Day-view block landed under the button and opened nothing. Two bugs fell out of the work. An all-day entry sorted below the morning east of UTC, because its start is a floating midnight in UTC while a timed one's is an instant — the time grid never showed it, since it puts all-day entries in a band of their own and never asks. And a grid block had never had a background at all: an inline colour was overriding the surface class written beside it, so the only paint it carried was a tenth of a calendar colour over whatever happened to be behind it. Opening on now has one consequence worth naming: a fixture at 10:00 is on screen all morning and scrolled above the viewport by the afternoon, and `boundingBox()` answers for an off-screen element with coordinates that land under the pinned day headings. calendar-timegrid's drag helpers scroll the block into view before measuring it now; without that the suite passed for hours and then did not, and the failure read as "dragging is broken". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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 |
|---|---|
| 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 |
|---|---|
| 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.