Provenance
Research
What this guide was written from, and what was decided along the way.
Sources
Every statement in this guide was checked against the module's own files rather than against the design documents, which in several places describe intentions that changed during the build.
| Guide section | Written from |
|---|---|
| Getting Started | controllers/Webmail_account.php, views/webmail/account.php, libraries/Webmail_credential_vault.php |
| Daily Use | controllers/Webmail.php, views/webmail/_island_app.php, helpers/webmail_helper.php |
| Administration | controllers/Webmail_settings.php, libraries/Webmail_connection_tester.php, libraries/Webmail_host_policy.php |
| Reference | config/permissions.php, config/system_logs.php, config/webmail.php, migrations/, language/english/webmail_lang.php |
| Scheduled jobs | jobs/WebmailOutboxRetryJob.php, jobs/WebmailCleanupJob.php |
Decisions worth knowing
Test before save
The design package contradicted itself: the security specification required that a rejected password never be written, while the backend specification described storing first and testing afterwards. The security reading was implemented on all three write paths — self-service, administrator, and bulk import — because retired credential rows are kept deliberately, so a password stored by mistake would be stored permanently.
No local mail store
Nothing about a message is kept in ERPat. The one exception is temporary: the raw text of a message you just sent, held only if filing it into Sent failed, and discarded as soon as that succeeds or the retention window passes.
The owner of a mailbox is fixed
Credentials are attached to the mailbox rather than to the person, so allowing the owner to be edited would let a mailbox — and its working password — be reassigned. That would be a way to read someone's mail without ever knowing their password, so reassignment is delete-and-recreate, which revokes the credential on the way through.
Folder roles come from the server first
Which folder is “Sent” is read from what the server declares, falling back to name matching only when it declares nothing. Where two folders could both claim a role, the declared one wins, then the shallower path, then alphabetical order — a fixed order, so the same mailbox always resolves the same way rather than appearing to move mail between folders.
Known limits
- The composer saves to Drafts (append-then-supersede, keyed on Message-ID). Re-opening a saved draft for further editing is not implemented.
- Search does not cover message bodies.
- Attachment size is reported from the message's own encoding and may differ slightly from the file on disk.
- Very large mailboxes page in fixed batches; there is no jump-to-date.